Работа с онлайн-справкой
Онлайн-справка может предоставляться в различных формах, от подробных концептуальных сведений до быстрых определений. В этом разделе содержатся следующие разделы.
Важный элемент пользовательского приложения легко доступен в веб-справке. Windows предоставляет функции и сообщения, которые в сочетании с приложением справки Windows упрощают реализацию онлайн-справки в вашем приложении. В этом обзоре рассматриваются элементы Windows, поддерживающие онлайн-помощь. В нем описывается, как использовать эти элементы для предоставления пользователям средств для запроса справки, а также объясняется, как использовать приложение справки Windows для отображения справки.
Большинство приложений под управлением Windows предоставляют справочную информацию онлайн в различных формах, начиная с концептуальной справки, объясняющей назначение функций приложения, и заканчивая всплывающей справкой, предоставляющей быстрые определения отдельным элементам в пользовательском интерфейсе приложения. Функции и сообщения используются для предоставления пользователям различных способов запроса доступа к этой информации. В следующих разделах описаны эти запросы на справку.
Большинство приложений предоставляет пользователям доступ к информации в разделе помощи через меню Help в главном окне. Когда пользователь выбирает элемент из меню справки, соответствующая процедура окна получает сообщение WM_COMMAND, определяющее выбранный элемент. Приложение отвечает, отображая соответствующую справочную информацию, такую как перечень тем справки, индекс или введение в использование приложения.
Windows предоставляет пользователю доступ к справке с клавиатуры, уведомляя приложение всякий раз, когда пользователь нажимает клавишу F1. Система отправляет сообщение WM_HELP окну, находящемуся в фокусе клавиатуры, когда пользователь нажимает клавишу. Если окно является дочерним окном (например, элементом управления в диалоговом окне), функция DefWindowProc передает сообщение родительскому окну. Если меню активно при нажатии клавиши F1, система отправляет сообщение в окно, связанное с меню. Приложение отвечает, отображая справочную информацию, связанную с окном, меню или элементом управления, которые имеют фокус или активны. Например, если пользователь выбирает элемент управления в диалоговом окне и нажимает клавишу F1, приложение отображает сведения о справке для этого элемента управления.
Параметр lParamWM_HELP — это указатель на структуру HELPINFO, содержащую подробные сведения о элементе, для которого запрашивается помощь. Вы используете эту информацию для определения темы справки для отображения. Структура HELPINFO также включает координаты курсора мыши во время нажатия клавиши. Эти сведения можно использовать для предоставления справки на основе расположения курсора мыши.
Windows предоставляет пользователю доступ к справке с мыши, уведомляя приложение всякий раз, когда пользователь нажимает правую кнопку мыши или щелкает окно, элемент управления или меню после нажатия кнопки "Вопрос" (?). Приложение отвечает, отображая сведения справки, связанные с заданным окном, элементом управления или меню.
Система отправляет WM_CONTEXTMENU сообщение, когда пользователь нажимает правую кнопку мыши. Окно, которое было щелкнуно, получает сообщение. Если окно является дочерним окном, например элементом управления, функция DefWindowProc передает сообщение родительскому окну. Сообщение WM_CONTEXTMENU указывает координаты курсора мыши. Координата x находится в младшем разряде слова параметра lParam, а координата y находится в старшем разряде. Если пользователь щелкнул элемент управления, параметр wParam является дескриптором элемента управления, полученного щелчком.
Система отправляет сообщение WM_HELP, когда пользователь щелкает элемент в окне после нажатия кнопки "Вопрос" (?), которая отображается в строке заголовка окна. При создании окна можно добавить кнопку "Вопрос" в заголовок, указав стиль WS_EX_CONTEXTHELP в функции CreateWindowEx. Параметр lParamWM_HELP — это указатель на структуру HELPINFO, содержащую подробные сведения об элементе, для которого запрашивается помощь, включая координаты курсора мыши во время нажатия кнопки мыши.
Кнопка "Вопрос" рекомендуется использовать только в диалоговых окнах. В прошлом приложения предоставляли пользователям доступ к справочной информации о диалоговом окне, предоставляя кнопку Справка в диалоговом окне. Этот метод больше не рекомендуется. Используйте вместо этого кнопку "Вопрос".
Когда приложение получит запрос на помощь, оно должно отобразить соответствующую справочную информацию. Поскольку приложение Windows Help обеспечивает единообразный пользовательский интерфейс, рекомендуется использовать Windows Help вместо других методов. Чтобы направить справку Windows для отображения информации, приложение использует функцию WinHelp, указав такие сведения, как информация для отображения и форма окна, в котором она должна отображаться. В следующих разделах объясняется, как использовать WinHelp для отображения справочной информации.
Чтобы просмотреть сведения о справке, необходимо указать файл справки при вызове функции WinHelp. Файл справки должен иметь формат файла справки Windows (HLP) и один или несколько разделов. Каждая тема — это отдельная единица информации, например концептуальное описание, набор инструкций, рисунок, определение глоссария и т. д. Разделы должны быть уникальным образом определены, чтобы справка Windows может находить их всякий раз, когда они запрашиваются. Внутри системы справки Windows используются идентификаторы тем для поиска тем, но приложения чаще всего используют идентификаторы контекста (уникальные целые значения) для указания отображаемых тем. Автор файла справки должен явно сопоставить идентификаторы контекста с идентификаторами раздела в разделе [MAP] файла проекта, используемого для создания файла справки.
Если указать файл справки, но не указать путь, WinHelp ищет файл справки в каталоге справки или в каталоге, указанном переменной среды PATH. Кроме того, WinHelp может найти файл справки, имя которого указано в следующем расположении реестра:
HKEY_LOCAL_MACHINE
Software
Microsoft
Windows
Help
Чтобы воспользоваться преимуществами реестра, необходимо создать имя значения, которое имеет то же имя, что и файл справки. Значение, назначенное данному имени, должно быть каталогом, в котором находится файл справки.
Если WinHelp не удается найти указанный файл справки, отобразится диалоговое окно, позволяющее пользователю указать расположение файла справки. Поскольку WinHelp сохраняет сведения о расположении в реестре, ему больше не требуется запрашивать расположение того же файла справки.
Дополнительные сведения о разработке и создании файла справки см. в документации, предоставленной средствами разработки.
В следующем примере используется функция WinHelp для запуска приложения справки Windows и открытия файла справки на странице "Содержание".
HWND hwnd; // main window handle
BOOL bResult // for checking Boolean function result
bResult = WinHelp(hWnd, "WINNT.HLP", HELP_CONTENTS, 0L);
В следующем примере открывается файл справки пользователя, выполняется поиск файла для раздела, связанного со строкой ключевого слова, а затем отображается раздел.
HWND hwnd; // main window handle
BOOL bResult // for checking Boolean function result
bResult = WinHelp(hWnd, "WINNT.HLP", HELP_KEY, (DWORD) "finding topics");
Диалоговое окно Справка по темам можно отобразить, вызвав функцию WinHelp с командой HELP_FINDER. Диалоговое окно справки позволяет пользователю выбирать темы для отображения, просматривая названия тем, ключевые слова, связанные с темами, или слова и фразы, найденные в темах. Приложения обычно отображают это диалоговое окно, когда пользователь выбирает команду, например разделы справки, в меню справки. Приложение также может отобразить это диалоговое окно, если пользователь нажимает клавишу, когда определенное окно, элемент управления или меню в приложении не имеют фокуса или неактивны.
В прошлом приложения использовали команды HELP_CONTENTS и HELP_INDEX с функцией WinHelp для отображения раздела "Содержимое" и индекса ключевых слов файла справки. Эти команды больше не рекомендуются. Используйте вместо этого команду HELP_FINDER.
Вы можете отобразить определенный раздел, вызвав функцию WinHelp с помощью команды HELP_CONTEXT и указав идентификатор контекста для раздела. Приложения обычно используют команду HELP_CONTEXT в ответ на запросы пользователей к темам, содержащим концептуальную информацию или процедурную справку, а не сведения о определенном элементе управления или меню. В таких случаях пользователь может продолжать просматривать файл справки, который ищет связанные сведения, прежде чем вернуться в приложение.
Команда HELP_CONTEXT вызывает регулярный экземпляр справки Windows, что позволяет пользователю находить другие разделы в файле справки. Обычно отображается главное окно справки, включающее строку заголовка, системное меню, кнопки минимизации и максимизации, главное меню, необязательную панель навигации, границу размера и клиентскую область. Текст выбранного раздела отображается в клиентской области, и пользователь может перемещаться по файлу справки с помощью горячих ссылок или кнопок навигации в главном окне. Обычный режим справки Windows также можно использовать для показа справки в одном или нескольких дополнительных окнах вместо главного окна.
Вы можете отобразить всплывающий раздел, содержащий сведения для определенного элемента управления или меню, вызвав функцию WinHelp с помощью команды HELP_WM_HELP или HELP_CONTEXTMENU. Эти команды отображают раздел в всплывающем окне рядом с соответствующим элементом управления или меню. Чтобы пользователь сразу же вернулся к работе в приложении, всплывающее окно будет уничтожено, как только пользователь нажимает клавишу или нажимает левую кнопку мыши.
При обработке сообщений WM_HELP для окон управления используется команда HELP_WM_HELP. Поскольку большинство элементов управления передают сообщение WM_HELP функции DefWindowProc, соответствующая процедура диалогового окна (или родительская процедура окна) обрабатывает это сообщение. Вместо того чтобы задать определенный идентификатор контекста, процедура диалогового окна должна передавать массив пар идентификаторов элементов управления и контекста WinHelp вместе с дескриптором элемента управления, указанным в hItemHandle член структуры HELPINFO, переданной с сообщением WM_HELP. Функция определяет идентификатор элемента управления, для которого был создан WM_HELP сообщение и использует соответствующий идентификатор контекста для отображения соответствующего раздела.
При обработке сообщений WM_CONTEXTMENU используется команда HELP_CONTEXTMENU. Так как большинство элементов управления передают сообщение WM_CONTEXTMENU функции DefWindowProc, соответствующая процедура диалогового окна (или родительская процедура окна) обрабатывает это сообщение. Процедура задает массив пар идентификаторов элементов управления и контекста; он также задает дескриптор в параметре wParam при вызове WinHelp, чтобы функция могла выбрать соответствующий идентификатор контекста из массива и отобразить соответствующий раздел. В отличие от команды HELP_WM_HELP, HELP_CONTEXTMENU сначала отображает в меню команду 'Что это?'. Если пользователь выбирает команду, WinHelp отображает раздел. В противном случае запрос отменен.
Вы также можете отображать всплывающие разделы с помощью команды HELP_CONTEXTPOPUP и указания идентификатора контекста раздела. Эта команда аналогична команде HELP_CONTEXT, но вызывает всплывающий экземпляр справки Windows, используемый HELP_WM_HELP и HELP_CONTEXTMENU. Приложения могут использовать эту команду в ответ на WM_HELP сообщения для отображения справки по меню и окнам, которые не являются элементами управления в диалоговом окне. Чтобы использовать эту команду наиболее эффективно, приложение должно назначать идентификаторы контекста этим меню и окнам.
Вы можете назначить идентификатор контекста любому окну или меню в приложении. При создании сообщения WM_HELP система включает идентификатор контекста в структуру HELPINFO, которая передается в родительское окно в сообщении WM_HELP. Затем родительское окно может передать идентификатор контекста WinHelp, чтобы отобразить запрошенный раздел справки.
Функция SetWindowContextHelpId используется для назначения идентификатора контекста окну или элементу управления и функции SetMenuContextHelpId для назначения идентификатора контекста меню. Вы можете получить идентификатор контекста для окна или меню с помощью функции GetWindowContextHelpId или GetMenuContextHelpId.
Вы можете разрешить пользователю находить и просматривать разделы, назначая ключевые слова темам в файле справки. Ключевое слово — это просто строка, связанная с одним или несколькими разделами. Справка Windows собирает все ключевые слова в файле справки, помещает их в таблицу и отображает их в списке индексов диалогового окна разделы справки. Когда пользователь выбирает ключевое слово, справка Windows отображает связанный раздел справки или, если с ключевым словом связано несколько разделов, отображает список тем, из которых пользователь может выбрать.
В приложении можно использовать команду HELP_KEY, HELP_PARTIALKEY или HELP_MULTIKEY с функцией WinHelp для поиска и отображения тем справки на основе целых или частичных ключевых слов. Вы указываете команду, строку ключевого слова, файл справки и дескриптор окна владельца. Во всех случаях, если найдено одно совпадение, WinHelp отображает нужный раздел. Если найдено несколько совпадений, функция отображает диалоговое окно "Найденные темы", а пользователь может выбрать, какой раздел нужно просмотреть. Если совпадение не найдено, WinHelp отображает список индексов (для HELP_KEY и HELP_PARTIALKEY) или отображает сообщение об ошибке (для HELP_MULTIKEY).
Приложение может искать несколько ключевых слов в одном вызове WinHelp, разделив ключевые слова точкой с запятой. (Поиск нескольких ключевых слов не поддерживается для файлов справки, созданных для Windows версии 3.x) Он также может искать ключевые слова в нескольких файлах справки, если указанный файл справки содержит файл содержимого (Cnt), содержащий команды :Index или :Link. С помощью команды HELP_KEY WinHelp осуществляет поиск ключевых слов во всех файлах, указанных этими командами. С помощью команд HELP_MULTIKEY и HELP_PARTIALKEY функция выполняет поиск всех файлов, кроме указанных командами :Link.
По умолчанию справка Windows распознает только таблицу ключевых слов, определяемую символом сноски K в исходном файле справки. Вы можете использовать справку Windows для создания дополнительных таблиц ключевых слов, добавив в исходный файл справки символ сноски, отличающийся от K, вместе с определением ключевого слова. (Однако символ сноски A зарезервирован.) При создании файла справки необходимо определить дополнительные таблицы ключевых слов с помощью инструкций MULTIKEY в разделе [OPTIONS] файла проекта.
Приложение может использовать команду HELP_SETINDEX с функцией WinHelp, чтобы направить Справочную систему Windows для отображения таблицы ключевых слов, отличающуюся от K в списке индекса. Для того чтобы приложение направило справку Windows на поиск ключевого слова в альтернативной таблице ключевых слов, оно может использовать команду HELP_MULTIKEY. Вы указываете ключевое слово и таблицу ключевых слов в структуре MULTIKEYHELP, которая передается в WinHelp.
Если WinHelp отображает раздел, он отображает его в окне, указанном в сноске ">" для раздела, в окне, указанном командой :Base в файле содержимого или в главном окне. Если главное окно уже открыто для другого файла справки при вызове WinHelp, функция скрывает главное окно при поиске. В этом случае отмена диалоговых окон Найденные Темы и Темы Справки закрывает главное окно.
Главное окно приложения справки Windows называется основным окном. Справка Windows также может отображать разделы справки в дополнительном окне. В отличие от основного окна справки, дополнительное окно не содержит строку меню. Вы можете включить панель навигации в дополнительное окно и добавить кнопки в панель. Вы также можете выбрать автоматическую регулировку высоты дополнительного окна Windows Help, чтобы оно соответствовало теме.
Необходимо определить вторичные окна в разделе проекта справки [WINDOWS], указав имя и, при необходимости, начальный размер и положение каждого окна. Вы можете заставить приложение справки Windows отображать раздел в дополнительном окне, вставив угловую скобку (>) и имя, определенное для дополнительного окна, в имя файла справки. Результирующая строка затем передается в функцию WinHelp.
Приложение может изменить размер и положение основного или дополнительного окна, указав адрес структуры HELPWININFO и команду HELP_SETWINPOS в вызове WinHelp. HELPWININFO указывает имя окна и его новое размер и положение.
Используя карточку обучения, приложение может отображать последовательность инструкций, направляющих пользователя на выполнение задачи. Карточка обучения обычно состоит из текста, который объясняет конкретный шаг и кнопки, связанные с макросами TCard, которые позволяют пользователю сообщать приложению, что делать дальше. Карточки обучения могут отображаться только в дополнительных окнах и не должны содержать горячие ссылки на другие разделы в файле справки.
Приложение инициирует экземпляр справочной карты для обучения Windows, вызвав функцию WinHelp и указав команду HELP_TCARD в комбинации с другой командой, например HELP_CONTEXT. Затем, когда пользователь нажимает кнопку на карточке обучения, щелкает по горячей точке, назначенной макросу TCard, или закрывает карточку обучения, справка Windows уведомляет приложение, отправляя ему сообщение WM_TCARD. Параметр wParam определяет действие кнопки или пользователя, а параметр lParam содержит дополнительные данные, значение которого зависит от значения wParam.
Справка Windows требует, чтобы приложение прямо отменяло справку, чтобы освободить ресурсы, используемые для управления приложением и его файлами справки. Приложение может сделать это в любое время, вызвав функцию WinHelpи указав команду HELP_QUIT. Обратите внимание, что это не относится к всплывающему окну справочной системы Windows. Приложение не должно пытаться закрыть всплывающее окно.
Если приложение сделало каких-либо вызовов к WinHelp, оно должно отменить справку, прежде чем закрыть главное окно (например, в ответ на сообщение WM_DESTROY в процедуре главного окна). Приложение должно вызывать WinHelp только один раз, чтобы закрыть справку, независимо от количества открытых файлов справки. Справка Windows остается запущенной до тех пор, пока все приложения или DLL не закрыли справку.
Чтобы закрыть инстанцию обучающей карточки справки Windows, необходимо указать команды HELP_TCARD и HELP_QUIT при вызове WinHelp. Если пользователь сначала отменяет экземпляр учебной карты в справке Windows, приложению не нужно его отменять. Справка Windows уведомляет приложение, когда пользователь отменяет экземпляр карточки обучения, отправив сообщение WM_TCARD с параметром wParam, установленным в значение IDCLOSE.
В этом разделе показано, как предоставить контекстную справку для диалогового окна и как задать внешний вид дополнительного окна справки.
Чтобы предоставить контекстную справку в диалоговом окне, необходимо создать массив, состоящий из пар значений DWORD: ,. Первое значение каждой пары — это идентификатор элемента управления в диалоговом окне, а второй — идентификатор контекста раздела справки для элемента управления. Массив должен содержать одну пару идентификаторов для каждого элемента управления в диалоговом окне.
Процедура диалогового окна должна обрабатывать WM_HELP и WM_CONTEXTMENU сообщения. Процедура диалогового окна получает WM_HELP, когда пользователь нажимает клавишу и WM_CONTEXTMENU, когда пользователь нажимает правую кнопку мыши.
Параметр lParamWM_HELP содержит адрес структуры HELPINFO. Элемент hItemHandle этой структуры определяет элемент управления, для которого пользователь запросил справку. Этот дескриптор необходимо передать в функцию WinHelp вместе с командой HELP_WM_HELP, именем файла справки и указателем на массив идентификаторов. Функция WinHelp выполняет поиск в массиве идентификатора указанного элемента управления и затем получает соответствующий идентификатор контекста справки. Затем функция передает идентификатор контекста справки в Windows Help, которая находит соответствующий раздел и отображает его во всплывающем окне. Если элемент управления имеет идентификатор -1, система ищет следующий элемент управления, который является пунктом остановки, а затем использует его идентификатор, чтобы определить идентификатор справочного контекста. По этой причине важно разместить статический текст перед элементами управления в файле ресурсов.
При вызове функции WinHelp обработка WM_CONTEXTMENU аналогична обработке WM_HELP с этими двумя исключениями:
- Вы передаете параметр wParam из WM_CONTEXTMENU, который является дескриптором управления, отправившего сообщение.
- Вместо HELP_WM_HELPукажите команду HELP_CONTEXTMENU.
Команда HELP_CONTEXTMENU приводит к отображению меню в справке Windows перед отображением раздела справки. Меню определяется системой. Он позволяет пользователю отображать справку по элементу управления или отображать диалоговое окно Разделы справки.
В следующем примере показано, как реализовать контекстно-зависимую помощь в диалоговом окне.
LRESULT CALLBACK EditDlgProc(HWND hwndDlg, UINT uMsg,
WPARAM wParam, LPARAM lParam)
{
// Create an array of control identifiers and context identifiers.
static DWORD aIds[ ] =
{
ID_SAVE, IDH_SAVE,
ID_DELETE, IDH_DELETE,
ID_COPY, IDH_COPY,
ID_PASTE, IDH_PASTE,
0,0
};
switch (uMsg)
{
case WM_HELP:
WinHelp(((LPHELPINFO)lParam)->hItemHandle, "helpfile.hlp",
HELP_WM_HELP, (DWORD)(LPSTR)aIds);
break;
case WM_CONTEXTMENU:
WinHelp((HWND)wParam, "helpfile.hlp", HELP_CONTEXTMENU,
(DWORD)(LPVOID)aIds);
break;
// Process other messages here.
}
return FALSE;
}
Приложение может задать размер, позицию и показать состояние дополнительного окна справки, передав команду HELP_SETWINPOS и адрес структуры HELPWININFO в функцию WinHelp. Члены HELPWININFO определяют имя окна для изменения, а также новый размер, положение и состояние отображения.
В следующем примере устанавливается внешний вид дополнительного окна с именем "wnd_menu". Имя должно быть определено в секции [WINDOWS] файла проекта справки.
BOOL DoWindowSize(VOID)
{
HANDLE hhwi;
LPHELPWININFO lphwi;
WORD wSize;
char *szWndName = "wnd_menu";
size_t NameLength; // Does not include the terminating null character
HRESULT hr
BOOL retval;
hr = StringCbLengthA(szWndName, STRSAFE_MAX_CCH, &NameLength);
if (SUCCEEDED(hr))
{
// Add 1 to account for the name string's terminating null character.
NameLength++;
// The HELPWININFO structure contains a minimal TCHAR array of size [2]
// that is used for the window name. Since sizeof(HELPWININFO)
// includes those two TCHARS, they must be subtracted from the
// total when adding the actual string length to calculate the
// size of the structure.
wSize = sizeof(HELPWININFO) - 2 + NameLength;
}
else
// Something's amiss with the string.
return FALSE;
hhwi = GlobalAlloc(GHND, wSize);
lphwi = (LPHELPWININFO)GlobalLock(hhwi);
lphwi->wStructSize = wSize;
lphwi->x = 256; // horizontal position
lphwi->y = 256; // vertical position
lphwi->dx = 767; // width
lphwi->dy = 512; // height
lphwi->wMax = SW_SHOW; // show the window
// secondary window
hr = StringCbCopyA(lphwi->rgchMember, sizeof(lphwi->rgchMember), szWndName);
if (SUCCEEDED(hr))
{
WinHelp(hwnd, "myhelp.hlp", HELP_SETWINPOS, (DWORD)lphwi);
GlobalUnlock(hhwi);
GlobalFree(hhwi);
return TRUE;
}
else
// There was a problem copying the window name.
return FALSE;
}