TN028. Поддержка контекстной справки

Статья
06/16/2023

В этом примечании описываются правила назначения идентификаторов контекстов справки и других проблем справки в MFC. Поддержка справки с учетом контекста требует компилятора справки, доступного в Visual C++.

Примечание.

Помимо реализации контекстно-конфиденциальной справки с помощью WinHelp, MFC также поддерживает использование справки HTML. Дополнительные сведения об этой поддержке и программировании с помощью справки HTML см . в справке HTML: контекстно-чувствительная справка для ваших программ.

Поддерживаемые типы справки

В приложениях Windows реализованы два типа справки с учетом контекста. Первое, называемое "Справка F1", включает запуск WinHelp с соответствующим контекстом на основе текущего активного объекта. Второй — режим SHIFT+F1. В этом режиме курсор мыши изменяется на курсор справки, и пользователь переходит к щелчку объекта. На этом этапе WinHelp запускается, чтобы дать помощь для объекта, который пользователь щелкнул.

Классы Microsoft Foundation реализуют обе эти формы справки. Кроме того, платформа поддерживает две простые команды справки, индекс справки и использование справки.

Файлы справки

Классы Microsoft Foundation предполагают один файл справки. Этот файл справки должен иметь то же имя и путь, что и приложение. Например, если исполняемый файл является C:\MyApplication\MyHelp.exe, файл справки должен быть C:\MyApplication\MyHelp.hlp. Вы задаете путь через переменную члена m_pszHelpFilePath класса CWinApp.

Диапазоны контекстов справки

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

0x00000000 - 0x0000FFFF : user defined
0x00010000 - 0x0001FFFF : commands (menus/command buttons)
0x00010000 + ID_
(note: 0x18000-> 0x1FFFF is the practical range since command IDs are>=0x8000)
0x00020000 - 0x0002FFFF : windows and dialogs
0x00020000 + IDR_
(note: 0x20000-> 0x27FFF is the practical range since IDRs are <= 0x7FFF)
0x00030000 - 0x0003FFFF : error messages (based on error string ID)
0x00030000 + IDP_
0x00040000 - 0x0004FFFF : special purpose (non-client areas)
0x00040000 + HitTest area
0x00050000 - 0x0005FFFF : controls (those that are not commands)
0x00040000 + IDW_

Простые команды "Справка"

Существует две простые команды справки, реализованные классами Microsoft Foundation:

ID_HELP_INDEX реализации CWinApp::OnHelpIndex
ID_HELP_USING реализации CWinApp::OnHelpUsing

Первая команда показывает индекс справки для приложения. Во втором показана справка пользователя по использованию программы WinHelp.

Справка с учетом контекста (справка F1)

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

Независимо от того, как создается команда ID_HELP, она направляется как обычная команда, пока она не достигнет обработчика команд. Дополнительные сведения об архитектуре маршрутизации команд MFC см. в техническом примечание 21. Если в приложении включена справка, команда ID_HELP будет обрабатываться CWinApp::OnHelp. Объект приложения получает сообщение справки, а затем направляет команду соответствующим образом. Это необходимо, так как маршрутизация команд по умолчанию не подходит для определения наиболее конкретного контекста.

CWinApp::OnHelp пытается запустить WinHelp в следующем порядке:

Проверяет наличие активного AfxMessageBox вызова с идентификатором справки. Если в настоящее время поле сообщения активно, WinHelp запускается с контекстом, соответствующим данному окне сообщения.
Отправляет WM_COMMANDHELP сообщение в активное окно. Если это окно не отвечает, запуская WinHelp, то то же сообщение отправляется предкам этого окна, пока сообщение не будет обработано, или текущее окно будет окном верхнего уровня.
Отправляет команду ID_DEFAULT_HELP в главное окно. При этом вызывается справка по умолчанию. Эта команда обычно сопоставляется с CWinApp::OnHelpIndex.

Чтобы глобально переопределить базовые значения идентификаторов по умолчанию (например, 0x10000 для команд и 0x20000 для таких ресурсов, как диалоговые окна), приложение должно переопределить CWinApp::WinHelp.

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

WM_COMMANDHELP

afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam)

WM_COMMANDHELP — это частное сообщение Windows MFC, полученное активным окном при запросе справки. Когда окно получает это сообщение, он может вызываться CWinApp::WinHelp с контекстом, который соответствует внутреннему состоянию окна.

lParam
Содержит текущий доступный контекст справки. lParam равно нулю, если контекст справки не определен. Реализация может использовать идентификатор контекста OnCommandHelp в lParam для определения другого контекста или просто передать его CWinApp::WinHelpв .

wParam
Не используется и будет нулевым.

OnCommandHelp Если функция вызываетсяCWinApp::WinHelp, она должна возвращать ЗНАЧЕНИЕ TRUE. Возврат TRUE останавливает маршрутизацию этой команды в другие классы и в другие окна.

Режим справки (справка SHIFT+F1)

Это вторая форма справки с учетом контекста. Как правило, этот режим вводится путем нажатия клавиш SHIFT+F1 или с помощью меню или панели инструментов. Он реализуется как команда (ID_CONTEXT_HELP). Перехватчик фильтра сообщений не используется для перевода этой команды во время модального диалогового окна или меню, поэтому эта команда доступна только пользователю, когда приложение выполняет основной насос сообщений (CWinApp::Run).

