Создание help-файла (справки) в формате CHM для Delphi-приложения для Windows в Dr.Explain

Журавлев Денис

Установка

Скачайте дистрибутив программы Dr.Explain в разделе «Загрузить» официального сайта продукта по адресу http://www.drexplain.ru/ и пройдите стандартную процедуру установки программного обеспечения для начала его использования.

Доступно использование бесплатной незарегистрированной версии программного обеспечения без ограничения по времени. Функционал для бесплатной и лицензионной версий Dr.Explain совпадает, однако все изображения в итоговом сформированном в бесплатной версии файле справки будут помечены специальным водяным знаком.

Рис. 1. Мастер установки Dr.Explain

Создание и настройка нового проекта

Для создания нового проекта файла справки с возможностью последующего экспорта в файл формата CHM в Dr.Explain выберите пункт «Создать новый проект» в стартовом окне программы, либо перейдите в пункт «Файл -> Создать» главного меню программы.

Рис. 2. Стартовое окно программы Dr.Explain

Перейдите в пункт меню «Настройки -> Настройки проекта» и в открывшемся диалоговом окне перейдите в раздел «CHM экспорт -> Управление Help ID». Для осуществления последующей привязки проекта Delphi к темам файла справки установите флаг «Экспорт Help ID в CHM». Нажмите кнопку «OK» для применения настроек к проекту.

Рис. 3. Окно «Настройки проекта»

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

Создание тематических разделов в файле справки

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

Создайте темы файла справки, перейдя в пункт меню «Настройки -> Добавить тему», или нажмите правой кнопкой мыши на дерево проекта в левой части экрана, после чего в открывшемся меню выберите пункт «Добавить -> Добавить тему». Для полного описания Delphi-приложения создайте темы для каждого его объекта. В таком случае в приложении по нажатию клавиши F1 будет открываться информация об объекте, на котором находится фокус.

Рис. 4. Дерево проекта Dr.Explain

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

Перейдите в нужную тему в дереве проекта и в окне редактора введите содержимое раздела в свободной форме. В окне редактора имеется стандартный функционал для форматирования текста.

Во вкладке «Ключевые слова» укажите набор ключевых слов для поиска по файлу справки. Для того, чтобы ассоциировать ключевое слово с определенной темой, выберите тему в дереве проекта и установите флаг напротив выбранного ключевого слова.

Рис. 5. Ключевые слова

Для создания описания конкретного объекта Delphi-приложения (в том числе и формы в приложении) также можно воспользоваться кнопкой «Схватить экран».

Рис. 6. Окно «Захват проекта»

В открывшемся диалоговом окне нажмите на пиктограмму «Accessible-объект» или «Win32-окно», после чего перейдите в окно приложения Delphi и выберите описываемый в разделе объект одним из указанных способов:

Нажмите на клавишу PrtScr;
Нажмите на объект, удерживая нажатой клавишу Ctrl;
Поочередно кликните двумя кнопками мыши по объекту.

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

Рис. 7. Результат выполнения захвата объекта

Настройка значений Help ID

В Dr.Explain существует возможность редактирования значения Help ID. Для изменения значения идентификатора выберите желаемую тему и нажмите на ячейку «Help ID» в окне свойств страницы. Введите свое значение и уберите фокус мыши с поля для применения значения.

Рис. 8. Изменение значения Help ID в окне «Свойства страницы»

Перейдите в пункт меню «Инструменты –> проверка проекта на ошибки» для проверки уникальности измененного Help ID. В случае совпадения этого значения у нескольких тем будет выдано сообщение о дублированных значениях. Для корректного создания и привязки к проекту Delphi файла справки CHM устраните дублирование, изменив одно или несколько значений Help ID, не выходя из окна «Проверка проекта» нажатием на ячейку в поле Значение.

Рис. 9. Окно «Проверка проекта». Дублированные значения Help ID

Экспорт проекта в CHM-файл

