Содержание
• Глава 21. СОЗДАНИЕ ВСТРОЕННОЙ СПРАВОЧНОЙ СИСТЕМЫ
• ЭТАПЫ РАЗРАБОТКИ
• ПЛАНИРОВАНИЕ СИСТЕМЫ СПРАВОК
• СОЗДАНИЕ ТЕКСТОВЫХ ФАЙЛОВ
  • Задание идентифицирующей строки и организация перекрестных ссылок
  • Задание названия раздела
  • Определение ключевых слов
  • Определение условий компиляции
  • Указание порядка просмотра связанных разделов
  • Вставка графики
  • Выполнение макрокоманд
  • Отображение текста раздела в дополнительном окне
• РАЗРАБОТКА ПРОЕКТНОГО ФАЙЛА
  • Секция OPTIONS
• Секция FILES
• Секция WINDOWS
• Секция BITMAPS
• Секция MAP
• Секция ALIASES
• Секция Conftg
• Секция BAGGAGE
• ФАЙЛ СОДЕРЖАНИЯ СПРАВОЧНОЙ СЛУЖБЫ
• КОМПИЛЯЦИЯ, ТЕСТИРОВАНИЕ И СВЯЗЬ С ПРОГРАММОЙ
• МАКРОКОМАНДЫ WINHELP

Глава 21

СОЗДАНИЕ ВСТРОЕННОЙ СПРАВОЧНОЙ СИСТЕМЫ

Ни одна серьезная программная разработка не обходится без создания контекстно-чувствительной справочной службы (далее - Help-службы).

В этом разделе описан процесс создания Help-службы и настройка программы на работу с ней. Для реализации процесса вам понадобятся как минимум две утилиты: текстовый RTF-редактор и компилятор Help-файлов. В качестве текстового редактора обычно используется Microsoft Word (далее просто Word), поддерживающий расширенный текстовый формат RTF (стандартный для Windows 32 текстовый редактор WordPad также поддерживает формат RTF, но в нем нет удобных средств вставки специальных управляющих символов). В ранних версиях Delphi в качестве компилятора Help-файлов поставлялся стандартный компилятор hcsi.exe. С последними версиями 4 и 5 поставляется более удобная утилита Microsoft Help Workshop (файл hcw.exe из каталога help | tools каталога размещения Delphi).

21.1. ЭТАПЫ РАЗРАБОТКИ

Разработка Help-службы требует решения следующих основных задач.

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

21.2. ПЛАНИРОВАНИЕ СИСТЕМЫ СПРАВОК

• Любой раздел может содержать список подчиненных или связанных разделов, т. е. разрешается произвольная иерархия справочной службы.
• Полезно структурировать разделы по роду предоставляемой ими информации. Например, предусмотреть разделы для начинающего пользователя с пошаговыми инструкциями, выделить примеры использования программы, предоставить информацию опытным пользователям с точным и детальным описанием каждой программной функции, а также информацию о “продвинутых” возможностях программы и т. п.
• Каждый раздел должен, по возможности, отображаться в одном распахнутом окне. Избегайте слишком длинных пояснений, лучше разбейте такой комментарий на несколько разделов. Учтите, что согласно исследованиям лишь менее 30% людей могут читать текст на экране так же легко и быстро, как на бумаге.
• Старайтесь описывать справочную информацию простым и ясным языком. Избегайте использования профессионального жар- гонизма, а также фраз типа “как вам это известно”. Юмор, безусловно, увеличит эффективность справки, однако его чрезмерное количество может навредить главному - помощи пользователю.
• Структурируйте текст, вставляйте в него больше рисунков, выделяйте важную информацию шрифтами и цветом. Помните, что монотонный текст (как и чрезмерно “раскрашенный”) резко увеличивает утомляемость пользователя и затрудняет усвоение информации.

21.3. СОЗДАНИЕ ТЕКСТОВЫХ ФАЙЛОВ

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

При создании текстовых файлов учтите следующие особенности их подготовки:

• Количество RTF-файлов может быть произвольным. Вы можете поместить всю справочную информацию в один файл или предусмотреть для каждого раздела отдельный файл - все зависит от объема и структуризации Help-службы и ваших личных пристрастий.
• В пределах одного файла каждый раздел отделяется от другого служебным символом конца страницы (с помощью Word этот символ вставляется клавишами Ctrl+Enter).
• Любой раздел, доступный с помощью перекрестных ссылок или индексных указателей, должен иметь связанный с ним идентификатор - уникальную текстовую строку.
• Раздел может иметь название и связанный с ним список ключевых слов.

