Другие предметы \ Операционные системы

Взаимодействие со справочными файлами, страница 2

Обучающие иллюстрации

Обучающие иллюстрации усиливают принцип интерактивности справочной системы Windows и помогают пользователю выполнять сложные задачи, выступая в качестве проводника для определенного процесса. Приложение инициирует обучающие иллюстрации путем комбинирования флага HELP_TCARDс другой командой при вызове функции WinHelp. Справочная система Windows отображает запрашиваемый раздел, который обычно содержит одну или несколько кнопок, на которые пользователь может воздействовать. Когда пользователь выбирает одну из кнопок, либо выполняет некоторое другое действие, Windows отправляет приложению сообщение WM_TCARD, которое и указывает на это действие. Пример использования обучающих иллюстраций приводится ниже в описании сообщения WM_TCARD.

Функции справочных файлов и описания сообщений

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

Таблица 28.2 Перечень функций справочных файлов и сообщений

Функция

Назначение

GetMenuContextHelpId

Извлекает идентификатор контекстной справки указанного меню

GetWindowContextHelpId

Извлекает идентификатор контекстной справки указанного меню или элемента управления

SefMenuContextHelpId

Устанавливает идентификатор контекстной справки указанного меню

SetWindowContextHelpId

Устанавливает идентификатор контекстной справки указанного окна или элемента управления

WinHelp

Запускает механизм справочной системы Windows

Сообщение

Назначение

WM_HELP

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

WM_TCARD

Обеспечивает взаимодействие между приложением и механизмом справочной системы Windows в течение сеанса работы с обучающими иллюстрациями

GetMenuContextHelpId                       •  Windows 98   •  Windows 2000

Описание

Функция GetMenuContextHelpId извлекает идентификатор контекстной справки указанного меню. Значение этого идентификатора устанавливается с помощью функции SetMenuContextHelpId.

Синтаксис

DWORD GetMenuContextHeIpId( HMENU hMenu )

Параметры hMenu

HMENU: Дескриптор меню, для которого возвращается контекстный идентификатор.

Возвращаемое значение

DWORD: В случае успешного завершения возвращается контекстный идентификатор указанного меню, а иначе — 0.

Включаемый файл

winuser.h

См. также

SetMenuContextHelpId

GetWindowContextHelpId                   * Windows 98   + Windows 2000

Описание

Функция GetWindowContextHelpId извлекает идентификатор контекстной справки указанного окна или элемента управления. Значение этого идентификатора устанавливается с помощью функции SetWindowContextHelpId. Окно или элемент управления, для которого не установлен идентификатор контекстной справки, наследует идентификатор родительского объекта.

Синтаксис

DWORD GetWindowContextHelpId( HWND hWindow )

Параметры Л Window

HWND: Дескриптор окна или элемента управления для окна, контекстный идентификатор которого возвращается.

Возвращаемое значение

DWORD: При успешном завершении возвращается контекстный идентификатор указанного окна, в противном случае — 0.

Включаемый файл

winuser.h

См. также

SetWindowContextHelpId

SetMenuContextHelpId                       *• Windows 98   • Windows 2000

Описание

Функция SetMenuContextHelpId устанавливает идентификатор контекстной справки указанного меню. Значение этого идентификатора извлекается с использованием функции GetMenuContextHelpId. Доступ к контекстному идентификатору меню осуществляется через структуру HELPINFO в процессе обработки сообщения WMJHELP.

Синтаксис

BOOL SetMenuContextHelpId( HMENU hMenu, DWORD dwContextHelpID )

Параметры

hMenu

HMENU: Дескриптор меню, для которого устанавливается контекстный идентификатор.

dwContextHelpID

DWORD: Идентификатор контекстной справки. Это значение присваивается идентификатору контекстной справки пункта меню.

Возвращаемое значение

BOOL: При успешном завершении возвращается значение TRUE, в противном случае — FALSE.

Включаемый файл

winuser.h

См. также

GetMenuContextHelpId

SetWindowContextHelpId                    • Windows 98   • Windows 2000

Описание