После ввода этого режима курсор мыши справки отображается во всех областях приложения, даже если приложение обычно отображает собственный курсор для этой области (например, границу размера вокруг окна). Пользователь может использовать мышь или клавиатуру для выбора команды. Вместо выполнения команды отображается справка по этой команде. Кроме того, пользователь может щелкнуть видимый объект на экране, например кнопку на панели инструментов, и будет отображаться справка для этого объекта. Этот режим справки предоставляется CWinApp::OnContextHelp.

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

Если в функции существуют определенные переводы или действия, которые не должны выполняться в PreTranslateMessage режиме справки SHIFT+F1, перед выполнением этих операций необходимо проверка элемент CWinApp m_bHelpMode. PreTranslateMessage Реализация CDialog проверка выполняется перед вызовомIsDialogMessage, например. Это отключает клавиши "навигация по диалогу" в бессерверных диалоговых окнах в режиме SHIFT+F1. Кроме того, CWinApp::OnIdle он по-прежнему вызывается во время этого цикла.

Если пользователь выбирает команду из меню, она обрабатывается как справка по этой команде (через WM_COMMANDHELP см. ниже). Если пользователь щелкает видимую область окна приложений, определяется, является ли он неклиентным щелчком или клиентом. OnContextHelp обрабатывает сопоставление неклиентных щелчков с клиентскими щелчками автоматически. Если клиент щелкает, он отправляет WM_HELPHITTEST в окно, которое было щелкнуно. Если это окно возвращает ненулевое значение, это значение используется в качестве контекста справки. Если он возвращает ноль, OnContextHelp пытается родительское окно (и завершается сбоем, его родительским и т. д.). Если контекст справки не может быть определен, по умолчанию необходимо отправить команду ID_DEFAULT_HELP в главное окно, которое затем (обычно) сопоставлено с CWinApp::OnHelpIndex.

WM_HELPHITTEST

afx_msg LRESULT CWnd::OnHelpHitTest(
WPARAM, LPARAM lParam)

WM_HELPHITTEST — это сообщение о частных окнах MFC, полученное активным окном, щелкнув в режиме справки SHIFT+F1. Когда окно получает это сообщение, он возвращает идентификатор справки DWORD для использования WinHelp.

LOWORD(lParam) содержит координату устройства оси X, где мышь была щелкнуна относительно клиентской области окна.

HIWORD(lParam) содержит координату оси Y.

wParam
не используется и будет нулевым. Если возвращаемое значение ненулевое, WinHelp вызывается с этим контекстом. Если возвращаемое значение равно нулю, родительское окно запрашивается для справки.

Во многих случаях можно использовать код для тестирования попаданий, который уже имеется. См. пример CToolBar::OnHelpHitTest обработки сообщения WM_HELPHITTEST (код использует код теста попадания, используемый на кнопках и подсказках CControlBar).

Поддержка мастера приложений MFC и MAKEHM

Мастер приложений MFC создает необходимые файлы для создания файла справки (Cnt и HPJ-файлов). Он также включает ряд предварительно созданных RTF-файлов, которые принимаются компилятором справки Майкрософт. Многие из разделов завершены, но некоторые из них могут быть изменены для конкретного приложения.

Автоматическое создание файла справки поддерживается служебной программой с именем MAKEHM. Служебная программа MAKEHM может перевести ресурс приложения. H-файл в файл сопоставления справки. Например:

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND   150

преобразуется в:

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Этот формат совместим с средством компилятора справки, который сопоставляет идентификаторы контекста (цифры справа) с именами разделов (символами слева).

Исходный код ДЛЯ MAKEHM доступен в примере программы программирования MFC MAKEHM.

Добавление поддержки справки после запуска мастера приложений MFC

Лучший способ добавить справку в приложение — проверка параметр "Контекстно-конфиденциальная справка" на странице дополнительных функций мастера приложений MFC перед созданием приложения. Таким образом мастер приложений MFC автоматически добавляет необходимые записи карты сообщений в CWinAppпроизводный класс для поддержки справки.

Справка по полям сообщений

Справка по полям сообщений (иногда называемые оповещениями) поддерживается через AfxMessageBox функцию, оболочку для MessageBox API Windows.

Существует две версии AfxMessageBox: одна для использования с идентификатором строки и другая для использования с указателем на строку (LPCSTR):

int AFXAPI AfxMessageBox(LPCSTR lpszText,
    UINT nType,
    UINT nIDHelp);

int AFXAPI AfxMessageBox(UINT nIDPrompt,
    UINT nType,
    UINT nIDHelp);

В обоих случаях существует необязательный идентификатор справки.

В первом случае значение по умолчанию для nIDHelp равно 0, указывающее отсутствие справки для этого поля сообщения. Если пользователь нажимает клавишу F1, например поле сообщения активно, пользователь не получит справку (даже если приложение поддерживает справку). Если это не желательно, необходимо указать идентификатор справки для nIDHelp.

Во втором случае значение по умолчанию для nIDHelp равно -1, указывающее, что идентификатор справки совпадает с nIDPrompt. Справка будет работать только в том случае, если приложение с поддержкой справки, конечно). Если в поле сообщения нет поддержки, необходимо указать значение 0 для nIDHelp. Если вы хотите, чтобы сообщение было включено, но требуется другой идентификатор справки, отличный от nIDPrompt, просто укажите положительное значение для nIDHelp, отличное от nIDPrompt.

См. также

Технические примечания по номеру
Технические примечания по категории

Поделиться через