TN028: поддержка контекстной справки
Эта заметка описывает правила присвоения идентификаторы и другое контекстов Справки проблемы справки в MFC.Поддержка контекстной справки требуется компилятора справки, который доступен в Visual C++.
.gif "Примечание") Примечание |
|---|
Помимо контекстную справку, используя 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 перед выполнением этих операций.Реализация CDialog проверяет это PreTranslateMessage перед вызовом IsDialogMessage, например.Это запрещает «клавиши навигации диалогового окна» в диалоговых окнах modeless во время режима 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, где была нажата кнопка мыши по оси y относительно клиентской области окна.HIWORD (lParam)
содержит координату по оси Y.wParam
не используется и становится равным нулю.Если возвращаемое значение не равно нулю, то WinHelp вызывается с этим контекстом.Если возвращаемое значение равно нулю, то родительское окно запрашиваются для справки.
Во многих случаях можно использовать код, выполненная строка-тестирования можно иметь.См. пример реализации CToolBar::OnHelpHitTest обработки сообщения WM_HELPHITTEST (код использует код проверки нажатия, используемый на кнопках и подсказках в CControlBar).
Поддержка мастера приложений MFC и MAKEHM
Мастер приложений MFC создает файлы, необходимые для построения файл Справки (файлы .cnt и .hpj).Он также содержит несколько файлов prebuilt .rtf, которые принимаются компилятором Справки (Майкрософт).Многие из подразделов завершен, но некоторые из них могут быть изменен для конкретного приложения.
Автоматическое создание файла сопоставления «справка» поддерживается называемого программой 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.