Использование HTML Help в приложениях на Visual Basic

Эта статья впервые была опубликована на сайте www.relib.com

• Основы
• HTML Help Workshop
• Создание проекта Справки HTML Help
• Добавление оглавления и индексных файлов
• Параметры окна и HTMLHelp API
• Компиляция вашего проекта Справки
• Вызов Справки из VB
• Использование класса CHelp
• Заключение

Если вы когда-либо смотрели Справку в Internet Explorer (IE) последних версий, то наверняка задавались вопросом, как создать справочную систему для вашего приложения подобно этой? В этой статье рассказывается как сформировать систему html-справки, используя Microsoft HTML Help Workshop, и как вызвать из VB-приложения готовый справочный файл.

Впервые Microsoft представила HTML Help - новую справочную систему, основанную на html - в августе 1997 как замену WinHelp. Это было относительно ново и не использовалось в других приложениях, кроме IE. Однако, как мы можем сейчас видеть - все новые версии продуктов Microsoft используют HTML Help: начиная игрой "Пасьянс" и заканчивая операционной системой Windows 98. Чтобы использовать советы из данной статьи на вашем компьютере должен быть установлен как минимум IE 3.02 (для использования всех функций HTML Help вы нуждаетесь в одной из последних версий IE).

Основы

Типичное окно HTML Help состоит из трех основных частей, как показано на Рис.1. В верхней части панель инструментов, которая содержит кнопки управления. В левой нижней части - окно навигации, импортированное из ActiveX-компонента HHCtrl.OCX и предоставляющее возможности просмотра оглавления, индекса и функцию поиска. В правой нижней части - окно содержания, которое действует как контейнер для HTML документов.

Рис.1. Три части окна Справки Internet Explorer 4.0.

HTML Help Workshop

Для создания файлов HTML Help вы можете использовать специализированный редактор HTML Help Workshop, созданный Microsoft. HTML Help Workshop доступен для загрузки на сайте Microsoft. В этой части показывается, как сделать простую справочную систему с использованием этого инструмента. Прежде чем начать, установите HTML Help Workshop на вашу машину и посмотрите табл.1, дающую пояснения к различным типам файлов, используемых в HTML Help.

Табл.1. Файлы, используемые в HTML Help.

Extension	Type
HHP	Help project
HHC	Table of contents
HHK	Index
CHM	Compiled Help
HTM	Individual Help
H	Header files

Создание проекта Справки HTML Help

До того, как вы сможете начать формировать вашу систему Справки, вы должны создать все HTML-файлы, которые потребуются для создания справочного файла. Затем создайте каталог HTMLHelp и сохраните там подготовленные HTML-файлы - это будет каталог вашего проекта.

Теперь откройте HTML Help Workshop и выберите в меню пункт File | New. В появившемся диалоговом окне New выберите Project и щелкните OK. Запустившийся Мастер Проекта (New Project Wizard) предложит вам выполнить ряд шагов для создания вашего проекта. Убедитесь, что проверили опцию HTML Files в окне New Project-Existing Files и прибавили ваши HTML-файлы к создаваемому проекту. Щелкните кнопку Finish, чтобы создать проект. Рисунок 2 показывает типичное окно HTML Help Workshop.

Рис.2. Окно редактора HTML Help Workshop.

Главное окно HTML Help Workshop состоит из четырех закладок: Проект, Содержание, Индекс, Справка и набора кнопок для каждой закладки. Вы можете использовать закладку Проект (Project), чтобы изменить параметры проекта, добавить или удалить файлы содержания, изменить настройки окна и установить параметры для HTMLHelp API. Установка настроек окна и HTMLHelp API важна для VB разработчиков. Мы покажем вам позже как установить эти параметры.

Добавление оглавления и индексных файлов

Файл оглавления определяет содержание, которое вы будете видеть в закладке Contents в будущем справочном файле. Оглавление обычно организовано в виде дерева с разделами, подразделами и страницами.

Чтобы добавить файл оглавления к вашему проекту щелкните закладку Contents (Оглавление) и увидите диалог Table Of Contents Not Specified. Выберите Create A New Contents File, чтобы создать пустую таблицу файла оглавления. Теперь вы сможете прибавить ваше содержание, используя кнопки Insert Heading и Insert Page. В диалоговых окнах, которые появляются, когда вы выбираете эти параметры, вы можете сопоставить HTML-файлы с разделами и страницами. Вы можете также редактировать, удалять или реорганизовывать ваши разделы и страницы, используя кнопки Edit, Delete и Move Selection.

Индексный файл содержит ключевые слова, которые вы видите, когда щелкаете закладку Index. Для добавления индексного файла к вашему проекту щелкните закладку Index и увидите диалог Index Not Specified. Выберите Create New Index и создайте пустой индексный файл. Вы можете прибавлять ключевые слова, использующие кнопку Insert A Keyword и сопоставлять HTML-файл с этим ключевым словом. Вы можете также редактировать, удалять или реорганизовывать ключевые слова, используя кнопки Edit, Delete и Move Selection.

Параметры окна и HTMLHelp API

