Справочная система

 

Каждая программа должна обеспечивать пользователя справочной информацией. Существует два способа отображения справочной информации: классический ( 1, левый) и современный, в "интернет-стиле" ( 1, правый). Классический способ отображения справочной информации применяется большинством приложений, в том числе и C++ Builder. Отображение справочной информации в интернет-стиле используется в программных продуктах Microsoft и, в последнее время, в продуктах других разработчиков программного обеспечения.

Классическая справочная система представляет собой набор файлов, используя которые программа Winhelp, являющаяся составной частью Windows, выводит справочную информацию. Основой такой справочной системы являются hip-файлы.

Основой современной справочной системы являются chm-файлы. Chm-файл представляет собой компилированный HTML-документ, полученный путем компиляции (объединения) файлов, составляющих HTML-документ, в том числе и файлов иллюстраций.

Создать hip-файл можно при помощи утилиты Microsoft Help Workshop, которая входит в комплект C++ Builder (файл утилиты hce.exe находится в каталоге \CBuilder\Help\Tools). Chm-файл можно создать при помощи утилиты Microsoft HTML Help Workshop, которая, к сожалению, в состав C++ Builder не включена.

Рассмотрим процесс создания справочной системы, сначала классической, а затем — современной.
Создание справочной системы при помощи Microsoft Help Workshop

Процесс создания справочной системы состоит из двух этапов. На первом этапе надо подготовить справочную информацию, на втором — преобразовать справочную информацию в справочную систему. Задача первого этапа может быть решена при помощи редактора текста, второго — посредством утилиты Microsoft Help Workshop.

Подготовка справочной информации

Исходным материалом для Microsoft Help Workshop является справочная информация, представленная в виде rtf-файла. Наиболее просто подготовить rtf-файл справочной информации можно при помощи Microsoft Word.

Сначала нужно набрать текст разделов справки. Заголовки разделов нужно оформить одним из стилей Заголовок. Каждый раздел должен заканчиваться символом "разрыв страницы".

После того как текст разделов будет набран, каждому разделу надо назначить идентификатор. Идентификатор назначается путем вставки перед заголовком раздела сноски #.

Для того чтобы назначить разделу идентификатор, нужно установить курсор перед первой буквой заголовка раздела, затем в меню Вставка выбрать команду Сноска, а появившемся диалоговом окне Сноски выбрать в группе Нумерация положение другая, в поле редактирования ввести символ "#" ( 2).

В результате щелчка на кнопке ОК в документ будет вставлена сноска t, а в нижней части окна документа откроется окно ввода текста сноски. В этом окне рядом со значком сноски надо ввести идентификатор раздела ( 3). Рекомендуется, чтобы идентификатор раздела состоял из префикса IDH_ и порядкового номера раздела, например, IDH_1, IDH_2 и т. д.

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

Во время подготовки текста справочной информации слово-ссылку следует подчеркнуть двойной линией и сразу за этим словом, без пробела, поместить идентификатор раздела справки, к которому должен быть выполнен переход в результате выбора ссылки. Вставленный идентификатор необходимо оформить как скрытый текст. Чтобы задать двойное подчеркивание, нужно выделить слово-ссылку, выбрать команду Формат | Шрифт и в появившемся окне выбрать способ подчеркивания. Аналогичным образом надо задать "скрытый текст" для идентификатора. В качестве примера на 4 приведен вид окна редактора текста во время подготовки файла справочной информации для программы "Сапер 2003". Название игры помечено как ссылка на другой раздел справки, который имеет идентификатор IDH_3.
Помимо ссылки, обеспечивающей переход к другому разделу справки, в документ можно вставить ссылку на комментарий — текст, который появляется во всплывающем окне. Во время работы справочной системы ссылки на комментарии выделяются цветом и подчеркиваются пунктирной линией. При подготовке документа справочной системы комментарии, как и разделы справки, располагают на отдельной странице, однако текст комментария не должен иметь заголовка. Сноска # должна быть поставлена перед текстом комментария. Ссылка на комментарий оформляется следующим образом: сначала надо подчеркнуть одинарной линией слово, выбор которого должен вызвать появление комментария, затем сразу после этого слова вставить идентификатор комментария, оформив его как скрытый текст.

Следует отметить, что справочная информация может быть распределена по нескольким файлам.

Проект справочной системы

Преобразование файла справочной информации в файл справочной системы выполняет входящий в состав Microsoft Help Workshop компилятор. Исходными данными для компилятора является справочная информация, представленная в виде rtf-файлов, и файл проекта справочной системы.