В текстовый файл включаются такие управляющие символы:

21.3.1. Задание идентифицирующей строки и организация перекрестных ссылок

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

Идентифицирующая строка может содержать любые символы, кроме #, @, !, *, =, >, % и пробелов. Разница в высоте латинских букв (но не кириллицы!) игнорируется. Длина строки - до 255 символов.

В качестве идентификаторов имеет смысл использовать текст заголовка раздела, в котором пробелы заменены символами подчеркивания, - в этом случае вам не придется вспоминать идентификатор при ссылке на него.

Идентификатор задается с помощью сноски “#” в самом начале раздела.

Например:

Назначение_программы

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

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

На рис. 21.1 показано окно редактора Word с фрагментом текста Help-службы.

Раздел перекрестные ссылки связан с идентификатором hypertext, который задан в виде текста сноски “#”, предшествующей первому символу заголовка (для задания сноски выберите в главном меню Word'a Вставка | Сноска, в окне Сноски выберите Другая и введите символ “#” в строке 1, 2, 3).

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

Поскольку идентификатор выделяется скрытым текстом” в обычном режиме он скрыт и становится виден только в режиме отображения служебных символов после щелчка по кнопке V на инструментальной панели Word.

Рис. 21.1. Пример задания перекрестных ссылок

Для задания скрытого текста в редакторе Word необходимо выделить текст и применить к нему команду Hidden. Для этого можно воспользоваться опцией Формат | Шрифт и в разделе Эффекты щелкнуть по опции скрытый.

Поскольку эту последовательность действий; при написании текста, справочной службы придется выполнять очень часто, полезно предварительно настроить Word: выберите Сервис | Настройка, на панели.

