Создаем полноценный Help для Delphi-программ. Часть 3: Создание окон справочной системы.

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

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

Главное окно справочной системы как минимум должно содержать панель навигации, список разделов, поиск по контексту и предметный указатель.
На данный момент (если Вы читали первую и вторую часть) у нас имеется проект содержащий два топика справки. Давайте настроим наше главное окно справки и добавим в него список разделов. Для этого необходимо перейти в HHW на вкладку Contents:

Здесь и создается список таким, каким мы его хотели бы видеть. Вначале добавляем новый раздел. Для этого жмем кнопку «Insert heading» откроется окно настройки нового раздела:

Задаем название раздела, а также, если необходимо — страницу, которая будет открываться при выборе раздела. Также на вкладке «Advanced» можно настроить вид иконки, указать окно в котором будет открываться раздел, оставить комментарий и т.д.
Теперь добавим новый топик в созданный раздел. Для этого жмем кнопку «Insert a page». Откроется точно такое же окно, как и при создании раздела — заполняем необходимые поля, указываем страницу топика и эжмем «Ok».
Теперь можете скомпилировать проект и убедиться, что теперь наша справка имеет удобное содержание:

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

Примерно также создается и предметный указатель. А мы тем временем перейдем непосредственно к основной теме поста — созданию новых окон.
Переходим в HHW на вкладку «Project», жмем кнопку «Add/Modify window definitions» и начинаем создание новго окна:

Окно содержит несколько вкладок, каждая из которых отвечает за определенные элементы нового окна:
General — основные свойства окно, такие как тип окна: произвольная строка, задаваемая пользователем. Используется при вызове окна. Заголовок окна (Title Bar Text).
Buttons — на этой вкладке можно выбрать те кнопки, которые будут отображаться в навигационной панели окна.
Position — здесь мы можем задать положение окна (свойства Left и Top), а также размеры окна (свойства Height и Width)
Navigation Pane — если мы хотим, чтобы новое окно содержало навигационной панель и содержание, то на этой вкладке необходимо включить опцию (единственную на вкладке)
Styles — свойства окна, такие как показ окна в развернутом виде, перекрытие дочерних окон нашим окном и т.д.
Extended Styles — расширенные стили окна. Здесь можно указать такие дополнительные свойства как, например, выравнивание текста заголовка по правому краю, показ окна поверх других окон и т.д.
Files — на этой вкладке мы должны указать файлы, используемые для отображения навигации в окне, индексный файл, файл открываемый по умолчанию и т.д. Большинство свойств на этой вкладке заполняются автоматически из свойств Вашего проекта.
Итак, после недолгих манипуляций со свойствами нового окна у меня получилось вот такое новое окно с названием «Context» и заголовком «Title New Window»:

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

HtmlHelp(Handle,PChar(ExtractFilePath(Application.ExeName)+'help.chm::context.htm'),HH_DISPLAY_TOPIC,0)

Вызов этого же самого топика в окне «Context» ничем не сложнее, просто необходимо указать тип окна в параметне pszFile вот так:

HtmlHelp(Handle,PChar(ExtractFilePath(Application.ExeName)+'help.chm::context.htm>Context'),HH_DISPLAY_TOPIC,0)

То есть сразу после названия файла топика необходимо указать >Тип_Окна. Элементарно.
Теперь перейдем к следующему моменту — использование popup-окон справочной службы.
Здесь у нас есть два варианта как вызывать popup-окна из своей программы.

Вариант №1. Использование ActiveX контрола.

Для этого нам необходимо импортировать в проект библиотеку HHCtrl:

ActiveX Control — HHCtrl

После импорта hhctrl необходимо подключить в uses модуль HHCTRLLib_TLB. Теперь создаем в нашем тестовом проекте (см. содержимое проекта здесь) ещё одну кнопку с Capition «PopUp-window» и на onClick пишем:

procedure TForm5.Button3Click(Sender: TObject);
var HH: THHCtrl;
begin
  HH:=THHCtrl.Create(self);
  HH.TextPopup('Popup Подсказка','MS Sans Serif, 10, , BOLD',5,5,clBlack,clYellow);
end;

Запускаем приложение и по клику на кнопке получаем следующий popup:

Теперь раздеремся, какие параметры мы указали при вызове метода TextPopup:

procedure TextPopup(const pszText: WideString; const pszFont: WideString; horzMargins: SYSINT; vertMargins: SYSINT; clrForeground: LongWord; clrBackground: LongWord); safecall;

pszText: WideString — текст подсказки
pszFont: WideString — шрифт, используемый в подсказке. Шрифт необходимо определять, используя следующий шаблон:

facename[, point size[, charset[ BOLD ITALIC UNDERLINE]]]

horzMargins: SYSINT; vertMargins: SYSINT; — горизонтальный и вертикальный отступы надписи в popup-окне
clrForeground: LongWord; clrBackground: LongWord — цвет надписи и цвет заднего фона popup-окна.

Вариант №2. Использование команды HH_DISPLAY_TEXT_POPUP.

Этот вариант вызова popup-окна не требует от нас использования лишних модулей, т.к. использует функцию HtmlHelp.
Вызов popup-окна с помощью команды HH_DISPLAY_TEXT_POPUP имеет следующий формат:

HtmlHelp(hwndCTRL, NULL, HH_DISPLAY_TEXT_POPUP,        (DWORD)&popup);

В параметре dwData мы должны передать указатель на структуру HH_POPUP, которая содержит следующие поля:

type
 tagHH_POPUP = packed record
    cbStruct: integer;
    hinst:HINST;
    idString:UINT;
    pszText:LPCTStr;
    pt:TPoint;
    clrForeground:COLORREF;
    clrBackground:COLORREF;
    rcMargins:TRect;
    pszFont:LPCTStr;
end;

cbStruct: integer — размер структуры. Этот параметр должен быть определен перед использованием структуры в HtmlHelp.
hinst:HINST — хэндл окна вызывающей программы или DLL;
idString:UINT — 0, ID ресурса или номер топика в справке.
pszText:LPCTStr — текст подсказки
pt:TPoint — определяет абсолютные координаты положения popup-окна
clrForeground:COLORREF, clrBackground:COLORREF — цвет текста и фона окна.
rcMargins:TRect — отступы в пикселях.
pszFont:LPCTStr — строка, определяющая текст подсказки.
Остается только заполнить поля структуры необходимыми данными и использовать её в вызове HtmlHelp, например так:

var HH: tagHH_POPUP;
begin
  //заполняем поля
  HtmlHelpA(Handle,nil,HH_DISPLAY_TEXT_POPUP,DWORD(@HH))
end;

Какой способ более приемлим для Вас — решать вам, но на мой взгляд первый способ с использованием ActiveX контроля немного проще. Хотя бы даже потому, что popup-окно появляется точно под курсором мыши, что избавляет нас от лишней необходимости расчитывать координаты положения всплывающего окна.