Создание
справочной
системы
В этой главе мы рассмотрим
принципы, по которым подключается файл справки к вашему приложению.
CLX не обеспечивает прямую
поддержку отображения файла справки. Он обеспечивает механизм, с помощью которого
запросы об отображении справки вызывают внешние программы, отображающие справочные
файлы (такие, как Man, Info или HyperHelp). Кроме того, для работы этого механизма
на разработчика возлагается задача по созданию класса, который поддерживает
интерфейс ICustomHelpViewer
(и, по желанию, один из интерфейсов-потомков
ICustomHelpViewer
). После чего необходимо зарегистрировать экземпляр
данного класса с помощью глобального менеджера помощи (global Help Manager).
Менеджер помощи содержит
список всех зарегистрированных в системе программ для отображения файлов помощи
и передает ему запросы вашего приложения. Запросы передаются в две фазы:
Примечание
Если более чем
одна программа поддерживает данный формат ключевых слов или содержания,
то менеджер помощи отобразит окно, с помощью которого пользователь сам сможет
выбрать приложение для просмотра файла справки. В противном случае, файл
справки отобразится в первой из программ, поддерживающих данный формат ключевых
слов.
Итак, CLX обеспечивает
связь между вашим приложением и программой для просмотра файлов справки с помощью
интерфейсов. Эти интерфейсы описаны в файле HelpIntfs.pas, который также содержит
код, реализующий менеджер помощи (см. Приложение 1):
ICustomHelpViewer
обеспечивает поддержку отображения помощи по заданному ключевому слову,
а также отображения оглавления файла справки;IExtendedHelpViewer
обеспечивает поддержку отображения помощи по номеру контекста справки, а также
отображения тем. В большинстве справочных систем функция темы в обеспечении
ключевых слов высшего уровня (например, в справочной системе Kylix слово IntToStr
является ключевым словом, но строка String manipulation routines
является названием
темы);ISpecialWinHelpViewer
обеспечивает поддержку ответа на специализированные сообщения WinHelp
в случае, если приложение запущено под Windows. В поддержке данного интерфейса
нуждаются только те приложения, которые работают в среде Windows. Более того,
это необходимо, когда приложение использует нестандартные сообщения WinHelp;IHelpManager
обеспечивает
механизм для обратной связи программы просмотра файлов помощи с менеджером
помощи вашего приложения. Этот механизм необходим, если программа просмотра
помощи нуждается в дополнительной информации;IHelpSystem
обеспечивает механизм, с помощью которого TApplication
отсылает
запросы в систему помощи. TApplication
получает экземпляр объекта,
который поддерживает два интерфейса IHelpSystem
и IHelpManager
;IHelpSelector
обеспечивает механизм, с помощью которого система помощи может использовать
пользовательский интерфейс для того, чтобы узнать у пользователя, какую программу
необходимо применить для просмотра файлов справки, если более чем один просмотрщик
файлов справки может отображать данный файл. Интерфейс ICustomHelpViewer
содержит три типа методов:
Интерфейс ICustomHelpViewer
обеспечивает три функции, которые используются для связи менеджера помощи и
системной информации:
ICustomHelpViewer.
GetViewerName: String;
— Вызывается, когда менеджер помощи должен узнать
имя программы для показа файлов справки (например, когда приложение запрашивает
список всех зарегистрированных в системе программ просмотра файлов помощи).
Данная функция возвращает информацию в строковой форме (String
);ICustomHelpViewer.NotifyID(const
ViewerID: Integer);
— вызывается немедленно
после регистрации программы для просмотра файлов помощи, чтобы присвоить ей
уникальный идентификационный номер;ICustomHelpViewer.ShutDown;
- вызывается из менеджера помощи для уведомления программы — просмотрщика
помощи в том, что менеджер отключается и ресурсы, занятые просмотрщиком помощи,
должны быть освобождены. Интерфейс IHelpManager
позволяет просмотрщику помощи передавать четыре запроса:
Рассмотрим методы, позволяющие
выполнить все вышеописанное:
IHelpManager.GetHandle
: LongInt
; — вызывается просмотрщиком файлов помощи, если он нуждается
в дескрипторе текущего оконного компонента;IHelpManager.GetHelpFile:
String
; — вызывается просмотрщиком помощи, если ему необходимо узнать
имя файла помощи, который назначен активному оконному компоненту;IHelpManager.GetHelpPath:
String
; — вызывается просмотрщиком помощи, если ему нужно узнать путь
к файлу справки. Данная информация не предоставляется по умолчанию, т. к.
многие из внешних систем помощи способны самостоятельно определить путь с
помощью переменных среды или другими способами;IHelpManager.Release
;
— вызывается для уведомления менеджера помощи об отключении просмотрщика помощи.
Данный метод никогда не должен вызываться в ответ на запрос, приходящий из
ICustomHelpViewer.ShutDown
. Метод используется только для уведомления
менеджера помощи о неожиданном разрыве соединения. Запросы на отображение
разделов справки обычно идут по ключевому слову, в этом случае просмотрщик помощи
обеспечивает помощь, основанную на строке текста. Второй вариант основан на
контексте справки, в этом случае просмотрщик обеспечивает помощь, основанную
на числовом иденти-фикат.оре. Последний вариант является обычным вариантом предоставления
справки в приложениях, работающих в среде Windows и использующих систему WinHelp.
Несмотря на то, что CLX поддерживает данный вариант, он не рекомендуется, т.
к. большинство справочных систем Linux не поддерживают его.
Интерфейс ICustomHelpViewer
необходим для обеспечения поддержки помощи по ключевому слову. Интерфейс
IExtendedHelpViewer
необходим для поддержки контекстно-зависимой помощи.
Интерфейс ICustomHelpViewer
предоставляет три метода для работы со справкой по ключевому слову:
ICustomHelpViewer.CanShowKeyword(const
HelpString: String): Integer;
— метод, который вызывается менеджером
помощи. Данный метод опрашивает каждый из зарегистрированных в системе просмoтрщиков
помощи на возможность отображения справки по ключевому слову. Ожидается, что
просмотрщик даст ответ в виде целого числа, которое указывает, сколько различных
страниц справки может отобразить данный просмотрщик в ответ на запрос менеджера
помощи. Просмотрщик может использовать любые методы для определения этого
числа. Если просмотрщик не поддерживает помощь по данному ключевому слову,
он возвращает нулевое значение. Отрицательные значения, возвращаемые просмотрщиками,
в настоящее время расцениваются как нулевые, но в будущем могут использоваться
для каких-либо других целей; ICustomHelpViewer.GetHelpStrings(const
HelpString: String):
TStringList
;
— вызывается менеджером помощи если более одного про-смотрщика способны отобразить
помощь для данного ключевого слова. При вызове данного метода ожидается, что
просмотрщик возвратит значение типа TStringList
. Строки возвращаемого
списка должны указывать на страницы, которые содержат данное ключевое слово,
но характеристики данного списка могут отличаться у разных просмотрщиков.
В случае, когда ответ приходит от просмотрщика HyperHelp, список строк всегда
содержит всего одну ссылку на каждую из страниц, в которой есть ключевое слово;ICustomHelpViewer.ShowHelp(const
HelpString: String)
; —вызывается
менеджером помощи, если необходим просмотрщик помощи для отображения справки
по ключевому слову. Интерфейс ICustomHelpViewer
обеспечивает два метода, связанных с отображением содержания файла справки:
CanShowTableOfContents
;
ShoWTableOfContents
. Теоретически их работа
схожа с работой методов просмотра помощи по ключевому слову: менеджер помощи
сначала запрашивает все просмотрщики с помощью метода ICustomHelpViewer.CanShowTableOfContents:
Boolean;
, затем вызывает конкретную программу-просмотрщик с помощью вызова
метода ICustomHelpViewer.ShowTableOfContents
.
Для того чтобы менеджер
помощи мог работать с интерфейсами ICustomHelpViewer,
IExtendedHelpViewer
,
ISpecialWinHelpViewer
и IhelpSelector
,
необходимо осуществить регистрацию объекта справочной системы.
Модуль, который содержит
описание данного объекта, должен иметь в списке используемых модулей модули
HelpIntfs
и QForms
. Экземпляр объекта должен быть
объявлен в секции var
раздела реализации (implementing
)
модуля.
Вместе со средой Kylix
поставляются файлы, помогающие создавать систему помощи для ваших приложений.
Эти файлы находятся в каталоге
/kylix/demos/helpviewers/.
Здесь располагаются три
основных файла:
Прежде чем рассмотреть
эти три файла, отметим, что справочная система CLX имеет подключаемую архитектуру,
которая работает через интерфейс IHelpSystem
.
Модуль WinHelpViewer
обеспечивает связь между приложением и HyperHelp (эмулятором WinHelp
под Linux).
Модуль ManViewer
обеспечивает связь между приложением и системой Linux man.
Пакет HelpViewers представляет
собой пример пакета, который содержит модуль ManViewer
. Этот пакет
зарегистрирован как пакет времени разработки в IDE и обеспечивает связь IDE
со страницами man
. Данный пакет не может быть использован во время
работы приложения. Листинги всех трех файлов приводятся в конце книги, в
Приложении 2.