Функция SetWindowContextHelpId устанавливает контекстный идентификатор указанного окна или элемента управления. Для извлечения значения этого идентификатора используется функция GetWindowContextHelpId. Окно или элемент управления с неустановленным контекстным идентификатором наследует идентификатор родительского объекта. Доступ к контекстному идентификатору реализуется через структуру HELPINFO в процессе обработки сообщения WM_HELP.

Синтаксис

BOOL SetWindowContextHelpId( HWND hWindow, DWORD dwContextHelpID )

Параметры

hWindow

HWND: Дескриптор окна или элемента управления для окна, контекстный идентификатор которого возвращается.

dwContextHelpID

DWORD: Контекстный идентификатор. Это значение присваивается контекстному идентификатору окна или элемента управления.

Возвращаемое значение

BOOL: При успешном завершении возвращается TRUE, в противном случае -FALSE.

Включаемый файл

winuser.h

См. также

GetWindowContextHelpId

WinHelp                                             • Windows 98   • Windows 2000

Описание

Функция WinHelp обеспечивает взаимодействие между справочной системой Windows и приложением. Она запускает Windows Help (W1NHLP32.EXE) и передает дополнительные данные, определяющие вид справки, запрашиваемой приложением. Приложение задает имя и, если необходимо, путь к справочному файлу. Перед закрытием окна, из которого запрашивалась справка, приложение должно вызвать функцию WinHelp с параметром uCommand, для которого установлено значение HELP_QUIT. Пока приложение не выполнит эти действия, процесс Windows Help не завершится. Если WinHelp была вызвана с командой HELP_CONTEXTPOPUP, в передаче HELP_QUIT нет необходимости.

Синтаксис

BOOL WinHeIp( HWND hWnd, LPCTSTR IpszHelpFile, UINT uCommand, DWORD dwData )

Параметры

hWnd

HWND: Дескриптор окна, запросившего справку. Обычно это главное окно приложения за исключением случаев, когда параметр uCommand имеет значение HELP_CONTEXTMENU или HELP_WM_HELP. При таких условиях это идентификатор элемента управления либо окна, о котором запрашивается справочная информация.

lpmHelpFik

LPCTSTR: Имя HLP-файла приложения. Имя файла может содержать символ "больше" (>), после которого следует имя окна. В таком случае справка будет отображаться во вспомогательном окне, тип которого указан в его имени. Имя вспомогательного окна должно быть указано в разделе WINDOWS HPJ-файла.

uCommand

UINT: Команда справочной системы Windows. Эта команда может принимать любое из значений, перечисленных в табл. 28.3.

dwData

DWORD: Дополнительные данные в соответствие с требованиями параметра uCommand.

Возвращаемое значение

BOOL: При успешном выполнении- возвращается значение TRUE, а в противном случае — FALSE.

Таблица 28.3 Значения uCommand

Значение

Описание

HELP_COMMAND

Исполняет макросы справочной системы. Параметр  dwData указывает на строку макросов справки, разделенных точками с запятой. Если макрос имеет как краткое, так и длинное имя, используется краткое имя.

HELP_CONTENTS

Указывает справочной системе Windows на необходимость отображения раздела, идентифицированного в HPJ-файле в качестве раздела содержимого. Обычно используется приложениями Windows 3.x, когда пользователь выполняет щелчок на пункте меню  Help Contents (Вызов справки). В приложениях Windows 95 и Windows NT 4.x  вместо HELP_CONTENTS должна использоваться команда HELP_FINDER.

HELP_CONTEXT

Указывает справочной системе Windows на необходимость отображения раздела, который связан с 32-разрядным контекстным идентификатором, переданным в параметре dwData.

HELP_CONTEXTMENU

Указывает справочной системе Windows на необходимость отображения меню справки для выбранного окна, а затем вывода связанного раздела справки во всплывающем окне. Параметр dwData указывает на массив пар DWORD. Первое значение DWORD в каждой паре служит идентификатором окна или элемента управления, а второе — контекстным идентификатором связанного раздела.

HELP_CONTEXTPOPUP

Указывает справочной системе Windows на необходимость отображения раздела, который связан 32-разрядным контекстным идентификатором, переданным в параметре dwData. Раздел отображается во всплывающем окне.

