	Демо-версия сайт и интерфейс
	Документация все о системе
	Служба поддержки +7 (3412) 511419

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

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

Введение

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

WinHelp — Появилась вместе с Windows 3.0. Исходный формат базируется на RTF. Поддерживается всеми версиями Windows, но в настоящее время для новых приложений практически не используется.
HTML Help 1.x (далее «HH») — Вышла в 1997 г. вместе с IE4. Использует для тем формат HTML и движок IE. Входит в состав всех используемых в настоящее время версий Windows.
MS Help 2.x — Выпущена в начале 2002 г. Также использует формат HTML и движок IE. В основном используется для интеграции со справкой Visual Studio .NET
Longhorn Help — Новая справочная система, которая будет включена в Windows Longhorn. Подробнее — Introducing Windows "Longhorn" Help

Автором 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 и корректно прочитан компилятором.

Темы

Страницы справки (темы) для 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
    ...
End Enum

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)
    If Not CheckHelpFileExists() Then Exit Sub
    Dim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(mainForm, g_HelpFilePath, val)
End Sub

' <summary> 
' Показывает страницу справочной системы, соответствующую значению contextID. 
' </summary>
Public Sub ShowHelp(ByVal contextID As Integer)
    If Not CheckHelpFileExists() Then Exit Sub
    Dim id As Integer = contextID
    Dim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(mainForm, g_HelpFilePath, CType(15, HelpNavigator), id)
End Sub

' <summary> 
' Показывает страницу справочной системы, соответствующую значению contextID. 
' </summary>
Public Sub ShowHelp(ByVal parent As Control, ByVal contextID As Integer)
    If Not CheckHelpFileExists() Then Exit Sub
    Dim id As Integer = contextID
    Dim mainForm As Form = Common.g_ApplicationContext.MainForm
    Help.ShowHelp(parent, g_HelpFilePath, CType(15, HelpNavigator), id)
End Sub

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

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

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

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

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

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
End Enum

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

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

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. Вот некоторые из его возможностей:

Редактор проекта (.HHP).
Редактор содержания (.HHC) и предметного указателя (.HHK).
Утилита проверки связей в .CHM (Link Checker).
Сжатие .CHM.

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

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

Версия Windows      Версия HTMLHelp 
--------------      --------------- 
Windows 95          не содержит 
Windows 95 OSR2     не содержит 
Windows NT          не содержит 
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.

Ссылки

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

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

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

Никита Зимин,
ведущий разработчик компании «Деловые программы»

Вернуться к списку статей

CMS List: Обзор систем управления сайтами и программ для создания сайтов