Электронная библиотека книг Александра Фролова и Григория Фролова.
Shop2You.ru Создайте свой интернет-магазин
Библиотека
Братьев
Фроловых

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

© Александр Фролов, Григорий Фролов
Том 17, М.: Диалог-МИФИ, 1994, 287 стр.

[Назад] [Содеожание] [Дальше]

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.

Параметры:

Параметр Описание
key Виртуальный код клавиши ускоренного запуска макрокоманды
shift Использование дополнительных клавиш сдвига:0 клавиши сдвига не используются;1 <Shift>2 <Ctrl>3 <Shift+Ctrl>4 <Alt>5 <Alt+Shift>6 <Alt+Ctrl>7 <Shift+Alt+Ctrl>
macro Имя макрокоманды, которая будет выполнена после того как пользователь нажмет комбинацию клавиш, заданную первыми двумя параметрами

Annotate()

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

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

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

Параметры:

Параметр Описание
menuid Имя меню, использованное в макрокоманде InsertMenu
itemid Имя, идентифицирующее строку меню
itemname Текстовая строка, отображаемая в добавляемой строке меню
macro Имя макрокоманды, которая будет выполнена после того как пользователь выберет из меню добавленную макрокомандой AppendItem строку

Back()

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

BookmarkDefine()

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

BookmarkMore()

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

BrowseButtons()

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

ChangeButtonBinding("buttonid", "buttonmacro")

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

Алиас: CBB.

Параметры:

Параметр Описание
buttonid Идентификатор кнопки, использованный при ее создании макрокомандой CreateButton, или один из встроенных идентификаторов стандартных кнопок: btn_contents, btn_search, btn_back, btn_history, btn_previous, btn_next
buttonmacro Имя макрокоманды, которая будет выполнена, когда пользователь нажмет на кнопку

ChangeItemBinding("itemid", "itemmacro")

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

Алиас: CIB.

Параметры:

Параметр Описание
itemid Идентификатор строки меню, присвоенный макрокомандой AppendItem
itemmacro Имя макрокоманды, которая будет выполнена, когда пользователь выберет указанную строку

CloseWindow("windowname")

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

Contents()

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

CopyDialog()

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

CopyTopic()

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

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

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

Алиас: CB.

Параметры:

Параметр Описание
buttonid Идентификатор создаваемой кнопки
name Текстовая строка, которая появится на кнопке
macro Имя макрокоманды, которая будет выполнена, когда пользователь выберет созданную кнопку

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.

Параметры:

Параметр Описание
cmd Командная строка для запуска (с параметрами запуска)
show Способ отображения окна запускаемого приложения:0 нормальное;1 минимизированное;2 максимизированное

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")

Параметры:

Параметр Описание
markertext Маркер, который проверяется макрокомандой IsMark
macro Имя макрокоманды, которая будет выполнена, если указанный маркер существует

IfThenElse(...)

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

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

Параметры:

Параметр Описание
markertext Маркер, который проверяется макрокомандой IsMark
macro1 Имя макрокоманды, которая будет выполнена, если указанный маркер существует
macro2 Имя макрокоманды, которая будет выполнена, если указанный маркер не существует

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

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

Параметры:

Параметр Описание
menuid Имя меню, использованное в макрокоманде InsertMenu, или одно из имен стандартных меню: mnu_file, mnu_edit, mnu_bookmark, mnu_helpon.
itemid Имя, идентифицирующее строку меню
itemname Текстовая строка, отображаемая в новой строке меню
macro Имя макрокоманды, которая будет выполнена после того как пользователь выберет из меню вставленную строку
pos Позиция, где будет вставлена строка. Значение 0 соответствует самой верхней позиции в меню

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

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

Параметры:

Параметр Описание
menuid Идентификатор добавляемого меню
menuname Текстовая строка названия меню
pos Позиция, где будет вставлено меню. Значение 0 соответствует самой левой позиции в главном меню приложения winhelp.exe

IsMark("marktext")

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

JumpContents("hlp_filename")

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

JumpContext("filename", contextnumber)

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

Алиас: JC.

Параметры:

Параметр Описание
filename Имя hlp-файла
contextnumber Номер контекста раздела в указанном hlp-файле. Этот номер должен быть определен в разделе MAP файла проекта *.hpj справочной системы

Немного о секции 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.

Параметры:

Параметр Описание
filename Имя hlp-файла
contextstring Строка контекста раздела, на который выполняется переход

JumpKeyword("filename", "keyword")

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

Алиас: JK.

Параметры:

Параметр Описание
filename Имя hlp-файла
keyword Ключевое слово, по которому выполняется поиск раздела справочной системы

Next()

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

Not(...)

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

Not(IsMark("markertext"))

PopupContext("filename", contextnumber)

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

Алиас: PC.

Параметры:

Параметр Описание
filename Имя hlp-файла
contextnumber Номер раздела в указанном hlp-файле. Этот номер должен быть определен в разделе MAP файла проекта *.hpj справочной системы

PopupId("filename", "contextstring")

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

Алиас: PI.

Параметры:

Параметр Описание
filename Имя hlp-файла
contextstring Строка контекста отображаемого раздела

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

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

Алиас: PW.

Параметры:

Параметр Описание
x X-координата верхнего левого угла окна (значение параметров x, y, w, h может находиться в диапазоне от 0 до 1024)
y Y-координата верхнего левого угла окна
w Высота окна
h Ширина окна
wndstate Состояние окна:0 нормальное;1 максимизированное
windowname Имя окна (главному окну приложения winhelp.exe соответствует имя "main")

Prev()

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

Print()

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

PrinterSetup()

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

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

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

Алиас: RR.

Параметры:

Параметр Описание
DLLname Имя DLL-библиотеки, из которой выполняется вызов функции
functionname Имя функции
format Описание формата параметров.

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

Буква в строке формата Тип параметра
u unsigned short
U unsigned long
i short int
I long int
s near char *
S far char *
v void

SaveMark("marktext")

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

Search()

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

SetContents("filename", "contextnumber")

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

Параметры:

Параметр Описание
filename Имя hlp-файла
contextnumber Номер раздела в указанном hlp-файле. Этот номер должен быть определен в разделе MAP файла проекта *.hpj справочной системы

SetHelpOnFile("filename")

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

[Назад] [Содеожание] [Дальше]