Для того чтобы преобразовать справочную информацию, подготовленную в редакторе текста, в справочную систему, сначала надо создать файл проекта справочной системы. Для этого нужно запустить Microsoft Help Workshop и в меню File выбрать команду New | Help Project ( 5). На экране появится диалоговое окно Project File Name. В этом окне ( 6) надо открыть папку, в которой находится файл справочной информации (rtf-файл), задать имя проекта и щелкнуть на кнопке Сохранить. В результате этих действий будет создан файл проекта (hpj-файл) и станет доступным окно проекта справочной системы ( 7).

Первое, что надо сделать, — это добавить в проект rtf-файл, в котором находится справочная информация. Для этого нужно сначала щелкнуть на кнопке Files, затем в открывшемся окне Topic Files — на кнопке Add ( 8).

На экране появится стандартное диалоговое окно Открытие файла, используя которое можно выбрать нужный rtf-файл. Если справочная информация распределена по нескольким файлам, то операцию добавления файла нужно повторить.

После того как все нужные файлы будут выбраны, надо в окне Topic Files щелкнуть на кнопке ОК. В результате этих действий вновь станет доступным окно проекта, в разделе [FILES] которого будут перечислены файлы, в которых находится справочная информация.

Следующее, что надо сделать, — это назначить числовые значения идентификаторам разделов справочной информации. Для этого в окне проекта надо сначала щелкнуть на кнопке Map, затем, в открывшемся окне Map, — на кнопке Add ( 8). На экране появится окно Add Map Entry ( 9). В поле Topic ID этого окна надо ввести идентификатор раздела справки (идентификаторы были назначены разделам во время создания rtf-файла), в поле Mapped numeric value — число, идентифицирующее раздел. В поле Comment можно ввести комментарий — название раздела справки. После того как будут назначены числовые значения идентификаторам разделов справки, окно Map можно закрыть.

Последнее, что надо сделать, — это настроить вид окна справочной информации. Для этого надо в окне проекта щелкнуть на кнопке Windows, в поле Create a window named открывшегося окна Create a window ( 10) ввести слово main и щелкнуть на кнопке ОК.

На экране появится окно Window Properties, в поле Title bar text вкладки General которого нужно ввести заголовок главного окна создаваемой справочной системы ( 11).

На этом процесс создания проекта простой справочной системы можно считать завершенным ( 12). Теперь можно выполнить компиляцию. Для этого надо в меню File выбрать команду Compile, в появившемся диалоговом окне Compile a Help File установить флажок Automatically display Help file in WinHelp when done (Автоматически показывать созданную справочную систему по завершении компиляции) и щелкнуть на кнопке Compile ( 13).
По завершении компиляции на экране появится окно с информационным сообщением о результатах компиляции и, если компиляция выполнена успешно, окно созданной справочной системы. Файл справочной системы (HLP-файл) компилятор поместит в ту папку, в которой находится файл проекта.
Вывод справочной информации

Обычно окно справочной системы становится доступным в результате нажатия клавиши <F1> или выбора в меню Справка команды ?.

Для того чтобы во время работы программы пользователь, нажав клавишу <F1>, мог получить справочную информацию, надо чтобы свойство HelpFile главного окна приложения содержало имя файла справочной системы, а свойство Helpcontext — числовой идентификатор нужного раздела ( 14).

Для каждого компонента формы можно задать свой раздел справки. Раздел справки, который появляется, если фокус находится на компоненте и пользователь нажимает клавишу <F1>, определяется значением свойства Helpcontext этого компонента. Если значение свойства Helpcontext элемента управления равно нулю, то при нажатии клавиши <F1> появляется тот раздел справки, который задан для формы^приложения.

Для того чтобы справочная информация появилась на экране в результате выбора в меню ? команды Справка, надо создать функцию обработки события onclick для соответствующей команды меню. Процесс создания функции обработки события для команды меню ничем не отличается от процесса создания функции обработки события для элемента управления, например, для командной кнопки: в списке объектов надо выбрать объект типа TmenuItem, для которого создается функция обработки события, а во вкладке Events — событие.

Ниже приведена функция обработки события onclick для команды Справка меню ?.
// выбор в меню ? команды Справка
void__fastoall TForml::N3Click(TObject *Sender)
{
WinHelp(Forml->Handle,"saper.hip",HELP_CONTEXT,1);
}