HELP_FINDER

Отображает список разделов справки.

HELP_FORCEFILE

Обеспечивает отображение справочной системой Windows требуемого HLP-файла. Если указанный HLP-файл не отображается,  Windows Help его открывает. В противном случае никаких действий не происходит.

HELP_HELPONHELP

Отображает файл WINHELP.HLP, предоставляющий справочную информацию об использовании справочной системы Windows. Обычно присутствует в приложениях Windows 3.x, обеспечивая реакцию на щелчок на опции меню Help On Using Help (Использование справки). В приложениях Windows 95 и Windows NT 4.x вместо HELP_HELPONHELP следует использовать команду HELP_FINDER.

HELP_INDEX

Отображает индекс справочного файла. Обычно используется в приложениях Windows 3.x, когда пользователь выполняет щелчок на опции меню Help Index (Содержание). В приложениях Windows 95 и Windows NT 4.x вместо HELP   INDEX следует применять команду HELP_FINDER.

HELP_KEY

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

HELP_MULTKEY

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

HELP_PARTIALKEY

Реализует в  HLP-файле поиск разделов, где встречается ключевое слово, на которое указывает параметр dwData. Если ключевому слову соответствует более одного раздела, отображается вкладка  Index (Предметный указатель). Чтобы справочная система отобразила эту вкладку, можно также задать в качестве ключевого слова пустую строку.

HELP_QUIT

Сообщает справочной системе   Windows, что приложение завершило использование справки.  HLP-файл закрывается, а окно справки — удаляется.

HELP_SETCONTENTS

Устанавливает контекстный идентификатор для раздела содержания. Справочная система Windows отобразит этот раздел в ответ на команду HELP   CONTENTS либо на щелчок на кнопке Contents (Содержание) в окне справки. Параметр dwData определяет 32-разрядный контекстный идентификатор для раздела, который необходимо выделить для содержания.

HELP_SETINDEX

Указывает таблицу ключевых слов, которая должна отображаться в диалоговом окне Help Topics (Разделы справки).

HELP_SETPOPUP_POS

Устанавливает позицию следующего всплывающего окна. Параметр dwData определяет 32-разрядное значение, содержащее данные о позиции. Для объединения горизонтальных и вертикальных координат в единственное значение используется функция MAKELONG.

HELP_SETWINPOS

Устанавливает размер и позицию главного либо вспомогательного окна справки. Параметр dwData указывает на структуру HELPWININFO, описание которой приводится ниже.

HELP_TCARD

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

HELP_WM_HELP

Приложение может использовать эту команду в ответ на сообщение WM_HELP. В данном случае параметр hWnd должен представлять собой дескриптор элемента управления, передаваемый структуре HELPINFO. Параметр dwData указывает на массив пар DWORD. Первое значение DWORD каждой пары является идентификатором элемента управления, а второе — контекстным идентификатором раздела справки, отображаемого для данного элемента управления.

Включаемый файл                    winuser.h См. также           GetMenuContextHelpID, GetWindowContextHelpID, SetMenuContextHelpID, SetWindowContextHelpID Связанные сообщения WM_HELP, WMJTCARD Описание структуры HELPWININFO

typedef   struct { int        wStructSize;

int         x ;

int      y;

int        dx;

int         dy;

int        wMax;

TCHAR   rgchMember [2] ; }    HELPWININFO;

Члены wStructSize         

int: Размер структуры в байтах. х                         

int: Координата X верхнего левого 'угла окна йа экране.

y

int: Координата Y верхнего левого угла окна на экране.

dx

int: Ширина окна в пикселях.

dy

int: Высота окна в пикселях.

wMax

int: Указывает способ отображения окна. Этот член может представлять собой одно из состояний отображения, доступных через функцию ShowWindow.

rgchMember

ТСНАЩ2]: Имя окна.

Пример

Пример этой функции содержится в листинге 28.1.

Сообщение WM HELP                       • Windows 98   • Windows 2000

Описание

