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

В этой главе мы рассмотрим принципы, по которым подключается файл справки к вашему приложению.

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/.

Здесь располагаются три основных файла:

• HelpViewers.dpk
  
• ManViewer.pas
  
• WinHelpViewer.pas
  

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

Модуль WinHelpViewer обеспечивает связь между приложением и HyperHelp (эмулятором WinHelp под Linux).

Модуль ManViewer обеспечивает связь между приложением и системой Linux man.

Пакет HelpViewers представляет собой пример пакета, который содержит модуль ManViewer. Этот пакет зарегистрирован как пакет времени разработки в IDE и обеспечивает связь IDE со страницами man. Данный пакет не может быть использован во время работы приложения. Листинги всех трех файлов приводятся в конце книги, в Приложении 2.