Команды в окне категории выберите все команды, а в окне Команды - Hidden и “перетащите” мышью (нажав и не отпуская, левую, кнопку) эту команду на инструментальную, панельку. Теперь, чтобы выбрать скрытый текст, достаточно выделить его и щелкнуть по новой кнопке. Для Задания перечеркнутого или дважды подчеркнутого текста нет специальной команды, поэтому автоматизировать соответствующие действия нужно с помощью макроса. Чтобы создать Макрос сначала выделите текст, затем выберите Сервис | Макрос | Начать запись, в окне Запись макроса укажите подходящее имя (например, Зачеркнутый) и щелкните по кнопке ''Панели, затем из окна Настройка перетащите имя макроса на панель инструментов и накройте окно. Теперь указатель мыши будет иметь вид кассеты с лентой, а на экране появится соответствующая панелька управления. Выберите Формат | Шрифт [Зачеркнутый и остановите запись макроса щелчком по левой кнопке панельки управления или с помощью Сервис | Макрос |Остановить запись.

Любой вызываемый раздел может отображаться в основном окне справки или в окне пояснений. Это окно появляется поверх основного окна (такие окна иногда называют “всплывающими”) и обычно используется для пояснений (рис. 21.2).

Рис. 21.2. Пример использования окна пояснений

Чтобы показать раздел в окне пояснений, нужно выделить текст перекрестной ссылки шрифтом с одинарным подчеркиванием, на пример:

Для проверки АSI-шиныASI и связанных с ней реле и датчиков используется опция Сервис | Контроль шины главного меню.

В выделенную скрытым текстом часть ссылки можно вставить следующие дополнительные управляющие символы:

@ указывает HLP-файл, в котором расположена нужная тема;> указывает тип окна для отображения раздела.[Методика работы с Microsoft Word дается для версии 97. Для других версий могут быть незначительные отличия.]

Символы “*” и “%” вставляются непосредственно перед идентификатором раздела и, так же как и он, оформляются скрытым текстом. Например:

ГИПЕРТЕКСТ%НУРЕРТЕХТ

Теперь в справочном окне слово гипертекст ничем, кроме формы расположенного над ним указателя мыши, не будет отличаться от обычного текста справки, тем не менее щелчок по нему вызовет переход к теме hypertext. В ссылке можно указать только один из символов отмены выделения - “*” или “%”.

Символы “@” и “>”, наоборот, вставляются в конце скрытого текста и за ними должны следовать:

• маршрут доступа и имя HLP-файла - для символа “@”;
• имя типа окна, в котором следует отобразить раздел - для символа “>”; это окно должно определяться в файле проекта (см. п. 21.4.3).

Например, если раздел hypertext расположен в файле c:\proba\proba.hlp и должен показываться в дополнительном окне типа wind, соответствующая ссылка будет такой:

ГИПЕPTEKCT HYPERTEXT@C:\PRQBA\PROBA.HLP>WIND

Обратите внимание: символы “@” и “>”, как и следующие за ними символы маршрута и имени типа окна, должны оформляться скрытым текстом. Если, как в приведенном примере, в ссылке одновременно указываются и маршрут, и тип окна, порядок их следования безразличен, однако в одной ссылке можно указать только один символ “@” и (или) один символ “>”. Замечу, что имя типа окна нужно указывать заглавными буквами, даже если в файле проекта оно определено строчными.

21.3.2. Задание названия раздела

Название раздела используется в Help-службе следующим образом:

На рис. 21.3 показано окно поиск справочной службы Delphi.

Рис. 21.3. Окно Поиск со списком названий найденных разделов (“З. Выберите нужный раздел ...”)

Название раздела задается с помощью сноски “$”, которая должна предшествовать первому символу текста раздела. На рис. 21.4 показан пример окна Word с названием Режим|0тладка для раздела Отладочный режим. Название раздела записывается в тексте сноски и отделяется от символа “$” одним пробелом. В тексте названия можно указывать любые символы, в том числе и пробелы. Максимальная длина названия - 255 символов. Обычно название раздела совпадает с его заголовком.

Рис. 21.4. Вставки названия раздела

21.3.3. Определение ключевых слов

Help-служба позволяет искать разделы по связанным с ними ключевым словам. В диалоговом окне Поиск (см. выше рис. 21.3) предусмотрены строка (1) для ввода ключевых слов и возможность выбора их из списка (2). Для любого раздела можно назначить сколько угодно ключевых слов и наоборот - с любым ключевым словом можно связать сколько угодно разделов.

Для определения ключевого слова в начале раздела (до первого символа текста раздела) ставится сноска, помеченная латинской буквой “К” или “k”. Например:

^к открыть;текст файл;ASCII;текст

Все связанные с разделом ключевые слова помещаются в текст сноски и отделяются от “К” одним пробелом, а друг от друга символом “;”. Группы связанных по смыслу ключевых слов объединяются во фразы, которые отделяются друг от друга пробелами. Help-служба ищет и отображает в списке выбора названия всех разделов, ключевые слова которых перечислены в одной фразе. Например, если для приведенной выше сноски пользователь ввел слово файл, будут представлены названия разделов, связанных со словами файл, ASCII и текст.

Помимо основной таблицы ключевых слов в Help-службе может быть определена дополнительная таблица. Слова из дополнительной таблицы не показываются в окне Поиск. Их использование возможно только вмакрокомандах ALink и TestALink (СМ. П. 21.7). Для

вставки ключевых слов в дополнительную таблицу используется сноска, помеченная латинской буквой “А”:

^А таблица/слово

21.3.4. Определение условий компиляции

Подобно директивам условной компиляции Delphi в RTF-файл можно вставлять указания Help-компилятору помещать или не помещать в результирующий файл тот или иной раздел. Такие указания могут понадобиться на этапе отладки справочной службы, а также при создании нескольких версий приложения (например, справочная служба демонстрационной версии может не содержать некоторые разделы, определенные для основной версии). Они вставляются в текст с помощью сноски, помеченной символом “*”. Чтобы включить условный раздел в Help-файл или исключить его из файла, ключевое слово, определяемое сноской “*”, должно указываться в секции соответственно include или Exclude файла проекта справочной службы (см. п. 21.4.1).

В тексте сноски “*” можно указать одно или несколько управляющих слов (следующие друг за другом слова в тексте сноски разделяются символом “;”). Раздел будет включен в Help-файл, если хотя бы одно из связанных с ним управляющих слов указано в секции include файла проекта (если раздел не имеет сноски “*”, он всегда включается в результирующий файл). Управляющие слова могут содержать любые символы, кроме “;” и пробелов. Например:

Test_Build; AppVersionI; DebuggVer

21.3.5. Указание порядка просмотра связанных разделов

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

В этом списке каждой опции меню поставлена в соответствие комбинация символов (гл_меню: 010, меню_файл:025 и т. п.), определяющая порядковый номер просмотра раздела. Все разделы, помеченные соответствующими комбинациями, сортируются в обычном ASCII-порядке следования символов этих комбинаций. Таким образом, раздел Редактировать, помеченный гл_меню:010, будет следовать за Файл (гл_меню: 005), но предшествовать Окно (гл_меню: 015).

Чтобы связать с разделом код для указания порядка просмотра раздела, необходимо вставить сноску “+”:

*гл_меню:010

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

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

21.3.6. Вставка графики

Если вы создаете RTF-файл с помощью редактора Word, вы можете вставлять в текст графические врезки средствами редактора. Единственное ограничение: файлы с графикой должны соответствовать формату bmp. Однако Help-компилятор имеет и собственные средства вставки графических врезок с помощью внешних вмр-файлов. Ниже описывается, как это сделать.

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

(bmc filename.bmp}

{bml filename.bmp}

{bmr filename.bmp}

Здесь filename - имя вмр-файла; bmc, bml, bmr - команды, управляющие положением картинки относительно текста.

Команда bmc (от BitMap Char) предписывает рассматривать графический образ как символ. В этом случае он располагается точно на том месте в тексте справки, где указана директива вставки. Оставшаяся часть текста слева и справа от директивы разместится соответственно слева и справа от врезки, а высота строки с врезкой будет автоматически выбрана так, чтобы текст не накладывался на картинку. Команды bml (BitMap Left) и bmr (BitMapRight) заставят картинку прижаться соответственно к левому или правому краю окна справки. Все перечисленные в директивах ДМР-файлы должны располагаться в каталоге, указанном в опции bmroot секции [Options] проектного файла (см. п. 21.4.1).

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

Этот графический образ [bmc flower.bmp]Bitmap Cross вставлен непосредственно в текст и служит перекрестной ссылкой. {bml hardware.bmp}Bitmap Comment Если щелкнуть мышью по расположенной слева картинке, появится дополнительное окно с пояснениями. Такие окна удобно использовать для пояснения второстепенных деталей справки.

{bmr legal.bmp} Правая картинка не является перекрестной ссылкой. Она просто иллюстрирует одно из многочисленных изображений, поставляемых для текстового редактора MS Word.

На рис. 21.5 показан экран Help-службы с графическими вставками. Для его создания использовался приведенный выше фрагмент RTF-файла.

Рис. 21.5. Использование графических врезок

21.3.7. Выполнение макрокоманд

При открытии того или иного раздела можно выполнить одну или несколько макрокоманд. С помощью макрокоманд можно гибко воздействовать на состояние окна справочной службы: его положение, размеры, цвет, содержимое меню и инструментальных кнопок, отображать другие Help-файлы, выполнять внешние программы и т. д. (см. п. 21.7). Для указания макрокоманды, исполняющейся в момент открытия раздела, ее имя задается в тексте сноски “!”. Сноска указывается вместе с другими сносками в самом начале раздела (до первого символа текста). Например, для вставки в инструментальную панель кнопок просмотра связанных разделов сноска имеет такой вид:

!BrowseButtons ( )

Если нужно указать несколько макрокоманд, они отделяются в тексте сноски символами “;”.

21.3.8. Отображение текста раздела в дополнительном окне

Помимо основного окна в справочной службе можно определить множество дополнительных окон, каждое из которых в общем случае будет иметь свой цвет, заголовок, размеры и т. д. Дополнительные окна описываются в секции [windows] проектного файла (см. п. 21.4.). Чтобы указать, что раздел справки должен по умолчанию отображаться в дополнительном окне, используется ссылка “>” (с помощью модификации гиперссылки можно заменить умалчиваемый тип окна на другой, см. ниже). В тексте ссылки указывается тип окна так, как он определен в проектном файле, например:

^> wind

В ссылке “>” может указываться только одно умалчиваемое окно. Другим способом указания дополнительного окна является модификация перекрестной ссылки (см. п. 21.3.1). Если, например, в

ГИПЕРТЕКСТ НУРЕКТЕХТ

раздел hypertext должен отображаться в окне windi, ссылка оформляется следующим образом:

ГИПЕРТЕКСТНУРЕКТЕХТ>WIND1

Окно, указанное в тексте ссылки, имеет приоритет перед умалчиваемым окном, если оно определено сноской">" для раздела. Для нашего примера это означает, что окно windi будет использоваться для отображения ссылки гипертекст даже в том случае, если раздел hypertext имеет сноску “>”, в которой указано другое окно.

21.4. РАЗРАБОТКА ПРОЕКТНОГО ФАЙЛА

Проектный файл служит основным управляющим документом для Help-компилятора. В Windows 32 он создается с помощью утилиты Microsoft Help Workshop (MS HW) и представляет собой AS-CII-текстовый файл, содержащий несколько секций. Секция - это фрагмент текста, состоящий из заголовка и одной или нескольких следующих за ним строк (опций) вида

ИМЯ_ПАРАМЕТРА = ЗНАЧЕНИЕ,

подобно тому как организованы файлы инициации ini.

Для запуска MS HW следует загрузить файл help | tools | hcw.exe из папки размещения Delphi. Если файл проекта уже был ранее создан, для работы с ним используется опция File | open или соответствующая кнопка инструментальной панели MS HW. Для создания нового проектного файла выберите File | New и в дополнительном диалоговом окне - Help project; после указания имени создаваемого Help-файла в стандартном диалоговом окне save File окно MS HW приобретет вид, показанный на рис. 21.6.

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

21.4.1. Секция OPTIONS

Секция [Options] создается или изменяется с помощью кнопки options. Оно содержит общие для всей справочной службы установки и, в частности, определяет умалчиваемую тему, показываемую при открытии HELP-службы, заголовок основного окна, используемый в текстах язык и т. п.

После нажатия кнопки options появляется многостраничное окно, показанное на рис. 21.7.

Рис. 21.6. Окно утилиты Microsoft Help Workshop

Display this text... - определяет текст, который будет помещен

В окно Справка | Версия справочной службы;

Рис. 21.7. Окно установки параметров секции Options

if users paste... - определяет текст, который будет добавляться в конце копируемой через Clipboard или печатаемой справочной информации.

Страница Compession

Эта страница управляет сжатием результирующего файла.

None - результирующий файл не сжимается;

Maximum - результирующий файл максимально сжимается;

Custom - выбирает алгоритм сжатия результирующего файла.

Страница Sorting

Задает язык и способ сортировки ключевых слов.

Language of Help file - определяет используемый для сортировки ключевых слов язык;

Other - определяет язык сортировки по его индексу;

Non-spacing marks - если переключатель выбран, при сортировке игнорируются кавычки и апострофы; Symbols - если переключатель выбран, при сортировке игнорируются пробелы и знаки препинания; separate index... - содержит перечень символов, которые используются для указания нижних уровней сортировки.

Страница Files

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

Help File - имя результирующего нlр-файла; это имя должно быть указано обязательно;

Log File - имя ASCII-текстового файла, в который компилятор будет помещать свою информацию (может не указываться);

RTF-files - определяет имена исходных файлов с текстами справок; замечу, что изменение имен файлов фактически приводит к изменению секции [Files] (см. ниже п. 21.4.2);

contents file - указывает имя файла содержания, если такой файл создан (см. п. 21.5);

тмр folder - определяет папку для хранения временных файлов компилятора;

substitute path prefix - указывает имя маршрута доступа к rtf и вмр-файлам; используется при перемещении этих файлов в другую папку, чтобы не исправлять множество ссылок во всей справочной информации.

Страница FTS

Управляет созданием индекса для быстрого поиска по отдельным словам или фразам справочного текста. Этот индекс создается при первом обращении к окну поиск.

Generate full text search index - Создавать индекс по всем словам справочных фалов;

Include untitled topics in index - включает в индекс разделы без названия;

Enable search for word only - разрешить поиск только по словам;

Enable search for phrase - разрешить поиск по фразам;

Enable display of matching phrase - разрешить поиск по списку выделенных фраз;

Enable search for similar topics - разрешить поиск по альтернативным словам.

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

Страница Macros

Определяет макрокоманды, автоматически выполняемые при выборе того или иного ключевого слова.

Title that appears... - указывает заголовок окна Найденные разделы при выборе соответствующего слова;

Macro (s) associated with... - связанная со словом макрокоманда;

Add - позволяет добавить слово к списку Keywords;

Remove - удаляет слово из списка Keywords;

Edit - изменяет определение макрокоманды или заголовка для указанного слова.

Страница Build Tags

Содержит список условий, включающих разделы в результирующий файл (верхний список) или исключающих их из него (нижний список). Условия касаются только тех разделов, которые помечены ссылкой “*” (см. п. 21.3.4).

Страница Fonts

Определяет шрифты, используемые в справочной системе.

character set - определяет используемый в результирующем файле набор символов (он может отличаться от набора символов на инструментальной машине);

Font in winHelp Dialog boxes - определяет шрифт, используемый в диалоговых окнах справочной службы;

substitute this fonts.. - содержит перечень подстановок, указывающих, какой шрифт в исходном RTF-файле будет заменен при отображении в окне справки и на какой шрифт он будет заменен.

21.4.2. Секция FILES

С помощью этой секции определяются RTF-файлы, содержащие текст, справочной системы. Для нормальной работы компилятора

необходимо определить хотя бы один файл в этой секции. Замечу, что содержимое этой секции автоматически изменяется при изменении списка RTF-files на странице Files окна options (см. п. 21.4.1).

Справочная служба может состоять из множества RTF-файлов. В этом случае все они должны быть перечислены в секции [Files]. Компилятор разрешает задать в этом списке один или несколько ссылочных ASCII-текстовых файлов, каждая строка которых указывает нужный RTF-файл .(т. е. содержит маршрут доступа и имя файла).

21.4.3. Секция WINDOWS

Секция [windows] определяет используемый в справочной службе набор дополнительных окон. Каждое указанное в секции окно характеризуется своим типом, цветом, размерами, заголовком. Только имена перечисленных в секции окон могут указываться в ссылках и сносках “>” RTF-файлов.

Если в секции не определено ни одно окно, щелчок по кнопке window вызовет диалоговое окно для указания имени вновь создаваемого окна и его типа (рис. 21.8).

Рис. 21.8. Диалоговое окно определения имени и типа дополнительного окна

В строке create a window named следует задать имя окна. Замечу, что, если указать имя main, установки, производимые далее, будут относиться к основному окну справочной службы (именно таким способом мне, например, удалось получить нужный заголовок основного окна). С помощью списка Based on this standard window можно выбрать один из трех возможных стандартных типов окна:

procedure - окно предназначено для вывода текстов процедур; оно позиционируется в правом верхнем углу экрана и при значительной ширине может своим правым краем выйти за пределы экрана;

Reference - обычное справочное окно; позиционируется в левом верхнем углу, занимает приблизительно 2/3 экрана по высоте и ширине;

Error message - окно предназначено для вывода сообщений об ошибках, позиционируется по центру экрана, занимает почти всю высоту экрана и 3/4 его ширины.

Замечу, что все три типа создают стандартные Windows-окна с “толстой” рамкой и заголовком, т. е. их положение и размеры пользователь может изменять по своему усмотрению, так что выбор типа не носит решающего характера. Кроме того, с помощью кнопки Auto sizer на странице position (см. ниже) можно визуально настроить положение и размеры окна.

Если хотя бы одно окно в секции windows уже определено или если диалоговое окно определения типа и имени окна (рис. 21.8) закрыто кнопкой ок, на экране появляется многостраничное окно, показанное на рис. 21.9.

Рис. 21.9. Диалоговое окно определения параметров дополнительных окон

window type - позволяет выбрать одно из ранее определенных окон; все дальнейшие установки на странице General будут осуществляться для указанного в этой строке окна; подобные строки есть на всех других страницах окна window Properties;

Страница Position определяет положение и размеры окна в момент его появления на экране. тор - отступ левого верхнего угла от верхнего края экрана;

Left - отступ левого верхнего угла от левого края экрана;

Height - высота окна;

width - ширина окна;

Adjust for user screen resolution - если переключатель выбран, координаты задаются относительно виртуального экрана с разрешением 1024х1024; если не выбран, координаты указываются в пикселях;

Страница Buttons

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

Contents - кнопка Содержание;

Index - кнопка Индекс;

Find - кнопка Поиск;

Help Topics - кнопка Разделы;

Print - кнопка Печать;

Back - кнопка Назад;

Options — кнопка Параметры;

Страница Color

Позволяет изменять цвет фиксированной (Nonscrolling area) и основной (Topic area) зоны окна. Изменения становятся доступны после щелчка по соответствующей кнопке Add.

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

21.4.4. Секция BITMAPS

Эта секция определяет список папок, в которых компилятор будет искать графические файлы, встроенные в текст справки директивами bmc, bmi, bmr (см. п. 21.3.6). Если ни одна папка не определена, компилятор сможет подключить только те файлы, которые располагаются в том же каталоге, где создается нlр-файл.

21.4.5. Секция MAP

В этой секции следует определить числовые идентификаторы разделов, которые будут автоматически вызываться кнопками Help и клавишей F1 в работающей программе. Напомню, что все видимые компоненты Delphi имеют специальное свойство HeipContext, в которое можно поместить числовой идентификатор раздела справочной службы. Если соответствующий компонент имеет фокус ввода и пользователь нажимает кнопку F1, автоматически включается справочная система Windows, которая отыскивает в ньр-файле и показывает в справочном окне соответствующий раздел. Только разделы, указанные в секции [map] , могут быть контекстно-доступными из работающей программы. Остальные разделы можно просмотреть после вызова справки с помощью выбора ключевых слов, кнопками просмотра связанных разделов или по содержанию справочной службы.

После нажатия кнопки Map в окне MS HW появляется окно, показанное на рис. 21.10.

Рис. 21.10. Окно определения числовых идентификаторов разделов

В списке Map topics IDs to numeric values указываются уже определенные разделы в формате

идентификатор_темы=Неlр Сontext

Здесь идентификатор_темы - идентификатор, определенный сноской # в RTF-файле; HelpContext -присвоенный разделу числовой идентификатор, который можно помещать в свойство HelpContext визуального компонента.

Для задания идентификатора нового раздела или удаления раздела из списка Map используются соответственно кнопки Add и Remove. С помощью кнопки include можно указать ASCII-файл с перечнем идентификаторов разделов и присвоенными им числовыми идентификаторами. Кнопка Edit позволяет отредактировать элемент списка.

При разработке файлов справочной службы, включающих множество разделов, приходится запоминать (или распечатывать) многочисленные идентификаторы разделов, чтобы поставить им в соответствие числовые идентификаторы. Эту проблему можно упростить, если вы назначили идентификаторы такими же, как и названия разделов, заменив в них пробелы символами подчеркивания. В этом случае можно вызвать опцию File | Report, в появившемся диалоговом окне указать имя нlр-файла и имя файла для отчета, установить режим вывода названий (отметить переключатель Titles) и щелкнуть по кнопке Report - MS HW создаст текстовый файл с перечнем названий всех тем. Если этот файл не слишком велик, он будет тут же показан в окне MS HW, и вы сможете без труда вспомнить идентификаторы. Для примера на рис. 21.11 показано, как можно организовать окна MS HW для упрощения создания списка MAP.

Рис. 21.11. Использование отчета по названиям разделов для оргачишции списка MAP

21.4.6. Секция ALIASES

В этой секции можно указать псевдонимы идентификаторов разделов, с помощью которых можно модифицировать секцию Map без изменения RTF-файлов. Назначение кнопок Add, Remove, include и Edit такое же, как и в секции мар. После назначения псевдонима он может использоваться в секции мар вместо идентификатора раздела. Эта возможность облегчает модификацию справочной службы.

21.4.7. Секция Config

Секция [Config] предназначена для указания макрокоманд, которые будут выполняться в момент открытия справочной службы. С ее помощью можно также зарегистрировать подпрограммы из библиотеки) DLL, которые после этого могут использоваться наравне с макрокомандами.