Вывод справочной информации выполняет функция winHelp, которой в качестве параметра передается идентификатор окна программы, которая запрашивает вывод справочной информации, файл справки, константу HELP_CONTEXT и идентификатор раздела, содержимое которого должно быть отражено.
HTML Help Workshop

Помимо стандартного, классического способа представления справочной информации, в современных программах все чаще используется представление информации в интернет-стиле ( 15).

Основой современной справочной системы являются компилированные HTML-документы — файлы с расширением chm. Chm-файл получается путем компиляции (объединения) файлов, составляющих HTML-документ.

Отображение справочной информации обеспечивает операционная система.

Создать chm-файл можно при помощи утилиты Microsoft HTML Help Workshop. Исходной информацией для компилятора справочной системы являются файлы HTML, файлы иллюстраций и файл проекта.

Чтобы получить chm-файл, надо:
• подготовить справочную информацию в виде набора HTML-документов;
• создать файл проекта;
• создать файл контекста (содержания);
• выполнить компиляцию.

Последние три из перечисленных выше шагов выполняются в программе HTML Help Workshop.
Подготовка справочной информации

Подготовить справочную информацию в HTML-формате можно при помощи любого редактора текста. Наиболее быстро это можно сделать, если редактор позволяет сохранить набранный текст как HTML-документ. Можно воспользоваться и встроенным редактором Microsoft HTML Help Workshop, но для этого надо знать язык HTML (по крайней мере, его основы).

В простейшем случае вся справочная информация может быть помещена в один HTML-файл. Однако если для навигации по справочной системе предполагается использовать вкладку Содержание (см. 15), в которой будут перечислены разделы справочной информации, то в этом случае информацию каждого раздела нужно поместить в отдельный HTML-файл.
Использование Microsoft Word

Сначала нужно набрать текст разделов справки (каждый раздел в отдельном файле). Заголовки разделов и подразделов надо оформить одним из стилей Заголовок. Заголовки разделов, как правило, оформляют стилем Заголовок1, подразделов — стилем Заголовок 2.

Следующее, что надо сделать, — это вставить закладки в те точки документа, в которые предполагаются переходы из других разделов справочной системы. Чтобы вставить закладку, нужно установить курсор в точку текста, в которой должна быть закладка, из меню Вставка выбрать команду Закладка и в поле Имя закладки диалогового окна Закладка ввести имя закладки ( 16).

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

После того как будут расставлены закладки, можно приступить к расстановке ссылок. Различают ссылки, которые обеспечивают навигацию внутри раздела, и те, которые обеспечивают переход к другому разделу справочной системы.

Чтобы вставить ссылку, обеспечивающую навигацию внутри раздела, надо выделить фрагмент текста (слово или фразу), при выборе которого должен быть выполнен переход, из меню Вставка выбрать команду Гиперссылка, в появившемся окне Добавление гиперссылки ( 17) сначала щелкнуть на кнопке Связать с местом в этом документе, затем — выбрать закладку или заголовок, к которому должен быть выполнен переход.
Если нужно вставить в документ ссылку на раздел справки, который находится в другом файле, то в диалоговом окне Добавление гиперссылки надо щелкнуть на кнопке Файл и в появившемся стандартном окне выбрать имя нужного HTML-файла.

После того как в документ будут помещены все необходимые гиперссылки, документ нужно сохранить в HTML-формате.

Использование HTML Help Workshop


Использование HTML-редактора, входящего в состав HTML Help Workshop, предполагает знание основ HTML — языка гипертекстовой разметки (далее приведены краткие сведения об HTML, которых достаточно для того, чтобы создать вполне приличную справочную систему).

Чтобы создать HTML-файл, надо запустить HTML Help Workshop, из меню File выбрать команду New | HTML File и в появившемся окне HTML Title (   18) задать название раздела справки, текст которого будет находиться в создаваемом файле.

После щелчка на кнопке ОК становится доступным окно HTML-редактора, в котором находится шаблон HTML-документа. В этом окне, сразу после строки <BODY>, можно набирать текст.

Основы HTML

HTML-документ представляет собой текст, в который помимо обычного текста включены специальные последовательности символов — теги. Тег начинается символом < и заканчивается символом >. Теги используются программами отображения HTML-документов для форматирования текста в окне просмотра (сами теги не отображаются).

Большинство тегов парные. Например, пара тегов <Н2> </H2> сообщает программе отображения HTML-документа, что текст, который находится между этими тегами, является заголовком второго уровня и должен быть отображен соответствующим стилем.

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

Таблица 8.1. HTML-теги


Тег

Пояснение