По окончании редактирования сохраните проект и перейдите в пункт меню «Настройки -> Экспорт в CHM». Установите флаг «Запустить проверку проекта перед экспортом» для предварительной проверки проекта на корректность. Установите флаг «Открыть CHM файл» для открытия файла CHM после его создания и установите флаг «Перезаписать молча» для перезаписи существующего проекта без открытия диалогового окна «Сохранение CHM-документа». Нажмите кнопку «Начать экспорт». Лог экспорта будет отображаться в окне «Экспорт в CHM». По окончании экспорта нажмите кнопку «Закрыть».

Рис. 10. Окно «Экспорт в CHM»

Установка пути к CHM-файлу в проекте Delphi

Для загрузки файла справки CHM в проекте Delphi требуется указать путь к этому файлу. Для этого выполните одну из следующих операций (доступно для версий выше Delphi 7):

· Перейдите в пункт меню среды Delphi «Project -> Options» и во вкладке «Application» укажите путь к файлу в поле «Help file».

Примечание: В случае указания полного пути к файлу приложение Delphi, запускаемое на произвольной машине, будет искать файл справки именно в указанной директории, которая может отсутствовать на машине с установленным приложением. Поэтому оптимальное решение – указывать относительный путь к файлу справки.

Рис. 11. Установка относительного пути к файлу справки CHM с помощью GUI Delphi

· Перейдите в пункт меню среды Delphi «Project -> View Source» и в открывшемся окне введите код

Application.HelpFile:=ExtractFilePath(Application.ExeName) + 'Helpdrexplain.chm’,

где 'Helpdrexplain.chm’ - относительный путь к файлу справки CHM.

Рис. 12. Программная установка относительного пути к файлу справки CHM

Привязка темы файла справки CHM к форме приложения Delphi

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

· В коде проекта введите строку

HelpFile:=ExtractFilePath(Application.ExeName) + 'Helpdrexplain.chm'

Рис. 13. Программная установка относительного пути к файлу справки CHM для объекта TForm

· В инспекторе объектов для формы укажите соответствующее значение в поле «HelpFile»

Рис. 14. Установка относительного пути к файлу справки CHM для объекта TForm в окне «Инспектор объекта»

Привязка темы файла справки CHM к объектам приложения Delphi

Формат файла CHM и приложения Delphi позволяют назначить каждому объекту проекта свою тему файла справки, которая будет открываться при нажатии клавиши F1 в случае наличия фокуса на данном объекте. Для этого в Инспекторе объекта в поле «HelpContext» укажите HelpID из созданного файла CHM. В случае, если в файле справки отсутствует тема с HelpID, равным указанному значению «HelpContext», в файле справки будет открыта тема, ассоциированная с родительской формой.

Дополнительные способы вызова CHM-файла из приложения Delphi

Существует несколько альтернативных вариантов вызова справки из приложения Delphi:

· Выполните команду ShellExecute(Application.Handle, 'open', ’Help/drexplain.chm', nil, nil, 0); по нажатию кнопки или другому действию на форме. Предварительно пропишите в блоке Uses расширение ShellAPI. Данное действие откроет главную страницу файла справки. При таком способе вызова файла справки не обязательно осуществлять предварительную ассоциацию файла справки с приложением.

Рис. 15. Вызов файла справки с использованием команды ShellExecute

· Выполните команду Application.HelpCommand(HELP_FINDER,0); по нажатию кнопки или другому действию на форме.

Рис. 16. Вызов файла справки с использованием команды Application.HelpCommand

Особенности интеграции файла справки в приложениях Delphi 7

Для использования файла справки CHM в проектах Delphi версии 7 или ниже необходимо воспользоваться расширениями сторонних разработчиков.

Скачайте и разместите в директории вашего проекта файл *.pas одного из выбранных расширений:

· HtmlHelpViewerEx (http://dl.dropbox.com/u/201788/Projects/HTMLHelpViewerEx.zip);

· HtmlHelpViewer (https://github.com/darrincedwards/SESComponentsNW/blob/master/HTMLHelpViewer.pas);

· StoHtmlHelp (https://github.com/serbod/serial-print/blob/master/StoHtmlHelp.pas);

Укажите название подключаемого расширения в любом разделе Uses проекта Delphi.

Рис. 17. Подключение стороннего расширения к проекту Delphi 7

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