Использование справки ваших VB приложениях

От переводчика

Рано или поздно встает необходимость создания справочной системы для Вашего приложения. В конце концов, наличие справочной системы придает программе завершенность и, в некотором роде, поднимает Ваш имидж, как программиста-профессионала. После некоторых поисков я нашел в Интернете (http://www.tanstaafl-software.com) хорошо написанную статью и думаю, что после перевода на русский, ее ценность становится для русскоязычных VB программистов более существенной.

• Примеры, приведенные в настоящем переводе, проверены и работают. Все мои примечания приведены в квадратных скобках, например [от переводчика]
• Автор оригинальной статьи - женщина, но я переводил от имени мужчины
• Со мной можно связаться через dvv@es.vladivostok.ru. (Добжинский Виталий)

Приготовления

В большинстве случаев работа с WinHelp из Вашего приложения осуществляется посредством вызовов функций WinAPI, являющихся частью операционной системы Windows. Перед использованием WinAPI функций их следует объявить в BAS модуле Вашего проекта. Я использую следующие объявления:

Public Declare Function WinHelpStr Lib "user32" Alias "WinHelpA" _ 
(ByVal hWnd As Long, ByVal lpHelpFile As String, _
ByVal wCommand As Long, ByVal dwData As String) As Long 
Public Declare Function WinHelpNum Lib "user32" Alias "WinHelpA" _
(ByVal hWnd As Long, ByVal lpHelpFile As String, _
ByVal wCommand As Long, ByVal dwData As Long) As Long 

Как Вы видите, я объявил функцию дважды. Последний параметр в списке объясняет причину. В зависимости от параметра wCommand параметр dwData может быть либо типа integer (32 битное значение типа long), либо строкой или структурой (32 битный указатель). Несмотря на то, что Вы можете использовать одно и тоже объявление для обоих типов вызова, Вам придется явно преобразовывать передаваемые параметры к соответствующему типу. Я нашел, что легче иметь два разных вызова для разных параметров (один для параметра типа integer и другой для строк)

Вам также понадобятся следующие константы, которые следует поместить в тот же модуль, где объявлена функция WinHelpA

Public Const HELP_CONTEXT = &H1
Public Const HELP_QUIT = &H2 
Public Const HELP_INDEX = &H3
Public Const HELP_CONTENTS = &H3& 
Public Const HELP_HELPONHELP = &H4 
Public Const HELP_SETINDEX = &H5 
Public Const HELP_SETCONTENTS = &H5& 
Public Const HELP_CONTEXTPOPUP = &H8& 
Public Const HELP_FORCEFILE = &H9& 
Public Const HELP_KEY = &H101 
Public Const HELP_COMMAND = &H102& 
Public Const HELP_PARTIALKEY = &H105& 
Public Const HELP_MULTIKEY = &H201& 
Public Const HELP_SETWINPOS = &H203& 
Public Const HELP_FINDER = &HB 

Вызов справочной системы из меню

Стандартный интерфейс приложений для Windows 95 предполагает (в соответствии с требованиями фирмы Microsoft), что единственной точкой для вызова справочной системы, является пункт меню Help одноименного меню Help [в приложениях MS Office пункт меню "Help" заменен на "?"]. После этого должно отобразится окно с содержанием файла справки. Эти действия могут быть выполнены вот таким кодом:

lReturn=WinHelpNum (hWnd, sHelpFile, HELP_FINDER, 0&)

Первый параметр , hWnd, должен быть указателем [handle] на главное окно Вашего приложения [или MDI формы в случае MDI интерфейса). Вам следует использовать одно и тоже значение hWnd при всех вызовах.

Второй параметр, sHelpFile, - это строка, содержащее имя файла справочной системы [расширение HLP]. Обычно, файл справки находится в том же каталоге, в котором находится EXE файл Вашего приложения. В связи с этим Вы можете не указывать путь к файлу, либо использовать следующие строки для формирования полного пути к HLP файлу:

sHelpFile=App.Path & "\myfile.hlp"

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

Вызов справки по нажатию кнопки

В сообществе разработчиков справочных систем такой вид помощи принято называть . Обычно, каждое окно диалога [BorderStyle-Fixed Dialog] должно содержать кнопку . После нажатия кнопки пользователь получает справку, описывающую отображаемый в настоящий момент диалог. В те времена, когда справочной системы What's This [справка, отображаемая после того, как пользователь нажимает кнопку ?, расположенную в правом верхнем углу диалога, а затем щелкает по непонятному элементу формы] не было, отображаемое окно помощи содержало экранный снимок диалога. Если Вы используете режим What's This, то нет необходимости помещать в файл справки экранный снимок окна диалога. Вот такой пример кода может использоваться для вызова справки:

lReturn=WinHelpNum (hWnd, sHelpFile, HELP_CONTEXT, lContextID)

Параметр hWnd мы уже рассмотрели, sHelpFile содержит имя файла справочной системы (и может также указывать наименование окна, в котором следует отобразить помощь). Параметр lContextID содержит номер топика, который обычно указан в свойстве HelpContextID формы

Справочная система What's This

Справочная система What'sThis - это новшество, представленное впервые в новом пользовательском интерфейсе Windows 95 (но работает и в Windows NT). В сообществе разработчиков справочных систем такой вид помощи принято называть . Вы можете использовать этот вид помощи в качестве расширенных tooltip [подсказки, возникающие при задержке указателя мыши над каким-либо элементом на панели инструментов]. Однако, в отличие от tooltip, справка What's This может содержать графические изображения. Для VB программистов нет необходимости использовать WinAPI для реализации помощи типа What's This. Следует лишь выполнить ряд простых действий.

В событие Form_Load (или в процедуре Sub Main) добавьте вот такой код:

App.HelpFile=App.Path & "\helpfile.hlp"

Для каждого элемента экранной формы создайте топик, описывающий его назначение. Каждому топику следует присвоить уникальный номер Некоторые элементы формы (например кнопки ОК или Отмена) могут иметь одинаковые топики.

Как Вы знаете, некоторые элементы формы могут выступать в качестве контейнеров (например, элемент FRAME). Каждый элемент, помещенный в контейнер, может иметь свой собственный контекстный ID, а контейнер - свой.

Свойству WhatThisHelpID (есть практически у всех элементов) каждого элемента формы присвойте номер топика, в котором описывается данный элемент формы. Затем установите свойства формы:

WhatThisHelp=True 
WhatThisButton=True 

Для вызова подсказки What's This программно, используйте такой код:

lReturn=WinHelpNum (hWnd, sHelpFile, _
HELP_CONTEXTPOPUP, lContextID) 

lContextID указывает номер топика в HLP файле. Этот код можно использовать при нажатии кнопки F1

Есть одна маленькая неприятность, которую придется обойти. Если Вы установили свойство формы WhatThisHelp=True, то клавиша F1 (в соответствии с документацией) должна перестать работать. Однако, она продолжает работать и при нажатии отображает контекстную подсказку по элементу формы, над которым расположен указатель мыши. Поэтому, если Вы хотите обеспечить контекстную подсказку именно по тому элементу формы, на который установлен фокус [а не по тому, над которым указатель мыши], то следует поступить так:

1. Установите свойство формы KeyPreview=True.

Таким образом, форма первой получает возможность обработать нажатие кнопки.

2. В событии KeyDown формы отследите клавишу F1. Как только клавиша перехвачена, установите свойство key preview в значение 0. [Сказать по правде, я не понял это предложение. Вот так определяется событие KeyDown:

Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)

Видимо, автор предлагает в коде установить KeyCode=0]

3. Затем используйте вызов WinAPI функции, в котором значение lContextID можно определить следующим образом:

Form.ActiveControl.WhatsThisHelpID ActiveForm.ActiveControl.WhatsThisHelpID
Screen. ActiveControl.WhatsThisHelpID

Если Вы хотите полностью запретить справку What'sThis для некоторого элемента формы, то установите

WhatsThisHelpID=-1

Завершаем работу

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

lReturn=WinHelpNum (hWnd, sHelpFile, HELP_QUIT, 0&)

В этом вызове важно учитывать, что значения hWnd и sHelpFile должны быть теми же, что и при вызове WinAPI функций.