<TITLE> Название </TITLE>


Задает название HTML-документа. Программы отображения HTML-документов, как правило, выводят название документа в заголовке окна, в котором документ отображается. Если название не задано, то в заголовке окна будет выведено название файла


<BODY BACKGROUND = "Файл" BGCOLOR="Цвет" ТЕХТ="Цвет">


Параметр BACKGROUND задает фоновый рисунок, BGCOLOR — цвет фона, TEXT — цвет символов HTML-документа


<BASEFONT FАСЕ="Шрифт" SIZE=n>


Задает основной шрифт, который используется для отображения текста: FACE— название шрифта, SIZE — размер в относительных единицах. По умолчанию значение параметра SIZE равно 3. Размер шрифта заголовков (см. тег <H>) берется от размера, заданного параметром SIZE


<H1> </Н1>


Определяет текст, находящийся между тегами <Н1> и </Н1>, как заголовок уровня 1. Пара тегов <Н2> </H2> определяет заголовок второго уровня, а пара <H3> </H3> — третьего


<BR>


Конец строки. Текст, находящийся после этого тега, будет выведен с начала новой строки


<Р> </Р>


Текст, находящийся внутри этих тегов, является параграфом


<В> </В>


Текст, находящийся внутри этой пары тегов, будет выделен полужирным


<I> </I>


Текст, находящийся внутри этой пары тегов, будет выделен курсивом


<А NAME="Закладка"> </А>


Помечает фрагмент документа закладкой. Имя закладки задает параметр NAME. Это имя используется для перехода к закладке


<А НRЕF="Файл.htm#Закладка"> </А>


Выделяет фрагмент документа как гиперссылку, при выборе которой происходит перемещение к закладке, имя которой указано в параметре HREF


<IMG SRC= "Иллюстрация" >


Выводит иллюстрацию, имя файла которой указано в параметре SRC


<!-- -->


Комментарий. Текст, находящийся между дефисами, на экран не выводится


Набирается HTML-текст обычным образом. Теги можно набирать как прописными, так и строчными буквами. Однако, для того чтобы лучше была видна структура документа, рекомендуется записывать все теги строчными (большими) буквами. Следующее, на что надо обратить внимание — это то, что программы отображения HTML-документов игнорируют "лишние" пробелы и другие "невидимые" символы (табуляция, новая строка). Это значит, что для того чтобы фрагмент документа начинался с новой строки, в конце предыдущей строки надо поставить тег <BR>, а для того чтобы между строками текста появилась пустая строка, в HTML-текст надо вставить два тега <BR> подряд.

Работая с HTML-редактором в программе HTML Help Workshop, уже в процессе набора HTML-текста можно увидеть, как будет выглядеть набираемый текст. Для этого надо из меню View выбрать команду In Browser или щелкнуть на командной кнопке, на которой изображен стандартный значок Internet Explorer.

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

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

Сначала надо запустить HTML Help Workshop, из меню File выбрать команду New | Project и в окне New Project задать имя файла проекта создаваемой справочной системы ( 20). После щелчка на кнопке Далее в этом и следующем окнах окно HTML Help Workshop должно выглядеть так, как показано на 21.

Первое, что надо сделать,— это сформировать раздел [FILES], который должен содержать имена HTML-файлов, в которых находится справочная информация. Чтобы добавить в раздел [FILES] имя файла, надо щелкнуть на кнопке Add/Remove topic files (см. 21), а затем в появившемся диалоговом окне Topic Files ( 22) — на кнопке Add, после чего в появившемся стандартном диалоговом окне Открыть выбрать HTML-файл раздела справки. Если справочная информация распределена по нескольким файлам, то операцию добавления нужно повторить несколько раз. После того как в диалоговом окне Topic Files будут перечислены все необходимые для создания справочной информации HTML-файлы, нужно щелкнуть на кнопке ОК. В результате этих действий в файле проекта появится раздел [FILES], в котором будут перечислены HTML-файлы, используемые для создания справочной системы ( 23).

Следующее, что надо сделать, — это задать главный (стартовый) раздел и заголовок окна справочной системы. Заголовок и имя файла главного раздела вводятся соответственно в поля Title и Default file вкладки General диалотового окна Options ( 24), которое появляется в результате щелчка на кнопке Change project options (см. 21).

Если для навигации по справочной системе предполагается использовать вкладку Содержание, то надо создать файл контекста. Чтобы это сделать, нужно щелкнуть на вкладке Contents, подтвердить создание нового файла и задать имя файла контекста, в качестве которого можно использовать имя проекта. В результате станет доступной вкладка Contents ( 25), в которую нужно ввести содержание — названия разделов справочной системы.

