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

Справки типа "Что это такое?" к элементам интерфейса в формах

Работа по организации справок данного типа состоит из двух частей. Часть работы связана с программным проектом, формой, элементами интерфейса данной формы. Нужно уметь корректно задать нужные свойства при проектировании всех этих элементов, для того чтобы появились подобные справки. Вторая часть этой работы состоит в подготовке разделов справки, и она выполняется специальным инструментарием, например, Winhelp или HHW.

Работа, выполняемая на стороне программного проекта

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

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

Давайте поговорим обо всем этом подробнее. Прежде всего, обратите внимание, что справочное руководство связывается с проектом, а не с формой. Оно одно на весь проект, поэтому, сколько бы не было различных форм, все разделы справки должны быть собраны в одно руководство. Заметьте, также, что файл, содержащий руководство, может иметь расширение htm или chm в зависимости от того, каким инструментарием он подготовлен. Надеюсь, не надо объяснять, как нужно задавать свойства программного проекта. Ранее я уже об этом говорил.

Булевы свойства WhatThisButton и WhatThisHelp формы должны быть установлены как true (истина). Включение кнопки WhatThisHelp обеспечивает поддержку выдачи контекстных справок. Если же дополнительно включена кнопка WhatThisButton, то в этом случае в правом углу заголовка формы появится дополнительная кнопка со знаком вопроса, и форма приобретет новое качество. Всякий раз, когда пользователь щелкнет эту кнопку, курсор изменит свой внешний вид - рядом с курсором будет плавать знак вопроса. Достаточно теперь подвести такой курсор к выбранному элементу интерфейса и щелкнуть по нему, как в появившемся всплывающем окне отобразится контекстная справка, поясняющая суть данного элемента.

Понятно, что чудес не бывает и появляющийся раздел справки однозначно определяется числовым значением контекстного идентификатора - HelpContextID, установленного для каждого элемента интерфейса. Особых требований к этим идентификаторам не предъявляется, важно только, чтобы они были уникальными, позволяя для каждого элемента интерфейса во всем программном проекте однозначно установить нужный раздел справочного руководства. Возникает вопрос, - откуда берутся значения этих идентификаторов? Это вопрос о том, что было раньше - курица или яйцо. Если раньше строится справочное руководство, а уж потом контекстно-чувствительные справки добавляются к программному проекту, то значения идентификаторов определяются при построении справочного руководства. Чаще всего, возникает обратная ситуация, когда проектируется форма, задаются уникальные значения контекстных идентификаторов для каждого ее элемента, а потом уже строится справочное руководство, поддерживающее данные значения. В общем, правильный ответ состоит в том, что на этапе проектирования системы должны быть предусмотрены разделы справки для каждого элемента интерфейса и связанные с этими разделами два уникальных идентификатора - числовой (HelpContextID) и строковый, называемый символическим идентификатором раздела. О символических идентификаторах поговорим позже. Сейчас же замечу, что вся система контекстных справок, где бы они ни выдавались, - в формах или документах, построена на использовании этих двух видов идентификаторов. Скажу также, что и возникающие проблемы связаны с тем, что не всегда удается построить правильное отображение между идентификаторами и соответствующими разделами справки.

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

Рис. 9.12. "Новый" интерфейс в игре "Волк, Коза и Капуста"

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

Итак, подведу некоторые итоги. У меня есть программный проект, в нем есть форма, в ней элементы интерфейса и я выполнил все три условия, необходимые для организации контекстной справки типа "Что это такое?". В свойствах элементов интерфейса (в данном случае - это одни подписи, что не играет принципиальной роли) я задал значения HelpContextID от 1000 до 1009. Для рисунков, напомню, задать идентификатор для получения контекстной справки, к сожалению, невозможно. Можно было бы задать идентификатор для самой формы, но я этого не сделал, поскольку в нашей форме из-за визуальных объектов не осталось "живого" места. На следующем шаге я изменил значения вышеупомянутых булевых свойств формы и, как можно видеть на рисунке, у формы появился знак вопроса в правом верхнем углу. Я установил в свойствах программного проекта имя файла справочного руководства, которое должно содержать разделы справки для каждого элемента интерфейса. Этот файлу я дал длинное имя "WhatThisHelpToWGC.chm" и его предстоит создать уже знакомыми средствами инструментария HTML Help Workshop. Этим мы и займемся.

