Операционная система Microsoft Windows 3.1 для программиста. Дополнительные главы

4.4. Макрокоманды

В этом разделе мы кратко рассмотрим средство расширения справочной системы Windows, позволяющее наращивать практически неограниченно ее и без того широкие возможности - макрокоманды.

Компилятор Help Compiler распознает значительное количество встроенных в справочную систему макрокоманд, с помощью которых можно модифицировать меню и Toolbar, добавляя или удаляя строки меню и кнопки, выполнять переходы между разделами и поиск разделов, запускать произвольные приложения Windows и вызывать функции из внешних DLL-библиотек.

Макрокоманда имеет имя и параметры, указанные в скобках. Параметр может быть текстовой строкой или числом (десятичным или шестнадцатиричным, в последнем случае перед числом должны находится символы 0x). Каждый параметр, заданный в виде текстовой строки, должен быть взят в кавычки:

ExecProgram("testapp.exe",0)

Допустимы вложенные вызовы макрокоманд, однако в этом случае для внутренних макрокоманд вместо обычных кавычек следует использовать символы (`) и ('):

CreateButton("start","&Start App","ExecProgram(`app.exe',0)")

Символ (`) находится на той же клавише, где и символ (~) ("тильда"). Эта клавиша находится возле клавиши <Tab>. Символ (') вы сможете найти на той клавише, где расположен символ двойной кавычки (").

Если вам нужно вставить в текстовую строку параметра макрокоманды символы ("), (`), ('), (\), то перед ними необходимо расположить символ (\).

Вызов макрокоманды

Как вызвать макрокоманду?

Для этого существует несколько способов.

Во-первых, можно вызвать одну или несколько макрокоманд при загрузке hlp-файла. Такие макрокоманды могут выполнять инициализирующие функции, нужные для работы со всеми разделами справочной системы. Примером может послужить вызов макрокоманды BrowseButtons в разделе CONFIG файла проекта справочной системы hlpfile.hpj:

[CONFIG]
BrowseButtons()

В разделе CONFIG можно указывать сразу несколько макрокоманд.

Во-вторых, можно запускать одну или несколько макрокоманд при отображении раздела справочной системы. Для этого имя макрокоманды необходимо оформить как подстрочную ссылку с идентификатором "!":

! BrowseButtons()

Для запуска нескольких макрокоманд их надо разделить символом ";":

! BrowseButtons();SaveMark("Key Assignment")

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

Здесь при выборе строки "Запустить часы" будет исполнена макрокоманда ExecProgram, предназначенная для запуска приложений. В данном случае будет запущено приложение clock.exe.

Список встроенных макрокоманд

В этом разделе мы приведем краткий справочник по встроенным макрокомандам справочной системы Windows.

About()

Отображение диалоговой панели "About...".

AddAccelerator(key, shift, "macro")

Назначение комбинации клавиш ускоренного запуска для указанной макрокоманды, т. е. создание акселератора.

Алиас: AA.

Параметры:

Annotate()

Вывод на экран диалоговой панели "Annotate".

AppendItem("menuid", "itemid", "itemname", "macro")

Добавление строки к меню, созданному макрокомандой InsertMenu.

Параметры:

Back()

Отображение предыдущего раздела (в списке просмотренных разделов).

BookmarkDefine()

Отображение диалоговой панели "Bookmark Define".

BookmarkMore()

Отображение диалоговой панели "More", отображаемой при выборе строки "More..." из меню "Bookmark" приложения winhelp.exe.

BrowseButtons()

Добавление в окно Toolbar приложения winhelp.exe кнопок последовательного просмотра разделов с обозначениями и (по умолчанию эти кнопки не создаются).

ChangeButtonBinding("buttonid", "buttonmacro")

С помощью этой макрокоманды можно закрепить за кнопкой "Help" указанную макрокоманду.

Алиас: CBB.

Параметры:

ChangeItemBinding("itemid", "itemmacro")

Эта команда предназначена для закрепления макрокоманды за заданной строкой меню.

Алиас: CIB.

Параметры:

CloseWindow("windowname")

Макрокоманда закрывает окно с именем windowname, которое может быть как основным окном приложения winhelp.exe, так и вторичным.

Contents()

Переход к разделу, выполняющему функции оглавления справочной системы.

CopyDialog()

Отображение на экране диалоговой панели "Copy", предназначенной для копирования всего раздела или его фрагмента в Clipboard.

CopyTopic()

Копирование текущего (отображаемого в главном окне) раздела в Clipboard.

CreateButton("buttonid", "name", "macro")

Создание новой кнопки в окне Toolbar приложения winhelp.exe.

Алиас: CB.

Параметры:

DeleteItem("itemid")

Удаление строки меню с идентификатором itemid.

DeleteMark("marktext")

Удаление отметки в тексте, созданной макрокомандой SaveMark.

DestroyButton("buttonid")

Удаление кнопки с идентификатором buttonid.

DisableButton("buttonid")

Блокирование кнопки с идентификатором buttonid.

Алиас: DB.

DisableItem("itemid")

Блокирование строки меню с идентификатором itemid.

Алиас: DI.

EnableButton("buttonid")

Разблокирование кнопки с идентификатором buttonid.

Алиас: EB.

EnableItem("itemid")

Разблокирование строки меню с идентификатором itemid.

Алиас: EI.

ExecProgram("cmd", "show")

Запуск приложения Windows.

Алиас: EP.

Параметры:

Exit()

Завершение работы приложения winhelp.exe.

FileOpen()

Отображение диалоговой панели "Open", которая обычно появляется при выборе из меню "File" приложения winhelp.exe строки "Open...".

FocusWindow("windowname")

Назначение фокуса ввода окну, указанному параметром windowname.

GoToMark("marktext")

Переход на отметку в тексте (закладку) с именем marktext, установленную макрокомандой SaveMark.

HelpOn()

Отображение содержимого справочной системы, содержащей информацию об использовании приложения winhelp.exe.

History()

Отображение диалоговой панели "History", позволяющей выбрать один из нескольких только что просмотренных разделов справочной системы.

IfThen(...)

Условный запуск макрокоманды. Обычно используется вместе с макрокомандой IsMark:

IfThen(IsMark("markertext", "macro")

Параметры:

IfThenElse(...)

Запуск одной из двух макрокоманд в зависимости от существования маркера. Обычно используется вместе с макрокомандой IsMark:

IfThenElse(IsMark("markertext", "macro1", "macro2")

Параметры:

InsertItem("menuid", "itemid", "itemname", "macro", "pos")

Вставка новой строки в существующее меню в заданной позиции.

Параметры:

InsertMenu("menuid", "menuname", pos)

Добавление нового временного меню к главному меню приложения winhelp.exe.

Параметры:

IsMark("marktext")

Эта макрокоманда проверяет, существует ли маркер (закладка), указанная в параметре marktext и определенная макрокомандой SaveMark. Используется совместно с макрокомандами IfThen и IfThenElse.

JumpContents("hlp_filename")

Отображение раздела, выполняющего роль оглавления справочной системы, расположенной в hlp-файле с именем hlp_filename.

JumpContext("filename", contextnumber)

Переход к разделу, номер контекста которого равен contextnumber. Расположение раздела (имя hlp-файла) определяется параметром filename.

Алиас: JC.

Параметры:

Немного о секции MAP и о номере контекста раздела.

Секция файла проекта справочной системы MAP предназначена для установки соответствия между строками контекста и номерами контекста. Номер контекста - это численное значение, которое используется приложением для ссылки на раздел справочной системы.

Приведем пример оформления секции MAP:

[MAP]
file_wnd      0x01
edit_wnd      0x02
view_wnd      0x03
content_topic 100

Для номеров контекста можно использовать шестнадцатиричные или десятичные числа.

Допускается также включать в секцию MAP incude-файлы в стандарте Си, содержащие определения констант. Для этого необходимо использовать обычный оператор #include:

#include <menuid.h>

JumpHelpOn()

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

JumpId("filename", "contextstring")

Переход к разделу с контекстом contextstring. Расположение раздела (имя hlp-файла) определяется параметром filename.

Алиас: JI.

Параметры:

JumpKeyword("filename", "keyword")

Поиск раздела по ключевому слову keyword. Расположение раздела (имя hlp-файла) определяется параметром filename.

Алиас: JK.

Параметры:

Next()

Переход к следующему разделу в разделах, расположенных последовательно.

Not(...)

Эта макрокоманда инвертирует результат проверки, выполняемой макрокомандой IsMark:

Not(IsMark("markertext"))

PopupContext("filename", contextnumber)

Отображение раздела, номер контекста которого равен contextnumber. Расположение раздела (имя hlp-файла) определяется параметром filename.

Алиас: PC.

Параметры:

PopupId("filename", "contextstring")

Отображение раздела с контекстом contextstring. Расположение раздела (имя hlp-файла) определяется параметром filename.

Алиас: PI.

Параметры:

PositionWindow(x, y, w, h, wndstate, "windowname")

Изменение размеров и расположения главного или вторичного окон приложения winhelp.exe.

Алиас: PW.

Параметры:

Prev()

Переход к предыдущему разделу в разделах, расположенных последовательно.

Print()

Печать содержимого текущего (отображаемого в главном окне) раздела на принтере.

PrinterSetup()

Установка параметров принтера с помощью диалоговой панели "Print Setup".

RegisterRoutine("DLLname", "functionname", "format")

Макрокоманда RegisterRoutine позволяет вам расширить набор макрокоманд, определив собственные макрокоманды. Вы можете создать макрокоманду в виде функции, находящейся в разработанной вами DLL-библиотеке. Перед использованием такую функцию необходимо зарегистрировать, вызвав макрокоманду RegisterRoutine. Лучшее место для вызова макрокоманды регистрации - раздел CONFIG файла проекта справочной системы, хотя вы можете зарегистрировать свою функцию в любое время до ее вызова.

Алиас: RR.

Параметры:

Строка описания параметров состоит из отдельных букв, соответствующих типу параметров функции:

SaveMark("marktext")

Эта макрокоманда сохраняет расположение текущего отображаемого раздела и файла в виде закладки или маркера, имеющего имя marktext.

Search()

Отображает диалоговую панель "Search", которая обычно появляется на экране, если нажать кнопку "Search" в окне Toolbar приложения winhelp.exe.

SetContents("filename", "contextnumber")

С помощью этой макрокоманды вы можете указать, что раздел, имеющий номер контекста contextnumber, должен использоваться в качестве оглавления справочной системы, расположенной в hlp-файле с именем filename.

Параметры:

SetHelpOnFile("filename")

Вы можете заместить справочную систему, содержащую сведения об использовании приложения winhelp.exe (расположенную в файле winhelp.hlp) на свою собственную. Для этого в качестве параметра макрокоманде SetHelpOnFile следует указать имя hlp-файла, замещающего файл winhelp.hlp.