Применение Microsoft® HTML Help в приложениях на Visual Basic 5.0.

Тезисы к докладу на DevCon98

Волков Юрий Ольгердович Независимый разработчик программного обеспечения, Москва
Email: programmer@iname.com

Секция: Средства разработки. Уровень доклада: 3 - технический по конкретной технологии

В представленной демонстрации рассказывается об опыте разработки коммерческого приложения, использующего Microsoft® HTML Help в качестве справочной системы приложения. Результат демонстрируется исполнением реального законченного приложения. (В качестве примера демонстрируется то же приложение, что и в предыдущем докладе: "Применение DirectX в приложениях на Visual Basic 5.0").

Доступ к исполняемому модулю HTML Help осуществлён с помощью API без использования компонентов третьих фирм.

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

1. Что же такое HTML Help?

Microsoft® HTML Help предствляет собой набор средств для обеспечения создания полноценной справочной системы в стандарте HTML, а также для получения возможности группировки и поиска в Интернет.

HTML Help создан как преемник WinHelp. Средства обращения к HTML Help (API), а также базовое средство разработки: HTML Help Workshop - аналогичны имеющимся для WinHelp. Имеется утилита преобразования проекта WinHelp в проект HTML Help.

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

Доступ к системе HTML Help возможен и через Интернет. В этом случае, однако, если Вы используете скомпилированный файл, то он должен быть загружен целиком перед началом вывода первого окна справки.

По идее Microsoft использование HTML Help не требует наличия у пользователя браузера Интернет для просмотра справки, однако на начало мая 1998 известно, что дистрибутив для распространения HTML Help без браузера (hhrunx.exe) находится в стадии разработки. Проверяйте http://www.microsoft.com/workshop/author/htmlhelp/ .

Примеры использования HTML Help в качестве справочной системы: MS Internet Explorer 4.0 и его компоненты. Конкретно - ищите файлы с расширением .chm.

Один из примеров использования HTML Help в Интернет для получения расширяемого оглавления документов - материалы предыдущей конференции: DevCon97

2. Компоненты HTML Help

3. Ресурсы Интернет

4. HTML Help Workshop

5. Обеспечение контекстной справки из VB

Применение API позволяет, в частности получить контекстную справку. Вызов всех команд API HTML Help осуществляется через одну функцию, которую можно описать так:

  Private Declare Function HtmlHelp 
       Lib "hhctrl.ocx" Alias "HtmlHelpA" (
         ByVal hwndCaller As Long, 
         ByVal pszFile As String, 
         ByVal uCommand As Long, 
         ByVal dwData As Any) As Long

В простейшем случае для вызова страницы по её имени из формы MyForm можно применить команду:

Const HH_DISPLAY_TOPIC As Long = 0
Dim Hwnd As Long
Hwnd = HtmlHelp( MyForm.hwnd, 
                 "TkmW.chm", 
                 HH_DISPLAY_TOPIC, "Welcome.htm")

Для получения контекстной справки по значению свойства HelpContextID (элементов управления или формы) для текущего активного элемента можно использовать следующий код (один на весь проект), вызываемый по нажатию клавиши F1:

Const HH_HELP_CONTEXT As Long = &HF
Dim frm1 As Form     ' активная форма
Dim ctl1 As Control	  ' активный элемент управления
Dim lngContextID As Long
Dim mhWnd As Long
  On Error Resume Next
  Set frm1 = Screen.ActiveForm
  If Err = 0 Then
    Set ctl1 = frm1.ActiveControl
    If Err <> 0 Then Set ctl1 = Nothing
    If Not (ctl1 Is Nothing) Then
      lngContextID = ctl1.HelpContextID
    End If
    If lngContextID = 0 Then
      ' если не задан идентификатор контекстной справки для
      ' элемента управления, то используем справку для формы
      lngContextID = frm1.HelpContextID
    End If
    mhWnd = HtmlHelp(frm1.hwnd, "TkmW.chm", HH_HELP_CONTEXT, lngContextID)
  End If

6. Единая система идентификаторов контекста

Одни и те же идентификаторы контекста, (имена которых рекомендуется начинать с IDH_ ), встречаются в трёх местах Вашего проекта (VB + HTML Help). В целях облегчения развития программы удобно специально для этих целей создать три файла:

1. HelpMap.bas - содержит описания констант и входит в состав проекта VB ( например TkmW.vbp). Пример содержимого этого файла:

  Attribute VB_Name = "HelpMap"
  Global Const IDH_About = 10
  Global Const IDH_Plasma = 4
  Global Const IDH_PlasmaEdit = IDH_Plasma
  Global Const IDH_Welcome = 11

2. HelpMap.h - то же самое описание констант, но в формате C. Этот файл включается в секцию [MAP] файла проекта HTML Help ( TkmW.hhp ):

  [MAP]
  #include HelpMap.h

Содержимое файла HelpMap.h:

  #define IDH_About 10
  #define IDH_Plasma 4
  #define IDH_PlasmaEdit 4
  #define IDH_Welcome 11

3. HelpAlias.h - устанавливает соответствие между идентификаторами контекста и именами файлов гипертекстовых страниц. Этот файл включается в секцию [ALIAS] файла проекта HTML Help ( TkmW.hhp ):

  [ALIAS]
  #include HelpAlias.h

Содержимое файла HelpAlias.h:

  IDH_About = About.htm
  IDH_Plasma = Plasma.htm
  IDH_PlasmaEdit = Plasma.htm
  IDH_Welcome = Welcome.htm

HTML Help Workshop позволяет находить часть ошибок соответствия в HelpMap.h и HelpAlias.h, поддержание же файла HelpMap.bas в соответствии с HelpMap.h - дело автора. Похоже, надо написать утилиту для автоматической конвертации первого во второй.

7. Что же получилось?

Демонстрация работы программы, ответы на вопросы.