21.4.8. Секция BAGGAGE

Кнопкой Data Files окна MS HW открывается диалоговое окно определения файлов, которые будет использовать справочная служба. Список этих файлов содержит секция [Baggage] проектного файла. Помимо RTF-файлов, которые обычно вставляются в секции [Files] (см. п. 21.4.2), здесь можно также указать файлы библиотек DLL, подпрограммы которых после этого могут использоваться как макрокоманды.

21.5. ФАЙЛ СОДЕРЖАНИЯ СПРАВОЧНОЙ СЛУЖБЫ

Содержание справочной службы оформляется в файле с расширением сыт и становится доступным после нажатия кнопки содержание в справочном окне. Для создания/редактирования содержания используется утилита MS HW.

Чтобы создать файл содержания, запустите MS HW, выберите File i New и затем Help Contents - на экране появится окно, изображенное на рис. 21.12.

В строках Default filename (and window) И Default title В верхней части окна нужно указать соответственно имя ньр-файла, для которого создается содержание, и тип окна для отображения оглавлений, а также заголовок основного окна справочной службы. Замечу, что заголовок Default title, если он задан, переопределяет заголовок, указанный в секции [Options] файла проекта (см. п. 21.4.1).

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

вводе в строке Default filename (and window) имя файла отделяется от имени окна символом “>”.

