Для трансляции файла содержания необходимо в меню «File» пометить режим «Translation», затем открыть нужный файл содержания помощи (.cnt), выбрать нужную строку и произвести ее редактирование кнопкой «Edit». В этом случае нельзя менять имя раздела (topic IDs), имя файла помощи и тип окна.

4.РАЗРАБОТКА ПРИЛОЖЕНИЙ С КОНТЕКСТНОЙ ПОМОЩЬЮ

4.1.Вызов службы помощи

Компоненты среды разработки приложений Delphi поддерживают вызов контекстной помощи при нажатии на функциональную клавишу «F1». Для этого значением свойства «HelpContext» визуального компонента должен быть номер раздела, присвоенный ему в секции «Map» проекта. Для указания имени файла помощи программист должен заполнить поле «Help file» на странице «Application» диалогового окна «Project Options». В этом случае обработчик события для клавиши «F1» компонента, имеющего фокус ввода, используя значения свойства «HelpContext», формирует вызов службы помощи с указанием нужного раздела.

Для программирования вызовов службы помощи в обработчиках событий выбора из меню, инструментальных кнопок и других в состав методов компонента Tapplication входят

function HelpContext(Context: THelpContext): Boolean;

function HelpCommand(Command: Word; Data: Longint): Boolean;

HelpContext отображает раздел помощи, указанный параметром Context текущего файла помощи, заданного свойством

CurrentHelpFile.

Функция HelpCommand позволяет послать команду службе помощи WinHelp. Прежде чем послать команду службе помощи, оба метода генерируют событие OnHelp для активной формы или приложения. Посылку команды выполняет обработчик события: команда посылается, если обработчик не запланирован или обработчик явно вызывает службу помощи, например, с использованием функции

function WinHelp(hWndMain : HWND; HelpFile : Pchar: Command : Word; Data : Longint) : Boolean;

22

где параметры имеют следующий смысл:

hWndMain – дескриптор главного окна, из которого вызывается

При таком вызове службы помощи перед закрытием главного окна приложения необходимо вызвать службу помощи с командой HELP_QUIT. В противном случае окно помощи автоматически не закроется. Указанной команды не требуется, если помощь вызыва-

лась с командой HELP_CONTEXTPOPUP.

Перечень возможных команд, заданных своими константами, следующий:

HELP_COMMAND – исполняет последовательность макросов, заданных строкой вместо имени файла.

HELP_CONTENTS – демонстрирует раздел помощи, заданный опцией Contents в секции OPTIONS проекта помощи;

HELP_CONTEXT – демонстрирует замещающий раздел помощи, заданный своим номером в параметре Data. Номер должен быть специфицирован в секции MAP проекта.

HELP_CONTEXTPOPUP – демонстрирует всплывающий раздел помощи, заданный своим номером в параметре Data. Номер должен быть специфицирован в секции MAP проекта.

HELP_KEY – демонстрация раздела с заданным ключевым словом;

HELP_MULTIKEY– демонстрация раздела с заданным ключевым словом в таблице альтернативных ключей;

HELP_PARTIALKEY – демонстрация раздела с заданным ключевым словом. Если таких разделов несколько, то вызывается указатель;

HELP_QUIT – требование закрыть окно помощи; HELP_SETCONTENTS – задание раздела с оглавлением;

23

HELP_SETINDEX– задание таблицы ключевых слов для указателя разделов;

HELP_SETWINPOS – установка параметров окна службы помощи.

Как следует из перечня команд, служба помощи предоставляет программисту достаточно широкие возможности по взаимодействию с приложением. Можно программировать достаточно сложные сценарии взаимодействия приложения и службы помощи, например, для создания экспертов, управляющих последовательностью манипуляций.

При написании обработчиков событий программист может использовать вызов службы помощи с использованием функции

WinExec(CommandLine : PChar; CmdShow : Word) : Word;

где CommandLine – команда операционной системы; CmdShow – режим показа главного окна приложения [2].

В этом случае командная строка задается следующим синтаксисом:

winhlp32.exe [[-H] [-G[n]] [-W window-name] [-K keyword] [-N contextnum]

[-I topic-id] [-P pop-up-id] HLP-filename]

Ключи для управления режимами работы службы помощи имеют следующий смысл:

• -G[n] – создать конфигурационный файл (.gid) и закончить работу. Если задано числовое значение, то оно определяет, какой вид имеет таблица для выбора раздела при старте файла помощи;

•-H – показать, как пользоваться помощью;

•-I topic-id – показать заданный именем раздел помощи;

•-K keyword – показать заданный ключевым словом раздел помощи;

•-N context-num – показать заданный контекстным номером раздел помощи;

• -P pop-up-id – показать заданный именем всплывающий раздел помощи. Необходимо использовать совместно с ключами –P, -I или -N, как показано в примерах:

WINHLP32 -P -I EXEC_WINHELP HCW.HLP WINHLP32 -P -N 311 MYFILE.HLP

