Обработка справки в Интернете

Справка в Интернете может быть представлена в различных формах: от подробной концептуальной информации до кратких определений. В этом разделе содержатся следующие подразделы.

• Сведения о справке
  • Запросы на помощь
  • Отображение справки и справка Windows
• Использование справки
  • Предоставление справки в диалоговом окне
  • Настройка внешнего вида дополнительного окна справки

Сведения о справке

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

Запросы на помощь

Большинство приложений на основе Windows предоставляют справочные сведения в интернете в различных формах, начиная от концептуальной справки, объясняющей назначение функций приложения, до всплывающей справки, которая предоставляет быстрые определения отдельных элементов в пользовательском интерфейсе приложения. Функции и сообщения используются для предоставления пользователям различных способов запроса доступа к этой информации. Эти запросы на помощь описаны в следующих разделах.

Меню "Справка"

Большинство приложений предоставляют пользователям доступ к справочным сведениям, включив меню Справка в окне main. Когда пользователь выбирает элемент в меню "Справка" , соответствующая процедура окна получает 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

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

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

Чтобы просмотреть справочные сведения, необходимо указать файл справки при вызове функции WinHelp . Файл справки должен иметь формат файла справки Windows (HLP) и один или несколько разделов. Каждая тема представляет собой отдельную единицу информации, например концептуальное описание, набор инструкций, рисунок, определение глоссария и т. д. Разделы должны быть уникальными, чтобы справка Windows могло найти их при каждом запросе. Внутренне справка Windows использует идентификаторы тем для поиска тем, но приложения чаще всего используют идентификаторы контекста (уникальные целочисленные значения) для указания отображаемых тем. Автор файла справки должен явно сопоставить идентификаторы контекста с идентификаторами разделов в разделе [MAP] файла проекта, используемого для создания файла справки.

Если вы указываете файл справки, но не указываете путь, WinHelp ищет файл справки в каталоге справки или в каталоге, указанном в переменной среды PATH. Кроме того, WinHelp может найти файл справки, имя которого указано в следующем расположении реестра:

HKEY_LOCAL_MACHINE
   Software
      Microsoft
         Windows
            Help

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

Если WinHelp не может найти указанный файл справки, отображается диалоговое окно, позволяющее пользователю указать расположение файла справки. Так как WinHelp сохраняет сведения о расположении в реестре, он больше не запрашивает расположение того же файла справки.

Дополнительные сведения о создании и создании файла справки см. в документации по средствам разработки.

Запуск справки Windows

В следующем примере функция 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 для отображения раздела Contents и индекса ключевое слово файла справки. Эти команды больше не рекомендуются. Вместо этого используйте команду HELP_FINDER .

Информационные разделы

Вы можете отобразить определенный раздел, вызвав функцию WinHelp с помощью команды HELP_CONTEXT и указав идентификатор контекста для раздела. Приложения обычно используют команду HELP_CONTEXT в ответ на запросы пользователей на разделы, содержащие концептуальную информацию или процедурную справку, а не сведения о конкретном элементе управления или меню. В таких случаях пользователь может продолжать просматривать файл справки в поисках связанных сведений, прежде чем возвращаться в приложение.

Команда HELP_CONTEXT вызывает обычный экземпляр справки Windows, позволяя пользователю находить другие разделы в файле справки. Обычно в нем отображается окно справки main, которое включает строку заголовка, системное меню, кнопки свернуть и развернуть, меню main, необязательную панель навигации, границу размера и клиентскую область. Текст выбранного раздела отображается в клиентской области, и пользователь может перемещаться по файлу справки с помощью горячих ссылок или кнопок навигации в окне main. Обычный экземпляр справки Windows также можно использовать для отображения справки в одном или нескольких дополнительных окнах вместо окна main.

Всплывающие разделы

Вы можете отобразить всплывающий раздел, содержащий сведения для определенного элемента управления или меню, вызвав функцию WinHelp с помощью команды HELP_WM_HELP или HELP_CONTEXTMENU. Эти команды отображают раздел во всплывающем окне рядом с соответствующим элементом управления или меню. Чтобы пользователь сразу же вернулся к работе в приложении, всплывающее окно удаляется, как только пользователь нажимает клавишу или щелкает левую кнопку мыши.

Команда HELP_WM_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 в файле содержимого, или в окне main. Если окно main уже открыто для другого файла справки при вызове WinHelp, функция скрывает окно main при поиске. В этом случае при отмене диалоговых окон "Найденные разделы" и "Разделы справки" окно main закрывается.

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

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

Дополнительные окна необходимо определить в разделе [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, оно должно отменить справку, прежде чем закрыть окно main (например, в ответ на сообщение WM_DESTROY в процедуре окна main). Приложение должно вызывать 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, которая находит соответствующий раздел и отображает его во всплывающем окне. Если элемент управления имеет идентификатор -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;
}