HelpTest.hlp>WIND

Рис. 21.12. Окно MS H W в режиме создания/редактирования содержания

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

Для вставки в файл элемента содержания нужно щелкнуть по кнопке Add Above или Add Below. В первом случае элемент вставляется перед текущим элементом, во втором - после него. После щелчка по любой из этих кнопок появляется окно, показанное на рис. 21.13.

Переключатели в верхней части окна определяют тип вставляемого элемента:

Heading - вставляется тема; при выборе этого переключателя все расположенные ниже строки, кроме Title, становятся недоступными;

Topic - вставляется раздел;

Macro - вставляется макрокоманда; эта макрокоманда будет выполняться при выборе элемента в окне содержания;

include - вставляется ASCII-текстовый файл с элементами содержания.

Рис. 21.13. Окно определения элемента оглавления

Рис. 21.14. Содержание справочной службы Delphi:

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

21.6. КОМПИЛЯЦИЯ, ТЕСТИРОВАНИЕ И СВЯЗЬ С ПРОГРАММОЙ

Компиляция и тестирование справочной службы не составляют проблемы: с помощью MS HW создайте (или загрузите) проектный файл и щелкните по кнопке save and compile или по инструментальной кнопке. После этого появляется окно, показанное на рис. 21.15.

При компиляции MS HW сворачивает свое окно и вновь раскрывает его после завершения работы компилятора, если отмечен переключатель Minimize window while compiling. После окончания компиляции в нем будут показаны сообщения компилятора. Если компилятор обнаружил ошибки, он сообщает о них, причем некритические ошибки сопровождаются предупреждениями (warnings) и замечаниями (notes), а критические - прерывают компиляцию.

