Контекстная справка на HTML Help

На примерах для VB.NET

Автор: Никита Зимин
RussianIT

Источник: RSDN Magazine #6-2004
Опубликовано: 19.03.2005
Версия текста: 1.0
Введение
Создание простейшей справки
Проект
Содержание и предметный указатель
Темы
Сборка (компиляция)
Контекстная справка
Вызов из программы
Вызов средствами Win32
Helpware FAR
Распространение продукта
Ссылки

Введение

История справочных систем от Microsoft насчитывает четыре версии:

Автором WinHelp и HH является Ральф Уолден (Ralph Walden), работавший на MS с 1987 до начала 1998 года. После ухода из MS он основал KeyWorks Software.

На настоящий момент наиболее удобным форматом, с точки зрения как разработки (наличие обширного инструментария), так и распространения (поддержка операционной системой), несомненно, является HTML Help 1.3.

Создание простейшей справки

Проект

Основным файлом справки является файл проекта (.HHP), описывающий опции компиляции и содержащий ссылки на все другие файлы, участвующие при сборке. Структура .HHP-файла – это структура INI-файла. Обычно нет необходимости редактировать файл проекта вручную — все, что нужно, может быть задано с помощью HTML Help Workshop (HHW). Новый проект может быть создан с помощью мастера — командой File > New > Project.

Файл проекта может быть создан и вручную. Вот пример типичного .HHP-файла:

[OPTIONS]
Binary Index=No
Compatibility=1.1 or later
Compiled file=MyAppHelp.chm
Contents file=MyAppHelp.hhc
Default Window=main
Default topic=HTML\Welcome.htm
Display compile progress=No
Index file=MyAppHelp.hhk
Language=0x419 Русский
Title=Мое приложение - Справка

[WINDOWS]
main=,"MyAppHelp.hhc","MyAppHelp.hhk","HTML\Welcome.htm","HTML\Welcome.htm",,,,,0x72520,,0x60305e,[112,11,896,658],0x100b0000,,,,,,0

[FILES]
HTML\Manual.css

Содержание и предметный указатель

Содержание справки редактируется на вкладке Contents и содержится в .HHC-файле. Структура содержания — иерархическая, каждый элемент поименован, имеет иконку (выбирается из списка), к элементу содержания может быть привязана одна или несколько тем (HTML-файлов).

Предметный указатель описывается на вкладке Index и хранится в .HHK-файле.

ПРЕДУПРЕЖДЕНИЕ

.HHC и .HHK сохраняются из HHW в виде, похожем на HTML, но здесь есть одна тонкость. Если вы хотите формировать .HHC или .HHK сторонними средствами, НЕДОСТАТОЧНО, чтобы это был XML, сформированный по тому же DTD —файл должен содержать ту же шапку и такие же отступы в каждой строке — лишь в этом случае он будет принят в HHW и корректно прочитан компилятором.

ПРИМЕЧАНИЕ

Если вы хотите иметь возможность использовать в .HHC- и .HHK-файлах русский язык, не редактируйте эти файлы в HTML WorkShop – это средство не умеет работать с русским языком. – прим.ред.

Темы

Страницы справки (темы) для HH — это обычные HTML-страницы, для создания которых может быть использован любой HTML-редактор — начиная от простейших Notepad и FAR+Colorer до монстрообразных MS Word и FrontPage.

Рекомендуется описать используемые во всех топиках стили с помощью CSS и поместить описание в отдельном файле — например, Manual.css — который подключать в заголовке каждой темы:

<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=windows-1251">
<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
</HEAD>
<BODY>
  ...

Сборка (компиляция)

Для сборки готового .CHM файла из HHW используйте команду File > Compile или соответствующую кнопку на панели команд.

В некоторых случаях может понадобиться возможность сборки справочника в автоматическом режиме — используйте утилиту hhc.exe с параметром — именем файла проекта:

"C:\Program Files\HTML Help Workshop\hhc.exe" AMADocBase.hhp

Контекстная справка

Будем считать, что у нас уже написаны HTML-файлы, описывающие отдельные объекты программы (главное окно, диалоги и т.п.), и нам остается только связать программу с этими файлами.

1. В проекте на VB.NET заводим отдельный модуль (например, HelpSystem). В нем мы описываем все вещи в программе, для которых у нас будет контекстная справка, например:

      Public
      Enum HelpContextID
    FormMain = 2001
    FormLogin = 2002
    FormError = 3010
    FormWait = 3030
    ...
EndEnum

2. В проекте справки заводим файл Map.h вида:

      #define FormMain                2001
#define FormLogin               2002
#define FormError               3010
#define FormWait                3030
...

т.е. здесь мы описываем то же, что и в HelpContextID enum, но в другом формате. HelpContextID enum и Map.h должны быть «синхронизированы» — чтобы ID в программе и в справке всегда совпадали. В C/C++ это было проще — формат файла Map.h был специально приспособлен для того, чтобы входной файл для справки совпадал с файлом, используемым в самой программе.

В проекте справки заводим файл Aliases.h вида:

FormLogin=HTML\2_2.htm
FormMain=HTML\3_1.htm#FormMain
FormWait=HTML\2_2.htm
...

Здесь задается отображение символического имени, заданного в Map.h, на конкретную тему и место в ней.

Вызов контекстной справки происходит так: в HTML Help API передается идентификатор справки — целое число, которое определяется в HelpContextID enum — по нему (используя Map.h) определяется символическое имя, затем по символическому имени (используя Aliases.h) определяется тема, которая будет показана.