WM_HELP — сообщение, отправляемое приложению, когда пользователь запрашивает контекстно-зависимую справку. Это может быть результатом нажатия на клавишу F1 либо щелчка на значке Help (если таковой имеется) заголовка окна с последующим щелчком на элементе управления, окне или пункте меню. Обычно приложение отвечает на это сообщение,  генерируя  команду HELP WM HELP при помощи функции   WinHelp с использованием структуры HELPINFO.

Параметры

wParam

WPARAM: He используется.

IParam

LPHELPINFO: Указатель на структуру HELPINFO, идентифицирующую запрос справки. Описание структуры HELPINFO приводится ниже.

Возвращаемое значение

BOOL: Если приложение обрабатывает это сообщение, оно должно вернуть TRUE.

См. также

WinHelp

Связанные сообщения \VM_TCARD

Описание структуры HELPINFO

typedef      struct      tagHELPINFO

{ UINT              cbSize;

int                 iContextType;

int                  iCtrlld;

HANDLE         hltemHandle;

DWORD            dwContextld;

POINT           MousePos ; }    HELPINFO,    *LPHELPINFO;

Члены

cbSize

UINT: Размер структуры в байтах.

iContextfype

int: Тип контекста, для которого запрашивается справка. Если справка запрашивается для пункта меню, используется значение HELPINFO MENUITEM. Если справка запрашивается для элемента управления или окна, этот член принимает значение HELPINFO_WINDOW.

iCtrlld

int: Идентификатор окна либо элемента управления, если iContextType равно HELPINFO_WINDOW. В противном случае это идентификатор элемента меню.

hltemHandle

HANDLE: Дескриптор дочернего окна либо элемента управления, если iContextType равно HELPINFO_WINDOW. В противном случае это дескриптор связанного меню.

dwContextld

DWORD: Идентификатор контекстной справки окна или элемента управления.

MousePos

POINT: Координаты курсора мыши на экране.

Пример

Пример использования этого сообщения содержится в листинге 28.2.

Сообщение WM TCARD                     • Windows 98   • Windows 2000

Описание

Справочная   система   Windows   отправляет   приложению   сообщение WM_TCARD, когда пользователь выполняет щелчок на кнопке, связанной с макросом справки Tcard, либо другое действие в течение сеанса работы с обучающими иллюстрациями.

Параметры

wParam

WPARAM: Выполненное пользователем действие. Может принимать любое значение из перечисленных в табл. 28.4.

IParam

LPARAM: Дополнительные данные в зависимости от значения wParam.

Таблица 28.4 Значения параметра wParam сообщения WM_TCARD

Значение

Описание

HELP_TCARD_DATA

Пользователь щелкнул на кнопке. Параметр dwData содержит 32-разрядное значение, определенное автором справки.

HELP_TCARD_NEXT

Пользователь щелкнул на кнопке Next.

HELP_TCARD_OTHER_CALLER

Другое приложение запросило справку в форме обучающих иллюстраций.

IDABORT

Пользователь щелкнул на кнопке Abort (Прервать).

IDCANCEL

Пользователь щелкнул на кнопке Cancel  (Отмена).

IDCLOSE

Пользователь закрыл сеанс работы с обучающими иллюстрациями.

IDHELP

Пользователь щелкнул на кнопке Help (Справка).

IDIGNORE

Пользователь щелкнул на кнопке Ignore (Игнорировать).

IDNO

Пользователь щелкнул на кнопке No (Нет).

IDOK

Пользователь щелкнул на кнопке ОК.

IDRETRY

Пользователь щелкнул на кнопке Retry (Повтор).

IDYES

Пользователь щелкнул на кнопке Yes (Да).

Возвращаемое значение

LRESULT: Приложение должно возвращать значение 0.

См. также

WinHelp

Связанные сообщения

WM_HELP

Пример

В следующем примере инициируется сеанс использования справки в форме обучающих иллюстраций. Приложение отвечает на сообщения WM_TCARD со значениями IDOK, IDCANCEL, IDABORT параметра wParam. Кроме того, обрабатывается сообщение HELP_TCARD_DATA, связанное с выбором в течение сеанса соответствующего переключателя.

Си.    \local-sources\chap28\28-01.txt

Скачать файл