Рис. 21.15. Окно запуска компилятора

Для тестирования скомпилированного справочного файла используется одна из опций меню Test:

contents File - тестирует файл содержания;

close All Help - закрывает все ранее открытые нlр-файлы;

send a macro - посылает в winHelp нужную макрокоманду;

WinHelp api - вызывает нужный раздел справочной службы по присвоенному ему в секции map числовому идентификатору.

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

Связь с программой реализуется с помощью свойств HelpContext видимых компонентов, в которые следует поместить числовые идентификаторы нужных разделов справочной службы так, как они определены. В секции MAP. Кроме того, в свойство Application. HelpFile нужно поместить имя нlр-файла. Обычно эта связь устанавливается в обработчике события ОnCreat главной формы программы. После такой настройки пользователь программы сможет с помощью клавиши F1 получить контекстно-чувствительную справку, т. к. при нажатии F1 автоматически вызывается раздел, числовой идентификатор которого помещен в свойство HeipContext компонента с фокусом ввода. Если Heipcontext компонента с фокусом ввода содержит 0, вызывается раздел, указанный в HelpContext его владельца, а если и у того это свойство не определено, используется HelpContext активной формы (если во всей цепочке владельцев, включая активную форму, свойство HelpContext не определено, нажатие F1 игнорируется).

Рис. 21.16. Сообщение об ошибке вызова раздела

21.7. МАКРОКОМАНДЫ WINHELP

Справочная служба Windows 32 - WinHelp имеет встроенные макрокоманды, которые доступны из справочной службы программы. Макрокоманды могут выполняться в следующих случаях:

• при открытии справочного файла (определяются в секции Соnfig);
• при открытии окна с разделом (определяются сноской “!”);
• при выборе ключевого слова (определяются на странице Macros окна options).

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

 Макрокоманды переходов

 Работа с меню

 Команды условного перехода

Примечание 1. Параметр type в командах поиска ALink, KLink может иметь несколько следующих возможных значений, разделенных пробелом:

Примечание 2. Внутренний числовой идентификатор создается компилятором по идентификатору раздела. Его можно увидеть в окне File | Report после щелчка по кнопке Report при установленном переключателе Hash number.