Содержание справочной системы принято изображать в виде иерархического списка. Элементы верхнего уровня соответствуют разделам, а подчиненные им элементы — подразделам и темам.

Чтобы во вкладку Contents добавить элемент, соответствующий разделу справочной системы, нужно щелкнуть на кнопке Insert a heading, в поле Entry title появившегося диалогового окна Table of Contents Entry ( 26) ввести название раздела и щелкнуть на кнопке Add. На экране появится окно Path or URL ( 27). В поле HTML titles этого окна будут перечислены названия разделов (заголовки HTML-файлов) справочной информации, которая находится во включенных в проект файлах (имена этих файлов указаны в разделе [FILES] вкладки Project). Если вместо названия раздела будет указано имя файла, это значит, что в соответствующем файле нет тега <TITLE>. Выбрав раздел, надо щелкнуть на кнопке ОК. В результате перечисленных выше действий во вкладке Contents появится строка с названием раздела справочной информации.

При необходимости изменить значок, соответствующий добавленному разделу, следует щелкнуть на кнопке Edit selection и, используя список Image index вкладки Advanced окна Table of Contents, выбрать нужный значок (обычно рядом с названием раздела или подраздела изображена книжка).

Подраздел добавляется точно так же, как и раздел, с тем только отличием, что после того как подраздел будет добавлен, нужно щелкнуть на кнопке Move selection right. В результате чего уровень заголовка понизится, т. е. раздел станет подразделом.

Элементы содержания, соответствующие темам справочной информации, добавляются аналогичным образом, но процесс начинается щелчком на кнопке Insert a page.

Иногда возникает необходимость изменить порядок следования элементов списка содержания или уровень иерархии элемента списка. Сделать это можно при помощи командных кнопок, на которых изображены стрелки. Кнопки Move selection up и Move selection down перемещают выделенный элемент списка, соответственно, вверх и вниз. Кнопка Move selection right перемещает выделенный элемент вправо, т. е. делает его подчиненным предыдущему элементу списка. Кнопка Move selection left выводит элемент из подчиненности предыдущему элементу.

В качестве примера на 28 приведена вкладка Contents справочной системы программы "Сапер 2003".
Компиляция

После того как будут определены файлы, в которых находится справочная информация (сформирован раздел [FILES]) и подготовлена информация для формирования вкладки Содержание (создан файл контекста), можно выполнить компиляцию — преобразовать исходную справочную информацию в файл справочной системы (chm-файл).

Исходной информацией для HTML Help компилятора являются:
• файл проекта (hhp-файл);
• файл контекста (hhc);
• файлы справочной информации (htm-файлы);
• файлы иллюстраций (gif- и jpg-файлы).

Результатом компиляции является файл справочной системы (chm-файл).

Чтобы выполнить компиляцию, надо в меню File выбрать команду Compile, в появившемся диалоговом окне Create a compiled file ( 29) установить переключатель Automatically display compiled help file when done (после компиляции показать созданный файл справки) и щелкнуть на кнопке Compile. В результате этого будет создан файл справки и на экране появится окно справочной системы, в котором будет выведена информация главного раздела. /
Вывод справочной информации

Вывести справочную информацию, которая находится в chm-файле, можно несколькими способами. Наиболее просто это сделать при помощи утилиты hh.exe, являющейся составной частью Windows. Вызвать утилиту отображения справочной информации и передать ей в качестве параметра имя файла справочной системы можно при помощи функции winExec. У функции winExec два параметра. Первый — имя выполняемого файла программы, которую надо запустить, и командная строка. Второй параметр определяет способ отображения окна запускаемой программы. Окно запускаемой программы может быть развернуто на весть экран (SW_MAXIMIZE), запущенная

программа может работать в свернутом окне (SW_MINIMIZE) или окно программы может иметь размер и положение такие, какими они были в предыдущем сеансе работы (SW_RESTORE). Ниже в качестве примера приведена функция обработки события click на кнопке Справка. Функция обеспечивает вывод справочной информации, которая находится в файле saper.chm.
// Щелчок на кнопке Справка
void __fastoall TForml::Button2Click(TObject *Sender)
{
WinExec("hh saper.chm",SW_RESTORE); }


 
На главную | Содержание | < Назад....Вперёд >
С вопросами и предложениями можно обращаться по nicivas@bk.ru. 2013 г. Яндекс.Метрика