Параметры окна позволяют вам определять вид справочного окна при запуске. Вы можете определить, какие кнопки показывать на Панели Инструментов, какие закладки показывать на Панели Навигации и устанавливать другие свойства, которые изменяют вид справочного окна.

Когда вы вызываете HTMLHelp API из VB, вы можете обратиться к этим свойствам и показывать справочное окно в различных стилях. Кликните закладку Project, затем кнопку Add/Modify Window Definitions. В окне Add A New Window Type введите MyWindow (или любое другое название) и щелкните OK. В диалоговом окне Window Type вы можете выбрать различные закладки, чтобы изменить кнопки, стили и т.д. Кликнув OK, будет создано новое определение окна.

Если вам надо включить в ваш справочный файл закладку Search - кликните Панель Навигации и выберите Add Search Tab. Нажав OK - перед вами появится Мастер, который поможет создать функцию поиска. На втором шаге выберите Compile Full-text Search Information, чтобы позволить компилятору Справки сформировать ключевые слова для поиска.

Кнопка HTMLHelp API Information позволяет установить параметры контекстно-зависимой справки. Когда вы нажмете эту кнопку, вы увидите диалог HTMLHelp API information. Вы можете сопоставить файл заголовков, который определяет все контекстные идентификаторы, в закладке Map (Карта). Рис.3 показывает содержание типичного файла заголовков.

Рис.3. Файл заголовков, используемый HTMLHelp API.

Вы можете использовать закладку Alias, чтобы сопоставить константы идентификаторов контекстной Справки, определенные в заголовке HTML-файла, как показано на рис.4. Когда вы вызываете HTMLHelp из VB с константой идентификатора контекстной Справки, вы можете показать нужную тему Справки, связанную с этой константой.

Рис.4. Сопоставление идентификторов с HTML-файлами в закладке Alias.

Вы можете также устанавливать "всплывающий" текст используя закладку Text Pop-ups. Подробнее об этой возможности смотрите в он-лайн Справке по HTML Help Workshop.

Компиляция вашего проекта Справки

Прежде, чем вы начнете компилировать, нажмите кнопку Change Project Options в закладке Project и выберите Default File для вашего проекта в закладке General. Вы можете также кликнуть закладку Files, чтобы изменить название скомпилированного файла или проверить оглавление и индексные файлы. Нажмите кнопку Save All Project Files And Compile, чтобы откомпилировать ваш файл.

По умолчанию, ваш откомпилированный справочный файл будет иметь то же самое название как файл проекта с расширением CHM. Если в течении компиляции в вашем проекте встретятся какие-либо ошибки вы увидите их в правом окне. После успешной компиляции вы сможете вызывать вашу Справку из VB.

Вызов Справки из VB

Вы можете использовать API-функцию HTMLHelp, чтобы показывать справочные файлы из VB. Сейчас мы покажем вам, как использовать HTMLHelp API так, чтобы вы смогли многократно использовать это. Для начала создадим класс и назовем его CHelp. Добавьте следующий код а ваше VB-приложение:

' Constant declarations

Private Const HH_DISPLAY_TOPIC = &H0

Private Const HH_HELP_CONTEXT = &HF



' API declaration

Private Declare Function HtmlHelp Lib _

  "hhctrl.ocx" Alias "HtmlHelpA" _

  (ByVal hwndCaller As Long, _

  ByVal pszFile As String, _

  ByVal uCommand As Long, ByVal dwData As Long) _

  As Long

Public Sub Show(NewFile As String, _

  Optional WindowPane As String, Optional ContextID)



Dim strFile As String

Dim hRet As Long



strFile = NewFile



If Len(WindowPane) Then

'you need to include > symbol with the file name

  strFile = Trim(strFile) & _ ">"&Trim(WindowPane)

End If



If IsMissing(ContextID) Then

  hRet =HtmlHelp(0, strFile, _ HH_DISPLAY_TOPIC, _

    ByVal 0&)

Else

  hRet = HtmlHelp(0, strFile, _ HH_HELP_CONTEXT, _

  ContextID)

End If

End Sub

Использование класса CHelp

Как только вы создаете класса CHelp, все, что вы должны делать - вызов метода Show с именем откомпилированного файла в качестве первого параметра. Вы можете также передавать название HTML-файла, чтобы открыть его непосредственно в окне темы справки без Панели Навигации и Панели Инструментов.

Следующий пример показывает, как вызвать метод Show в процедуре события Click кнопки cmdShow. Вы можете попробовать вызов с другими параметрами, чтобы управлять окном Справки.

Private Sub cmdShow_Click()



Dim strFile As String

Dim objHelp As CHelp

    

Set objHelp = New CHelp

    

strFile = App.Path & "\HelpFiles\HTMLHelp.chm"



Call objHelp.Show(strFile, "MyWindow")



Set objHelp = Nothing

End Sub

Заключение

HTML Help - справочная система нового уровня, которая придаст вашему приложению современный вид. Так как в ее основе лежит HTML, то вы можете включать в вашу справку изображения, видеоролики, анимацию и звук. Возможности бесконечны.

Дополнительную информацию Вы можете получить в компании Interface Ltd.

Обсудить на форуме Microsoft
Отправить ссылку на страницу по e-mail