Создание справочной системы. Часть 2

Вот справочное руководство, открывающееся при нажатии кнопки "Остров Рокки"

Рис. 9.26. Контекстная справка к элементу интерфейса

Метод Help, как видите, может с успехом использоваться в программном коде, позволяя организовать в документах Excel и Power Point выдачу собственных контекстных справок. К сожалению, в приложениях Word и Access такой способ не применим. Существует другой, более мощный способ решения этой проблемы, применимый для всех приложений. Он основан на непосредственном вызове функции API - HtmlHelp, которая реально обеспечивает работу со скомпилированным chm-файлом и всегда вызывается явно или неявно.

Использование функции API - HtmlHelp

Как и другие функции API, функция HtmlHelp написана на языке C и ее "родное" описание имеет следующий синтаксис:

• HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData) Параметры этой функции имеют следующий смысл:
• hwndCaller - задает описатель окна, вызываемого HtmlHelp, в котором будет появляться справка.
• pszFile - указывает HTML-файл, URL или chm-файл. За именем файла может следовать определение окна, отделенное от имени знаком ">".
• uCommand - задает команду, определяющую действие, выполняемое данной функцией.
• dwData - указывает данные, которые требуются для выполнения той или иной команды.

Список возможных команд велик. С двумя основными командами мы познакомились при тестировании chm-файла, создаваемого в среде HHW. Этими командами являются HH_DISPLAY_TOPIC и HH_HELP_CONTEXT. Обе команды отображают в окне справки HTML-файл, но пользуются разной информацией. Для первой команды параметр pszFile задает имя chm-файла, а параметр dwData должен указывать на файл с разделом справки, являющийся частью скомпилированного chm-файла. Команда HH_HELP_CONTEXT позволяет отобразить в окне справки HTML-файл, заданный числовым идентификатором. Параметр dwData в этом случае задает значение HelpContextID.

Функция HtmlHelp входит в состав библиотеки, определяющей HTML Help ActiveX элемент управления (HHCtrl.ocx). Она реализует некоторые функциональные возможности этого элемента. Я напомню, что этот ActiveX элемент входит в состав HTML Help Workshop.

Для того, чтобы эту функцию можно было вызывать в программном коде VBA, необходимо предварительно объявить ее в операторе DECLARE. Необходимо объявить также используемые константы, а в общем случае и типы данных. Основная проблема при этом состоит в том, чтобы правильно отобразить типы языка C на типы языка VB. Приведу два возможных варианта объявления функции HtmlHelp на VBA, которые использовались мной в экспериментах:

Public Const Myf = "e:\O2000\DsCd\HelpToWGC\WhatThisHelpToWGC.chm"
'Константы, необходимые для вызова API функции HtmlHelp
Public Const HH_DISPLAY_TOPIC = &H0 'Вызов по имени раздела
Public Const HH_HELP_CONTEXT = &HF	'Вызов по Context ID
'Описание API функции HtmlHelp
Public Declare Function HtmlHelp Lib "hhctrl.ocx" _
		Alias "HtmlHelpA" _
		(ByVal hwndCaller As Long, _
		 ByVal pszFile As String, _
		 ByVal uCommand As Long, _
		 dwData As Any) As Long
'Описание варианта API функции HtmlHelp
Public Declare Function HtmlHelpLongArg Lib "hhctrl.ocx" _
			Alias "HtmlHelpA" (ByVal hwndCaller As Long, _
			ByVal pszFile As String, ByVal uCommand As Long, _
			ByVal dwData As Long) As Long

Обратите внимание, в первом варианте тип параметра dwData описан как Any. В этом случае при вызове не проверяется тип передаваемых данных, и вся ответственность за корректность вызова лежит на программисте. Это описание функции является универсальным и позволяет вызывать любые возможные команды, доступные для функции HtmlHelp. Во втором варианте описания функции тип параметра dwData зафиксирован. Этот вариант может быть использован при вызове команды HH_HELP_CONTEXT, когда в качестве значения передается числовой идентификатор.

Для иллюстрации возможностей работы с функцией API я использовал предыдущий пример, заменив вызовы метода Help на вызов функции HtmlHelp:

Private Sub ToggleButton1_Click()
	'Выдача контекстной справки -	работает!!!
	'Глобальный параметр Myf задает путь к файлу справочного руководства
	'Второй параметр метода Help позволяет по HelpContextID определить нужный раздел
	
	If Me.ToggleButton1.Value Then
		'Call Application.Help(Myf, Me.ToggleButton1.HelpContextID)
		'Вызов API функции HtmlHelp
		Call HtmlHelpLongArg(0, Myf, HH_HELP_CONTEXT, Me.ToggleButton1.HelpContextID)
	End If
End Sub

Окно справки задается по умолчанию, все остальные параметры сохранили значение, используемое в методе Help. Замечу, что работа метода Help реально сводится к вызову функции HtmlHelp. Вот как выглядит теперь вызов контекстной справки в нашей игре, открытой в Excel:

Рис. 9.27. Вызов контекстной справки, использующий API функцию HtmlHelp

Осталось выполнить обратный экспорт модифицированной формы в Word и проверить работоспособность данного способа, что я и сделал. Смею Вас уверить, что все работает, как нужно, поскольку вызов функции API и в приложении Word остается вызовом функции API, - слон он и в Африке слон.