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


Ни одна серьезная программная разработка не обходится без создания контекстно-чувствительной справочной службы (далее - 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).
ЭТАПЫ РАЗРАБОТКИ
Разработка Help-службы требует решения следующих основных задач.

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

ПЛАНИРОВАНИЕ СИСТЕМЫ СПРАВОК
На этапе планирования необходимо составить перечень разделов справочной службы и нужных перекрестных ссылок. Структура разделов и количество перекрестных ссылок зависит от сложности программы, для которой создается Help-служба, и опыта (и вкуса) разработчика. Полезно учесть следующие рекомендации.

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

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


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

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

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

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


Для задания перекрестных ссылок, реализующих скачок от одного раздела к другому, разделы помечаются уникальными идентифицирующими строками (идентификаторами). Только помеченные идентификаторами разделы можно просматривать в рамках гипертекстовой системы (непомеченные разделы могут быть доступны для просмотра по ключевым словам и в порядке просмотра связанных разделов).
Идентифицирующая строка может содержать любые символы, кроме #, @, !, *, =, >, % и пробелов. Разница в высоте латинских букв (но не кириллицы!) игнорируется. Длина строки - до 255 символов.
В качестве идентификаторов имеет смысл использовать текст заголовка раздела, в котором пробелы заменены символами подчеркивания, - в этом случае вам не придется вспоминать идентификатор при ссылке на него.
Идентификатор задается с помощью сноски “#” в самом начале раздела.
Например:
Назначение_программы
Перекрестная ссылка представляет собой выделенную цветом часть текста, щелчок мышью по которой приводит к смене раздела.
Для кодирования ссылки она выделяется в тексте перечеркнутым или дважды подчеркнутым шрифтом, и сразу за ней без каких либо пробелов указывается идентификатор темы в виде скрытого текста.
На показано окно редактора Word с фрагментом текста Help-службы.
Раздел перекрестные ссылки связан с идентификатором hypertext, который задан в виде текста сноски “#”, предшествующей первому символу заголовка (для задания сноски выберите в главном меню Word'a Вставка | Сноска, в окне Сноски выберите Другая и введите символ “#” в строке 1, 2, 3).
В тексте раздела указаны две перекрестные ссылки в виде слов ссылка и гипертекст. Эти слова выделены соответственно дважды подчеркнутым и перечеркнутым шрифтом, но в окне справочной службы они будут выглядеть одинаково: выделены зеленым цветом и подчеркнуты одной линией. Сразу за каждой ссылкой следует идентификатор соответствующего раздела.
Поскольку идентификатор выделяется скрытым текстом” в обычном режиме он скрыт и становится виден только в режиме отображения служебных символов после щелчка по кнопке V на инструментальной панели Word.
Для задания скрытого текста в редакторе Word необходимо выделить текст и применить к нему команду Hidden. Для этого можно воспользоваться опцией Формат | Шрифт и в разделе Эффекты щелкнуть по опции скрытый.
Примечание
Поскольку эту последовательность действий; при написании текста, справочной службы придется выполнять очень часто, полезно предварительно настроить Word: выберите Сервис | Настройка, на панели.
Команды в окне категории выберите все команды, а в окне Команды - Hidden и “перетащите” мышью (нажав и не отпуская, левую, кнопку) эту команду на инструментальную, панельку. Теперь, чтобы выбрать скрытый текст, достаточно выделить его и щелкнуть по новой кнопке. Для Задания перечеркнутого или дважды подчеркнутого текста нет специальной команды, поэтому автоматизировать соответствующие действия нужно с помощью макроса. Чтобы создать Макрос сначала выделите текст, затем выберите Сервис | Макрос | Начать запись, в окне Запись макроса укажите подходящее имя (например, Зачеркнутый) и щелкните по кнопке ''Панели, затем из окна Настройка перетащите имя макроса на панель инструментов и накройте окно. Теперь указатель мыши будет иметь вид кассеты с лентой, а на экране появится соответствующая панелька управления. Выберите Формат | Шрифт [Зачеркнутый и остановите запись макроса щелчком по левой кнопке панельки управления или с помощью Сервис | Макрос |Остановить запис ь.
Любой вызываемый раздел может отображаться в основном окне справки или в окне пояснений. Это окно появляется поверх основного окна (такие окна иногда называют “всплывающими”) и обычно используется для пояснений (
Чтобы показать раздел в окне пояснений, нужно выделить текст перекрестной ссылки шрифтом с одинарным подчеркиванием, на пример:
Для проверки АSI-шиныASI и связанных с ней реле и датчиков используется опция Сервис | Контроль шины главного меню.
В выделенную скрытым текстом часть ссылки можно вставить следующие дополнительные управляющие символы:
* отменяет выделение текста ссылки цветом;
% отменяет выделение текста ссылки цветом и подчеркиванием;
@ указывает HLP-файл, в котором расположена нужная тема; > указывает тип окна для отображения раздела.[ Методика работы с Microsoft Word дается для версии 97. Для других версий могут быть незначительные отличия. ]
Символы “*” и “%” вставляются непосредственно перед идентификатором раздела и, так же как и он, оформляются скрытым текстом. Например:
ГИПЕРТЕКСТ %НУРЕРТЕХТ
Теперь в справочном окне слово гипертекст ничем, кроме формы расположенного над ним указателя мыши, не будет отличаться от обычного текста справки, тем не менее щелчок по нему вызовет переход к теме hypertext. В ссылке можно указать только один из символов отмены выделения - “*” или “%”.
Символы “@” и “>”, наоборот, вставляются в конце скрытого текста и за ними должны следовать:

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

Например, если раздел hypertext расположен в файле c:\proba\proba.hlp и должен показываться в дополнительном окне типа wind, соответствующая ссылка будет такой:
ГИПЕPTEKCT HYPERTEXT@C:\PRQBA\PROBA.HLP>WIND
Обратите внимание: символы “@” и “>”, как и следующие за ними символы маршрута и имени типа окна, должны оформляться скрытым текстом. Если, как в приведенном примере, в ссылке одновременно указываются и маршрут, и тип окна, порядок их следования безразличен, однако в одной ссылке можно указать только один символ “@” и (или) один символ “>”. Замечу, что имя типа окна нужно указывать заглавными буквами, даже если в файле проекта оно определено строчными.
Задание названия раздела
Название раздела используется в Help-службе следующим образом:
• оно появляется после активизации опции закладка в главном меню Help-службы;
• оно указывается в списке разделов диалоговых окон, связанных с кнопками поиск и хронология инструментальной панели справочного окна.
На показано окно поиск справочной службы Delphi.
Название раздела задается с помощью сноски “$”, которая должна предшествовать первому символу текста раздела. На показан пример окна Word с названием Режим|0тладка для раздела Отладочный режим. Название раздела записывается в тексте сноски и отделяется от символа “$” одним пробелом. В тексте названия можно указывать любые символы, в том числе и пробелы. Максимальная длина названия - 255 символов. Обычно название раздела совпадает с его заголовком.
 
Определение ключевых слов
Help-служба позволяет искать разделы по связанным с ними ключевым словам. В диалоговом окне Поиск (см. выше предусмотрены строка (1) для ввода ключевых слов и возможность выбора их из списка (2). Для любого раздела можно назначить сколько угодно ключевых слов и наоборот - с любым ключевым словом можно связать сколько угодно разделов.
Для определения ключевого слова в начале раздела (до первого символа текста раздела) ставится сноска, помеченная латинской буквой “К” или “k”. Например: к открыть;текст файл;ASCII;текст
Все связанные с разделом ключевые слова помещаются в текст сноски и отделяются от “К” одним пробелом, а друг от друга символом “;”. Группы связанных по смыслу ключевых слов объединяются во фразы, которые отделяются друг от друга пробелами. Help-служба ищет и отображает в списке выбора названия всех разделов, ключевые слова которых перечислены в одной фразе. Например, если для приведенной выше сноски пользователь ввел слово файл, будут представлены названия разделов, связанных со словами файл, ASCII и текст.
Помимо основной таблицы ключевых слов в Help-службе может быть определена дополнительная таблица. Слова из дополнительной таблицы не показываются в окне Поиск. Их использование возможно только вмакрокомандах ALink и TestALink. Для вставки ключевых слов в дополнительную таблицу используется сноска, помеченная латинской буквой “А”: А таблица/слово
Определение условий компиляции
Подобно директивам условной компиляции Delphi в RTF-файл можно вставлять указания Help-компилятору помещать или не помещать в результирующий файл тот или иной раздел. Такие указания могут понадобиться на этапе отладки справочной службы, а также при создании нескольких версий приложения (например, справочная служба демонстрационной версии может не содержать некоторые разделы, определенные для основной версии). Они вставляются в текст с помощью сноски, помеченной символом “*”. Чтобы включить условный раздел в Help-файл или исключить его из файла, ключевое слово, определяемое сноской “*”, должно указываться в секции соответственно include или Exclude файла проекта справочной службы (см. п. 21.4.1).
В тексте сноски “*” можно указать одно или несколько управляющих слов (следующие друг за другом слова в тексте сноски разделяются символом “;”). Раздел будет включен в Help-файл, если хотя бы одно из связанных с ним управляющих слов указано в секции include файла проекта (если раздел не имеет сноски “*”, он всегда включается в результирующий файл). Управляющие слова могут содержать любые символы, кроме “;” и пробелов. Например:
Test_Build; AppVersionI; DebuggVer
Указание порядка просмотра связанных разделов
Связанные в некотором отношении разделы можно просматривать с помощью кнопок на инструментальной панели окна справочной службы. Связь разделов подразумевается создателем службы и может быть любая - по смысловой связанности, в алфавитном порядке, в порядке знакомства с программным продуктом и пр. Ниже представлен пример списка связанных разделов:

В этом списке каждой опции меню поставлена в соответствие комбинация символов (гл_меню: 010, меню_файл:025 и т. п.), определяющая порядковый номер просмотра раздела. Все разделы, помеченные соответствующими комбинациями, сортируются в обычном ASCII-порядке следования символов этих комбинаций. Таким образом, раздел Редактировать, помеченный гл_меню:010, будет следовать за Файл (гл_меню: 005), но предшествовать Окно (гл_меню: 015).
Чтобы связать с разделом код для указания порядка просмотра раздела, необходимо вставить сноску “+”: *гл_меню:010
Обычно в качестве кодовой последовательности выбирают общее название связанных разделов и цифры порядкового номера. Номера полезно задавать с некоторым шагом (в нашем пример шаг равен 5), чтобы была возможность вставлять дополнения в списки разделов и при этом не изменять уже существующие сноски.
Замечу, что кнопки просмотра связанных разделов появляются в справочном окне автоматически, только от одного факта указания сноски “+” в текущем разделе. Чтобы вставить их независимо от этого, нужно выполнить макрокоманду BrowsButtons. Если макрокоманда выполнена, а текущий раздел не связан ссылкой “+” с другими разделами, кнопки появятся, но будут запрещены для выбора.
Вставка графики
Если вы создаете 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] проектного файла.
Графический образ может служить ссылкой на пояснение или перекрестной ссылкой. Чтобы придать ему такие свойства, необходимо набрать текст директивы вместе с обрамляющими фигурными скобками перечеркнутым или дважды подчеркнутым шрифтом, если графическая врезка используется в качестве перекрестной ссылки, или подчеркнутым одной линией, если она служит ссылкой на пояснение. Сразу за выделенной таким образом директивой нужно указать скрытым текстом идентификатор связанного раздела. Например:
Этот графический образ [bmc flower.bmp]Bitmap Cross вставлен непосредственно в текст и служит перекрестной ссылкой. {bml hardware.bmp}Bitmap Comment Если щелкнуть мышью по расположенной слева картинке, появится дополнительное окно с пояснениями. Такие окна удобно использовать для пояснения второстепенных деталей справки.
{bmr legal.bmp} Правая картинка не является перекрестной ссылкой. Она просто иллюстрирует одно из многочисленных изображений, поставляемых для текстового редактора MS Word.
На показан экран Help-службы с графическими вставками. Для его создания использовался приведенный выше фрагмент RTF-файла.
Выполнение макрокоманд
При открытии того или иного раздела можно выполнить одну или несколько макрокоманд. С помощью макрокоманд можно гибко воздействовать на состояние окна справочной службы: его положение, размеры, цвет, содержимое меню и инструментальных кнопок, отображать другие Help-файлы, выполнять внешние программы и т. д. (см. п. 21.7). Для указания макрокоманды, исполняющейся в момент открытия раздела, ее имя задается в тексте сноски “!”. Сноска указывается вместе с другими сносками в самом начале раздела (до первого символа текста). Например, для вставки в инструментальную панель кнопок просмотра связанных разделов сноска имеет такой вид:
!BrowseButtons ( )
Если нужно указать несколько макрокоманд, они отделяются в тексте сноски символами “;”.
Отображение текста раздела в дополнительном окне
Помимо основного окна в справочной службе можно определить множество дополнительных окон, каждое из которых в общем случае будет иметь свой цвет, заголовок, размеры и т. д. Дополнительные окна описываются в секции [windows] проектного файла (см. п. 21.4.). Чтобы указать, что раздел справки должен по умолчанию отображаться в дополнительном окне, используется ссылка “>” (с помощью модификации гиперссылки можно заменить умалчиваемый тип окна на другой, см. ниже). В тексте ссылки указывается тип окна так, как он определен в проектном файле, например:
> wind
В ссылке “>” может указываться только одно умалчиваемое окно. Другим способом указания дополнительного окна является модификация перекрестной ссылки (см. п. 21.3.1). Если, например, в
ссылке
ГИПЕРТЕКСТ НУРЕКТЕХТ
раздел hypertext должен отображаться в окне windi, ссылка оформляется следующим образом:
ГИПЕРТЕКСТ НУРЕКТЕХТ>WIND1
Окно, указанное в тексте ссылки, имеет приоритет перед умалчиваемым окном, если оно определено сноской">" для раздела. Для нашего примера это означает, что окно windi будет использоваться для отображения ссылки гипертекст даже в том случае, если раздел hypertext имеет сноску “>”, в которой указано другое окно.
РАЗРАБОТКА ПРОЕКТНОГО ФАЙЛА
Проектный файл служит основным управляющим документом для 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 приобретет вид, показанный на
Всю центральную часть окна занимает текст проектного файла, который первоначально состоит из единственной секции [options]. В отличие от обычных текстовых редакторов это окно недоступно для клавиатурного ввода: чтобы вставить в него текст или изменить уже введенные секции, используются расположенные справа кнопки.
Секция OPTIONS
Секция [Options] создается или изменяется с помощью кнопки options. Оно содержит общие для всей справочной службы установки и, в частности, определяет умалчиваемую тему, показываемую при открытии HELP-службы, заголовок основного окна, используемый в текстах язык и т. п.
После нажатия кнопки options появляется многостраничное окно, показанное на
Страница General
Default topic - идентификатор умалчиваемого раздела;
Help title - заголовок основного окна справочной службы; замечу, что мне не удалось получить заметных результатов, связанных с изменением этой строки, так что для изменения заголовка основного окна пришлось использовать дополнительное окно main (см. ниже п. 21.4.3); заголовок можно также изменить при создании файла содержания (см. п. 21.5);
Notes - если переключатель выбран, компилятор сообщает о возникающих проблемах, если не выбран - только общее количество предупреждений и ошибок;
Progress - если переключатель выбран, компилятор сообщает о транслируемом -RTF-файле;
Errors - открывает окно для указания кодов ошибок, о которых компилятор не будет сообщать;
Display this text... - определяет текст, который будет помещен
В окно Справка | Версия справочной службы;
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];
contents file - указывает имя файла содержания, если такой файл создан;
тмр 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
Определяет макрокоманды, автоматически выполняемые при выборе того или иного ключевого слова.
Keywords - содержит список ключевых слов, для которых определены макрокоманды;
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-файле будет заменен при отображении в окне справки и на какой шрифт он будет заменен.
Секция FILES
С помощью этой секции определяются RTF-файлы, содержащие текст, справочной системы. Для нормальной работы компилятора необходимо определить хотя бы один файл в этой секции. Замечу, что содержимое этой секции автоматически изменяется при изменении списка RTF-files на странице Files окна options (см. п. 21.4.1).
Справочная служба может состоять из множества RTF-файлов. В этом случае все они должны быть перечислены в секции [Files]. Компилятор разрешает задать в этом списке один или несколько ссылочных ASCII-текстовых файлов, каждая строка которых указывает нужный RTF-файл .(т. е. содержит маршрут доступа и имя файла).
Секция WINDOWS
Секция [windows] определяет используемый в справочной службе набор дополнительных окон. Каждое указанное в секции окно характеризуется своим типом, цветом, размерами, заголовком. Только имена перечисленных в секции окон могут указываться в ссылках и сносках “>” RTF-файлов.
В строке create a window named следует задать имя окна. Замечу, что, если указать имя main, установки, производимые далее, будут относиться к основному окну справочной службы (именно таким способом мне, например, удалось получить нужный заголовок основного окна). С помощью списка Based on this standard window можно выбрать один из трех возможных стандартных типов окна:
procedure - окно предназначено для вывода текстов процедур; оно позиционируется в правом верхнем углу экрана и при значительной ширине может своим правым краем выйти за пределы экрана;
Reference - обычное справочное окно; позиционируется в левом верхнем углу, занимает приблизительно 2/3 экрана по высоте и ширине;
Error message - окно предназначено для вывода сообщений об ошибках, позиционируется по центру экрана, занимает почти всю высоту экрана и 3/4 его ширины.
Замечу, что все три типа создают стандартные Windows-окна с “толстой” рамкой и заголовком, т. е. их положение и размеры пользователь может изменять по своему усмотрению, так что выбор типа не носит решающего характера. Кроме того, с помощью кнопки Auto sizer на странице position (см. ниже) можно визуально настроить положение и размеры окна.
Страница General
window type - позволяет выбрать одно из ранее определенных окон; все дальнейшие установки на странице General будут осуществляться для указанного в этой строке окна; подобные строки есть на всех других страницах окна window Properties;
Add - вызывает окно для добавления нового окна к списку окон;
Remove - удаляет окно из списка;
include - включает ASCII-текстовьгй файл со списком окон;
Title bar text - определяет заголовок окна;
comment - содержит произвольный комментарий; здесь, например, можно указать функциональность окна; текст комментария не включается в результирующий файл;
Auto-size height - если переключатель выбран, окно автоматически изменяет высоту в зависимости от разрешения экрана;
Maximize window - окно максимизируется по размеру экрана;
Keep Help window on top - окно всегда появляется поверх остальных окон.
Страница Position определяет положение и размеры окна в момент его появления на экране. тор - отступ левого верхнего угла от верхнего края экрана;
Left - отступ левого верхнего угла от левого края экрана;
Height - высота окна;
width - ширина окна;
Adjust for user screen resolution - если переключатель выбран, координаты задаются относительно виртуального экрана с разрешением 1024х1024; если не выбран, координаты указываются в пикселях;
Auto-sizer - после щелчка по этой кнопке появляется окно с кнопками ОК и Cancel для визуальной настройки его размеров и положения;
Default position - после щелчка по этой кнопке окну задаются умалчиваемые размеры.
Страница Buttons
Определяет состав включаемых в окно инструментальных кнопок. Если выбран указанный ниже переключатель, в окно вставляется соответствующая кнопка.
Contents - кнопка Содержание;
Index - кнопка Индекс;
Find - кнопка Поиск;
Help Topics - кнопка Разделы;
Print - кнопка Печать;
Back - кнопка Назад;
Options — кнопка Параметры;
Brows - кнопки просмотра связанных тем.
Страница Color
Позволяет изменять цвет фиксированной (Nonscrolling area) и основной (Topic area) зоны окна. Изменения становятся доступны после щелчка по соответствующей кнопке Add.
Страница Macros
С помощью этой страницы можно указать макрокоманды, которые будут автоматически выполняться при появлении окна на экране.
Секция BITMAPS
Эта секция определяет список папок, в которых компилятор будет искать графические файлы, встроенные в текст справки директивами bmc, bmi, bmr. Если ни одна папка не определена, компилятор сможет подключить только те файлы, которые располагаются в том же каталоге, где создается нlр-файл.
Секция MAP
В этой секции следует определить числовые идентификаторы разделов, которые будут автоматически вызываться кнопками Help и клавишей F1 в работающей программе. Напомню, что все видимые компоненты Delphi имеют специальное свойство HeipContext, в которое можно поместить числовой идентификатор раздела справочной службы. Если соответствующий компонент имеет фокус ввода и пользователь нажимает кнопку F1, автоматически включается справочная система Windows, которая отыскивает в ньр-файле и показывает в справочном окне соответствующий раздел. Только разделы, указанные в секции [map] , могут быть контекстно-доступными из работающей программы. Остальные разделы можно просмотреть после вызова справки с помощью выбора ключевых слов, кнопками просмотра связанных разделов или по содержанию справочной службы.
В списке 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, и вы сможете без труда вспомнить идентификаторы.
Секция ALIASES
В этой секции можно указать псевдонимы идентификаторов разделов, с помощью которых можно модифицировать секцию Map без изменения RTF-файлов. Назначение кнопок Add, Remove, include и Edit такое же, как и в секции мар. После назначения псевдонима он может использоваться в секции мар вместо идентификатора раздела. Эта возможность облегчает модификацию справочной службы.
Секция Config
Секция [Config] предназначена для указания макрокоманд, которые будут выполняться в момент открытия справочной службы. С ее помощью можно также зарегистрировать подпрограммы из библиотеки) DLL, которые после этого могут использоваться наравне с макрокомандами.
Секция BAGGAGE
Кнопкой Data Files окна MS HW открывается диалоговое окно определения файлов, которые будет использовать справочная служба. Список этих файлов содержит секция [Baggage] проектного файла. Помимо RTF-файлов, которые обычно вставляются в секции [Files], здесь можно также указать файлы библиотек DLL, подпрограммы которых после этого могут использоваться как макрокоманды.
ФАЙЛ СОДЕРЖАНИЯ СПРАВОЧНОЙ СЛУЖБЫ
Содержание справочной службы оформляется в файле с расширением сыт и становится доступным после нажатия кнопки содержание в справочном окне. Для создания/редактирования содержания используется утилита MS HW.
В строках Default filename (and window) И Default title В верхней части окна нужно указать соответственно имя ньр-файла, для которого создается содержание, и тип окна для отображения оглавлений, а также заголовок основного окна справочной службы. Замечу, что заголовок Default title, если он задан, переопределяет заголовок, указанный в секции [Options] файла проекта.
Эти параметры можно установить вручную, но удобнее для ввода использовать вспомогательное диалоговое окно, которое раскрывается кнопкой Edit справа от строки Default title. При ручном вводе в строке Default filename (and window) имя файла отделяется от имени окна символом “>”.
Например:
HelpTest.hlp>WIND
Элементы содержания могут быть темами и разделами. Темы служат узлами в иерархической структуре содержания. В окне справочной службы слева от названия темы указывается пиктограмма в виде раскрытой или захлопнутой книги. Раздел - конечный элемент содержания. Слева от него указывается пиктограмма.
Для вставки в файл элемента содержания нужно щелкнуть по кнопке Add Above или Add Below. В первом случае элемент вставляется перед текущим элементом, во втором - после него.
Переключатели в верхней части окна определяют тип вставляемого элемента:
Heading - вставляется тема; при выборе этого переключателя все расположенные ниже строки, кроме Title, становятся недоступными;
Topic - вставляется раздел;
Macro - вставляется макрокоманда; эта макрокоманда будет выполняться при выборе элемента в окне содержания;
include - вставляется ASCII-текстовый файл с элементами содержания.
Четыре строки ниже переключателей используются только при вставке раздела. При вставке темы или включаемого файла доступна только первая строка, при вставке макрокоманды - первая и вторая, которая в этом случае снабжается надписью Macro.
В строке Title вводится произвольный текст длиной до 127 символов, который будет представлять элемент в окне содержания. В этой строке также указывается имя включаемого файла, если выбран переключатель Include. Во второй строке указывается идентификатор раздела или имя макрокоманды. В строке Help file нужно указать ньр-файл, если справочная система использует несколько файлов, а в строке window type - тип окна для отображения раздела.
Для смещения элемента оглавления на один уровень иерархии вниз используется клавиша Move Right, а на один уровень вверх -Move Left. Элемент сдвигается вместе со всеми другими элементами, расположенными ниже него. Максимальное количество уровней иерархии - 9.
Следует заметить, что файл содержания представляет собой AS-СН-текстовый файл, каждая строка которого соответствует элементу содержания. В начале строки указывается цифра, определяющая уровень иерархии, на котором располагается элемент. На для примера показано содержание справочной службы What's New in Delphi и соответствующий ей сnт-файл.
После создания файла содержания его нужно сохранить в том же каталоге, что и нlр-файл, - после этого содержание станет доступно в момент запуска нlр-файла или с помощью кнопки содержание окна справочной службы.
КОМПИЛЯЦИЯ, ТЕСТИРОВАНИЕ И СВЯЗЬ С ПРОГРАММОЙ
Компиляция и тестирование справочной службы не составляют проблемы: с помощью MS HW создайте (или загрузите) проектный файл и щелкните по кнопке save and compile или по инструментальной кнопке . После этого появляется окно, показанное на
При компиляции MS HW сворачивает свое окно и вновь раскрывает его после завершения работы компилятора, если отмечен переключатель Minimize window while compiling. После окончания компиляции в нем будут показаны сообщения компилятора. Если компилятор обнаружил ошибки, он сообщает о них, причем некритические ошибки сопровождаются предупреждениями (warnings) и замечаниями (notes), а критические - прерывают компиляцию.
Для тестирования скомпилированного справочного файла используется одна из опций меню Test:
contents File - тестирует файл содержания;
close All Help - закрывает все ранее открытые нlр-файлы;
send a macro - посылает в winHelp нужную макрокоманду;
WinHelp api - вызывает нужный раздел справочной службы по присвоенному ему в секции map числовому идентификатору.
Тестирование файла содержания заключается в автоматическом вызове всех указанных в содержании разделов. Если какой-либо раздел не вызывается, выдается сообщение (позволяющее найти и устранить ошибку.
Связь с программой реализуется с помощью свойств HelpContext видимых компонентов, в которые следует поместить числовые идентификаторы нужных разделов справочной службы так, как они определены. В секции MAP. Кроме того, в свойство Application. HelpFile нужно поместить имя нlр-файла. Обычно эта связь устанавливается в обработчике события ОnCreat главной формы программы. После такой настройки пользователь программы сможет с помощью клавиши F1 получить контекстно-чувствительную справку, т. к. при нажатии F1 автоматически вызывается раздел, числовой идентификатор которого помещен в свойство HeipContext компонента с фокусом ввода. Если Heipcontext компонента с фокусом ввода содержит 0, вызывается раздел, указанный в HelpContext его владельца, а если и у того это свойство не определено, используется HelpContext активной формы (если во всей цепочке владельцев, включая активную форму, свойство HelpContext не определено, нажатие F1 игнорируется).
МАКРОКОМАНДЫ WINHELP
Справочная служба Windows 32 - WinHelp имеет встроенные макрокоманды, которые доступны из справочной службы программы. Макрокоманды могут выполняться в следующих случаях:

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

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

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

 Работа с меню

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


 
IFThen(macro,macrol)

Если макрокоманда выполняет macrol иначе ничего не делает

IFThenElse(macro,macrol,macro2)

Если макрокоманда macro возвращает 1, выполняет macrol иначе выполняет macro2

Not(macro) macro возвращает 1,

Инвертирует результат, возвращаемый macro

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


0

Выводится окно с названиями наиденных разделов

1

Если найден только один раздел, он показывается в справочном окне

2

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

4

Если найден хотя бы один раздел, макрокоманда возвращает 1

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

 

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