Новые возможности при создании справочного руководства

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

1. Для чего нужны и как создаются символьные и числовые идентификаторы разделов, как строится отображение этих идентификаторов на имена файлов, содержащих разделы справки.
2. Как включаются в справочное руководство контекстные справки, появляющиеся затем во всплывающих окнах.

Идентификаторы и разделы справки. Построение отображения

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

Для того чтобы разделы справочного руководства связать с числовыми и символьными идентификаторами, при работе в HHW требуется установить два отображения. Первое отображение задается в специальной секции MAP, оно устанавливает соответствие между двумя видами идентификаторов. Второе отображение задается в секции ALIAS, - оно связывает символьные идентификаторы с именами файлов, хранящих разделы справки. В совокупности оба отображения позволяют, зная любой из идентификаторов, найти нужный раздел справки.

Поскольку одной из наших целей является включение в справочное руководство специальных контекстных справок, то мы также рассмотрим создание в hhp-проекте секции TEXT POPUPS, в которой задается ссылка на текстовый файл, содержащий контекстные справки и устанавливается соответствие между этими справками и их идентификаторами.

Давайте перейдем к рассмотрению подробностей построения каждого из упомянутых отображений и формирования секций hhp-проекта: MAP, ALIAS, TEXT POPUPS.

Отображение между двумя видами идентификаторов - символьными и числовыми - представляется в виде определения последовательности именованных констант. Синтаксис заимствован из языка С и каждая строка в определении отображения имеет вид:

#define 	<символьный идентификатор>		<числовой идентификатор>

Вот как выглядит отображение, задаваемое для нашего примера:

#define IDH_Man 	1000
#define IDH_Wolf	1001
#define IDH_Goat 	1002
#define IDH_Cabbage 	1003
#define IDH_Boat 	1004
#define IDH_River 	1005
#define IDH_LeftBank 	1006
#define IDH_RightBank 	1007
#define IDH_Shark 	1008
#define IDH_Island 	1009

Заметьте, символьные идентификаторы начинаются префиксом IDH_. В этом случае система HHW опознает их как символьные идентификаторы и осуществляет весьма полезные проверки корректности задания отображения между идентификаторами и разделами справки. Так что рекомендуется всегда использовать этот префикс в символьных именах. Это отображение строится в обычном текстовом редакторе внутри HHW, в Блокноте или в Word, если Вы привыкли там работать. Файл сохраняется как текстовый файл с уточнением ".h". Это уточнение типично для заголовочных файлов языка C. По сути, файл таковым и является, он является частью hhp-проекта и хранится в каталоге проекта вместе с остальными файлами. Теперь несколько слов о том, как создается секция MAP.

При работе с вкладкой Project в главном окне среды HHW на левой инструментальной панели расположена специальная кнопкаHTML Help API Information. Она называется так, потому что API функция HTML Help, которая явно или неявно используется при вызове разделов справочной системы, требует в качестве информации (параметров) задания числовых или символьных идентификаторов. Но об этом мы еще поговорим позже.

Щелчок по данной кнопке открывает диалоговое окно, три вкладки которого обеспечивают создание трех секций hhp-проекта, о которых идет речь. Вот как выглядит это окно, открытое на вкладке MAP:

Рис. 9.13. Создание секции MAP

По существу, в этом окне нужно задать имя заголовочного (Header) файла, задающего отображение между символьными и числовыми идентификаторами. Как создается этот файл, я только что рассказал. Казалось бы, нет ничего проще, чем задать имя файла. В данном случае и, к сожалению, это не так. Процесс по непонятным причинам усложнен. При его выполнении возникают ошибочные ситуации, приводящие, по моему мнению, в дальнейшем к некорректной работе системы. Давайте подробно рассмотрим все этапы этого процесса.