В файле проекта справки задаем ссылки на Aliases.h и Map.h:

[ALIAS]
#include Aliases.h

[MAP]
#include Map.h

3. В программе на VB.NET описываем вызов справки:

      ' <summary> Показывает TOC или Index справочной системы. </summary>
      ' <param name="val"> HelpNavigator.TableOfContents или HelpNavigator.Index </param>
      Public
      Sub ShowHelp(ByVal val As HelpNavigator)
    IfNot CheckHelpFileExists() ThenExitSubDim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(mainForm, g_HelpFilePath, val)
EndSub' <summary> 
' Показывает страницу справочной системы, соответствующую значению contextID. 
' </summary>PublicSub ShowHelp(ByVal contextID AsInteger)
    IfNot CheckHelpFileExists() ThenExitSubDim id AsInteger = contextID
    Dim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(mainForm, g_HelpFilePath, CType(15, HelpNavigator), id)
EndSub' <summary> 
' Показывает страницу справочной системы, соответствующую значению contextID. 
' </summary>PublicSub ShowHelp(ByVal parent As Control, ByVal contextID AsInteger)
    IfNot CheckHelpFileExists() ThenExitSubDim id AsInteger = contextID
    Dim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(parent, g_HelpFilePath, CType(15, HelpNavigator), id)
EndSub

Здесь g_HelpFilePath — глобальная переменная с полным путем к файлу справки. g_ApplicationContext — глобальная переменная с контекстом приложения, используется для получения главного окна — можно его получать любым другим способом.

Вызов из программы

Везде, где нужен вызов справки, расставляем вызовы вида:

        Private
        Sub btnHelp_Click(ByVal sender AsObject, _
    ByVal e As System.EventArgs) Handles btnHelp.Click
  HelpSystem.ShowHelp(Me, HelpContextID.FormContactProps)
EndSub

Вызов содержания справки и предметного указателя:

HelpSystem.ShowHelp(HelpNavigator.TableOfContents)
HelpSystem.ShowHelp(HelpNavigator.Index)

Вызов средствами Win32

Хотя класс System.Windows.Forms.Help и предоставляет необходимую функциональность, бывают случаи, когда ее недостаточно. Например, окно справки всегда лежит поверх окна основного приложения, переданного первым параметром в функцию ShowHelp(). Окно справки может занимать значительное место и закрывать большую часть окна приложения — поэтому может оказаться удобным, чтобы окно справки могло перекрываться окном основного приложения. Но функция ShowHelp() не имеет такой функциональности — вы не можете передать первым параметром Nothing, поскольку получите исключение. В таком случае придется воспользоваться функцией WinAPI:

        Public
        Enum HTMLHelpCommand
  HH_DISPLAY_TOPIC = 0
  HH_DISPLAY_TOC = 1
  HH_DISPLAY_INDEX = 2
  HH_DISPLAY_SEARCH = 3
  HH_HELP_CONTEXT = &HF
  HH_CLOSE_ALL = &H12
EndEnum

<DllImport("hhctrl.ocx", EntryPoint:="HtmlHelp", CharSet:=CharSet.Auto)> _
Function HTMLHelp( _
  ByVal hWndCaller As IntPtr, ByVal pszFile AsString, _
  ByVal uCommand AsInteger, ByVal dwData AsInteger) AsIntegerEndFunction

Собственно вызов выглядит так:

WinAPI.HTMLHelp(Nothing, filePath, HTMLHelpCommand.HH_HELP_CONTEXT, contextID)

WinAPI.HTMLHelp(Nothing, filePath, HTMLHelpCommand.HH_DISPLAY_TOC, 0)

Теперь все отлично — окно справки висит отдельно, работать в программе не мешает.

Helpware FAR

Основной недостаток HTML Help Workshop — это его непредсказуемость. HHW может неожиданно «вылететь» практически в любой момент — например, при сохранении содержания справки, которое вы долго и мучительно редактировали. Второй недостаток — крайне неудобный интерфейс — чтобы добавить новый пункт в содержание, требуется выполнить десяток действий. Все это кажется ерундой, пока вы делаете простую справку для первой версии вашей программы — и превращается в настоящую проблему, если нужно создать мощную справочную систему с сотнями тем.

К счастью, помимо HHW существуют и другие средства разработки HTML Help, среди которых я бы особо выделил Helpware FAR — бесплатный набор утилит для работы над справкой формата HH. Вот некоторые из его возможностей:

Распространение продукта

Практически все используемые в настоящее время версии Windows уже содержат HTMLHelp:

Версия Windows Версия HTMLHelp
Windows 95 не содержит
Windows 95 OSR2 не содержит
Windows NT 4 не содержит
Windows 98 1.1a
Windows 98 SE 1.21
Windows ME 1.32
Windows 2000 1.30
Windows 2000 SP1-3 1.31
Windows XP 1.33
Windows XP SP1 1.4
Windows XP SP2 1.4e

В Windows 95/98/NT можно установить HH с помощью дистрибутива HHUPD.EXE, который доступен после установки HHW. Для работы HH требуется IE 3.0 и выше. Для использования DHTML, очевидно, нужен IE версии 4, для XML понадобится IE версии 5 и выше. Последние версии IE включают в себя обновление HH — например, в состав IE 6.0 SP1 входит HH 1.4. Более подробно — см. HTML Help - Tech Info.

Ссылки

Общая информация

Инструментарий

Написание руководства пользователя


Эта статья опубликована в журнале RSDN Magazine #6-2004. Информацию о журнале можно найти здесь