Основы офисного программирования и документы Word

Использование функции 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, - слон он и в Африке слон.

Содержание раздела