24

• -W window-name – показать раздел в заданном окне;

•HLP-filename – задать имя файла помощи. Если имя не задано, то появляется диалоговое окно выбора файла.

При поставке программного обеспечения вместе с приложением

следует переносить на целевую машину следующие файлы службы помощи:

group list).

4.2. Использование макрокоманд

Служба помощи WinHelp позволяет использовать макрокоманды для улучшения функциональности встроенной помощи приложения. При разработке файлов помощи автор может разместить макрокоманды в различных точках:

•в проекте помощи для срабатывания макрокоманд при открытии файла помощи или некоторого окна;

•в проекте помощи для срабатывания макрокоманд при выборе некоторого раздела из указателя (секция «Options», страница

«Macros»);

•в разделе исходного файла при вставке сноски «!» для срабатывания при открытии этого раздела;

•в файле оглавления помощи (.cnt) для срабатывания при двойном щелчке по пиктограмме этого раздела;

•в проекте помощи конфигурированием меню и кнопок для срабатывания макрокоманд при их выборе пользователем;

•в разделах исходного файла при использовании чувствительных областей (ссылок) для срабатывания макрокоманд при выборе области пользователем.

Макрокоманды имеют следующий достаточно простой синтак-

сис:

<Имя макрокоманды>([<Параметр>[, <Параметр>]…])

Имя макрокоманды нечувствительно к выбору регистра. Параметры должны быть числами или строками и разделяться запятыми. Если последний параметр равен нулю или пустой строке, то он мо-

25

жет быть опущен. Если параметров нет, то скобки опускать нельзя. В этом случае вызов макрокоманды производится, например, выражением Exit(). Числовые параметры задаются в десятичной или шестнадцатеричной системах счисления, например, 0x40 и 64 задают одинаковое значение. Строки, как правило, не требуют использования кавычек, но при необходимости можно использовать как двойные, так и одинарные кавычки. При использовании в строках специальных символов (‘, “, \) им должен предшествовать символ «\» – обратная косая черта. При записи имен файлов можно использовать символ «/».

При записи последовательности макрокоманд их можно разделять символами «:» (двоеточие) или «;» (точка с запятой). Макросы исполняются последовательно в порядке их записи в строке.

При использовании макрокоманд в среде Help Workshop определенные в ней макрокоманды передаются в службу помощи с использованием сокращенных имен. Если макрокоманды передаются из приложения, то программист сам должен следить за использованием сокращенных имен, использовать кавычки для строковых параметров и передавать все параметры макросов, включая нулевые и пустые строки.

Все макрокоманды, понимаемые службой помощи WinHelp, разбиты на следующие группы:

Подробную информацию о параметрах описываемых ниже макрокоманд можно получить в службе помощи программы Help Workshop.

Макрокоманды для кнопок используются для доступа к стандартным, создания новых или изменения функций кнопок службы помощи. В состав этой группы входят:

• ChangeEnable – назначить новую функцию кнопке и сделать ее активной;

26

удаления клавиатурных макросов (акселераторов). В состав этой группы входят:

•JumpContents – перейти к разделу оглавления текущего файла помощи;

•JumpContext – перейти к разделу, заданному номером контекста;

• UpdateWindow – показать раздел в заданном окне и вернуть фокус ввода начальному окну.

27

Использование следующих макрокоманд позволяет производить манипуляции с меню и их позициями:

•ChangeItemBinding – изменить связанную с пунктом меню макрокоманду;

•CheckItem Displays – пометить маркером пункт меню;

разделов помощи:

•CloseSecondarys – закрыть все окна помощи за исключением теку-

28

Примеры использования в исходном тексте помощи (RTF-файл) макрокоманд для связи с чувствительной областью приведены ниже.

Режим окна!HelpOnTop()

Дополнительная информация!ALink(network printing; local printing)

В примерах символы чувствительной области должны иметь двойное подчеркивание, а символы, начиная с «!» и до конца строки, должны иметь скрытый стиль.

Для расширения стандартного набора макрокоманд, предопределенных в службе помощи Winhelp, можно использовать библиотеки динамической загрузки (DLL). Создаются эти библиотеки стандартным для MS Windows способом, например, с использованием среды Borland Pascal for Windows или Borland C. Для использования некоторой функции из DLL в качестве макрокоманды необходимо произвести ее регистрацию макрокомандой

RegisterRoutine(DLL-name, function-name, format-spec)

где DLL-name – имя библиотечного файла; function-name – имя библиотечной функции;

format-spec – описание типов параметров, передаваемых функ-

ции.

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

U – число без знака;

I – число со знаком; S – строка;

v– неопределенный тип;

=– символ, предшествующий этому знаку, определяет тип результирующего параметра.

Пример регистрации в секции проекта [CONFIG] макрокоманды для использования диалогового окна из набора функций API приведен ниже.

[CONFIG]

RegisterRoutine("user32.dll", "MessageBox", "USSU")

29