Создание справочной системы. Часть 2

Контекстные справки, появляющиеся во всплывающих окнах

Инструментарий HHW позволяет создавать и включать в справочное руководство специальную секцию TEXT POPUPS, предназначенную для обеспечения работы с контекстными справками к элементам интерфейса и появление этих справок во всплывающих окнах. Созданию секции TEXT POPUPS, которая необходима при работе с такими контекстными справками, должно предшествовать создание двух текстовых файлов. Один из них уже может существовать, если создавалась секция MAP, - это заголовочный файл, задающий отображение между символьными и числовыми идентификаторами. Второй текстовый файл содержит описание контекстных сообщений, которые будут появляться во всплывающих окнах. Чуть позже я расскажу о синтаксисе, которому должен удовлетворять этот файл. После того, как эти два файла будут созданы, можно переходить к созданию секции TEXT POPUPS, для чего достаточно нажать одноименную вкладку.

Рис. 9.21. Создание секции TEXT POPUPS

Две командные кнопки "Header" и "Text File" позволяют включить в секцию два файла - заголовочный файл и файл с контекстными сообщениями, что и должно обеспечить скомпилированному chm-файлу возможность выдавать при запросах контекстные справки к элементам интерфейса. Существует небольшая, но досадная разница в том, как подключается заголовочный файл в секциях MAP, ALIAS и TEXT POPUPS. В двух первых случаях формируется предложение #include <имя файла>. В последнем случае вставляется непосредственно имя файла, что не позволяет обойти возникающую проблему "невидимости" заголовочного файла.

Создание текстового файла с контекстными справками

Контекстные справки, появляющиеся во всплывающих окнах, как правило, представляют собой тексты небольшого размера. Поэтому в отличие от обычных разделов справочного руководства, каждый из которых содержится в отдельном файле, все такие контекстные справки могут быть собраны в одном файле. Иногда предпочтительнее вместо одного большого файла иметь несколько файлов, например, отдельные файлы для элементов каждой формы. Такой сборный файл с контекстными справками в HHW создается в текстовом, а не в HTML формате. Структура такого файла достаточно проста и удовлетворяет следующему синтаксису:

<Заголовок раздела>
 <Текст контекстной справки>
[ <Заголовок раздела>
 <Текст контекстной справки>]…

Файл, как видите, представляет последовательность озаглавленных разделов. Заголовок раздела начинается специальным ключевым словом и содержит символьный идентификатор раздела. Вот его синтаксис:

.topic <Символьный идентификатор>

Текст контекстной справки представляет собой обычный текст без картинок и прочих украшений, возможных для текстов в формате HTML, используемых в разделах справочного руководства. Вот два начальных раздела из файла, созданного для очередного примера:

.topic IDH_Man
Вот Человек, который следит за
всеми зверьми. Он не допустит, чтобы волк
съел козу, не разрешит козе съесть капусту.
Он перевезет всех с левого берега на правый
берег реки. Он помнит, что лодка его мала и
не выдержит трех пассажиров.
.topic IDH_Wolf
Это волк, который дружен с
человеком, равнодушен к капусте, но
обязательно съест козу, если рядом нет
человека.

В hhp-проект, создаваемый для игры "Волк, Коза и Капуста", были включены, как HTML-файлы с разделами справочного руководства, так и текстовый файл, содержащий контекстные справки к элементам интерфейса, подготовленные для показа во всплывающих окнах. Соответственно проект содержит все три секции - MAP, ALIAS и POPUPS. Заменить в секции POPUPS заголовочный файл на его содержание не удается, по причинам, о которых я уже говорил. В результате файл компилируется с ошибками и, хотя они носят характер предупреждений, нужное отображение между идентификаторами и разделами контекстной справки так и не строится. Вот как выглядит результат трансляции проекта:

Рис. 9.22. Результат компиляции hhp-проекта игры "Волк, Коза и Капуста quot;

С другой стороны стоит отметить, что при тестировании проекта обе команды HtmlHelp API функции работают успешно, что уже само по себе обеспечивает возможность организовать получение контекстных справок, используя вызовы функции HtmlHelp.

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

Контекстные справки к элементам интерфейса. Эксперимент

Проделана вся необходимая работу, как на стороне программного проекта "Волк, Коза и Капуста", так и на стороне создания справочного руководства для этой игры. Я создал и зарегистрировал chm-файл, содержащий, как разделы обычного справочного руководства, так и контекстные справки к элементам интерфейса формы, представляющей игровое поле. На основе chm-файла был создан и Aw-файл, позволяющий Рокки отвечать на вопросы. Осталось провести эксперименты и посмотреть, что из всего этого работает. Прежде всего, я попытался получить контекстные справки к тем надписям на форме, для которых определены числовые идентификаторы и созданы соответствующие разделы в справочном руководстве:

Рис. 9.23. Попытка получения контекстной справки к элементу интерфейса

Как видите, выдается сообщение об отсутствии контекстной справки для этого элемента интерфейса. Хотя истинная причина состоит не в отсутствии раздела, а в том, что не задано нужное отображение числового идентификатора на символьный идентификатор и связанный с ним раздел, где содержится контекстная справка. Что же все-таки работает в данной ситуации? Если специализированный курсор со знаком вопроса не подводить к элементам интерфейса, для которых задан HelpContextID, а щелкнуть где-нибудь в произвольном месте формы, то откроется справочное руководство и можно будет получить справку обычным способом. Заметьте, что для этого не понадобилось создавать никаких дополнительных командных кнопок или команд меню. Это не совсем то, что хотелось бы, но вызывать справочное руководство в форме достаточно просто, что, в конечном счете, позволяет получить справки ко всем элементам интерфейса.

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

Справки может выдавать и Помощник.

Рис. 9.24. Рокки отвечает на вопрос об основных героях игры

Как видите, Рокки показал все темы, в которых описаны запрашиваемые визуальные объекты. Это еще один способ решения поставленной задачи. Способ справиться с задачей всегда существует. Надеюсь, правда, что в следующей версии HHW не нужно будет искать обходные пути и будет доступен прямой способ решения данной задачи.