TN028. Поддержка контекстной справки
Эта заметка описывает правила присвоения идентификаторы и других контекстов справки проблемы справки в MFC. Поддержка контекстной справки для компилятора справки, доступный в Visual C++.
Примечание
В дополнение к реализации контекстная справка использование WinHelp, MFC также поддерживает использование справки HTML.Дополнительные сведения об этой поддержки и программирования со справкой HTML см. в разделе Html-справки. Контекстная справка для программ.
Поддерживаемые типы справки
2 Типа контекстной справки, реализованное в Windows-приложение. Во-первых, с именем «справка F1» включает запуск WinHelp, соответствующий контекст, основанный на активном в данный момент объекта. Второй режим Shift+ «F1». В этом режиме курсор мыши изменяется на курсор справки и пользователь продолжает кнопку на объект. На этом этапе, WinHelp запускается для справки для объекта, который выбрал пользователь включен.
Классы Microsoft Foundation реализуют обе формы справки. Кроме того, платформа поддерживает 2 простых команды справки, индекс справки и справка использования.
Файлы справки
Классы 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_
Простые команды «справка»
2 Простых команды справки, реализованную классами 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 частное сообщение MFC Windows, полученного активным, когда запрашивается справка. Когда окно получает сообщение, он может вызвать CWinApp::WinHelp с контекстом, совпадающего состояние окна.
lParam
Содержит в настоящее время доступны контекст справки. lParam ноль, если отсутствует контекст справки не был задан. Реализация OnCommandHelp может использовать контекстный идентификатор в lParam, чтобы указать другой контекст или может просто передать его в CWinApp::WinHelp.wParam
Не используется и будет ноль.
Если вызовы функций CWinApp::WinHelpOnCommandHelp, то должен возвращают TRUE. Возвращение TRUE останавливает перенаправление этой команды с другими классами и в других окон.
Режим справки (справка Shift+F1)
Это вторая форма контекстной справки. Как правило, этот режим зарегистрирован, нажав SHIFT+F1 либо через меню или панели инструментов. Он реализуется в виде команды (ID_CONTEXT_HELP). Обработчик фильтра сообщений не используется, чтобы преобразовать эту команду, модальное диалоговое окно или меню активно, поэтому эта команда доступна только пользователю, когда приложение выполняется цикла обработки сообщений (CWinApp::Run).
После ввода этот режим, курсор мыши справки отображается над всеми областями приложения, даже если приложение обычно показывало бы свой собственный курсор данной области (например, границы вокруг размера окна). Пользователь может использовать мыши или клавиатуры для выделения команду. Не удается выполнить команду, справка в этой команде. Кроме того, пользователь может щелкнуть объект отображается на экране, например кнопки на панели инструментов и справка отображается для этого объекта. Этот режим справки предоставляется CWinApp::OnContextHelp.
Во время выполнения этого цикла, весь ввод данных с клавиатуры бездействия, за исключением ключей для доступа к меню. Кроме того, преобразование команды по-прежнему выполняется через PreTranslateMessage для разрешения пользователя, чтобы нажать сочетание клавиш и получить справку для этой команды.
При наличии переводы или действия случаясь в функции, PreTranslateMessage, не должна быть во время режима справки SHIFT+F1 необходимо проверить член m_bHelpModeCWinApp перед выполнением этих операций. Реализация CDialogPreTranslateMessage проверяет это перед вызовом IsDialogMessage, например. Это приведет к отключению «ключи навигации диалогового окна» на немодальных диалоговых окнах во время режима SHIFT+F1. Кроме того, CWinApp::OnIdle по-прежнему вызывается во время этого цикла.
Если пользователь выбирает команду в меню, обрабатывается как справка в этой команде (с помощью функции WM_COMMANDHELP, см. ниже). Если пользователь щелкает видимой области окна приложений, определение делается доступной, нажмите кнопку nonclient или клиента. сопоставления дескрипторов OnContextHelp nonclient нажмите кнопку клиенту автоматически. Если щелкнуть клиентов, после чего отправляет 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).
Поддержка и MAKEHM мастера приложений MFC
Мастер приложений MFC создает файлы, необходимые для построения файл справки (файлы .cnt и .hpj). Он также содержит несколько файлов с расширением RTF из готовый, принимаются компилятором справки microsoft. Многие из подразделов завершена, но некоторые могут быть изменены для конкретного приложения.
Автоматическое создание файла сопоставления «справки» поддерживается вызов служебной программой MAKEHM. Программа MAKEHM может перевести файл RESOURCE.H приложения в файл сопоставления справки. Примеры.
#define IDD_MY_DIALOG 2000
#define ID_MY_COMMAND 150
преобразует в:
HIDD_MY_DIALOG 0x207d0
HID_MY_COMMAND 0x10096
Этот формат совместим с помещением компилятора справки, который сопоставляет идентификаторы контекста (числа в правой части) с именами раздела (знаков в левой части).
Исходный код для MAKEHM доступен в примере MAKEHM программ программирования MFC.
Добавление поддержки справки после запуска мастера приложений MFC
Лучший способ добавления справка в приложение проверку параметра «контекстной справки» на странице дополнительных функций мастера приложений MFC до создания приложения. В этом случае мастер приложений MFC автоматически добавляет необходимые записи в CWinApp- производный класс сопоставления сообщений в справке поддержки.
Справка в окнах
Справка в окне сообщения (иногда вызываемых оповещениями) поддерживается через функцию AfxMessageBox, программу-оболочку для API Windows MessageBox.
2 Версии 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.