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

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

Введение

Статья посвящена созданию файла справки в программе Dr.Explain и его интеграции в приложение Visual Basic.
Основные рассматриваемые вопросы:

создание и первичная настройка проекта в Dr.Explain;
создание структуры разделов в файле справки;
добавление аннотированных изображений интерфейса приложения на языке программирования Visual Basic;
настройка значений Help ID для реализации контекстной справки;
сохранение проекта;
экспорт проекта в формат СHM файла;
интеграция файла справки в приложение Visual Basic на уровне кода.

Установка Dr.Explain

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

Функционал пробной и полной версий идентичен. Единственное ограничение – при использовании пробной версии все изображения в экспортированных файлах помечаются водяными знаками.

Инсталлятор Dr.Explain

Рисунок 1. Инсталлятор «Dr.Explain»

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

Выберите пункт «Создать новый проект» в окне «Проекты Dr.Explain» (Рисунок 2) и нажмите «ОК», либо воспользуйтесь пунктом «Создать» в меню «Файл».

Проекты Dr.Explain

Рисунок 2. Проекты Dr.Explain

Настройте параметры экспорта в формат CHM. Используйте для этого пункт «Настройки -> Настройки проекта» в главном меню. Далее в открывшемся окне перейдите в раздел «CHM экспорт».

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

Создание отдельных тематических разделов для описания различных элементов приложения Visual Basic позволит получить удобную структуру файла справки.

Для создания новой темы используйте пункт «Настройки -> Добавить тему» главного меню. Либо вызовите контекстное меню нажатием правой кнопки мыши по любой из позиций дерева проекта (Рисунок 3) и выберите пункт «Добавить -> Добавить тему». Создайте тематические разделы для всех форм и элементов приложения.

Рисунок 3. Дерево проекта «Dr.Explain»

С помощью пунктов «Переименовать», «Выше» и «Ниже» контекстного меню вы можете переименовать темы и изменить порядок их следования в структуре документа. Для заполнения разделов выберите интересующий пункт в дереве проекта – его содержимое отобразится в окне редактора. Заполните раздел необходимой текстовой и графической информацией. Редактор содержит стандартный набор основных функций работы с текстом.

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

Создание ключевых слов повысит удобство поиска по файлу справки. Для добавления и удаления слов служат соответствующие кнопки в панели «Ключевые слова» (Рисунок 4), которая вызывается нажатием одноименной кнопки. Чтобы изменить привязку тем к словам, выберите интересующий раздел в дереве проекта и установите метки напротив слов, с которыми необходимо его ассоциировать.

Рисунок 4. Ключевые слова

Функция «Захват объекта» (Рисунок 5), которая вызывается кнопкой «Схватить экран», позволяет создать наглядное описание форм интерфейса и отдельных элементов приложения Visual Basic.

Рисунок 5. Окно «Захват объекта»

Выберите поле «Accessible-объект» или «Win32-окно» в окне захвата, после чего перейдите к приложению Visual Basic и захватите изображение интересующей формы одним из способов, предложенных в окне захвата. Тема, содержащая аннотированное изображение интерфейса, будет автоматически создана и добавлена в структуру документа (Рисунок 6). В окне редактора можно добавить и удалить аннотацию или изменить порядок следования описания отдельных элементов.

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

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

Для последующей привязки тем файла справки к элементам приложения в программе Dr.Explain предусмотрена возможность редактирования значений HelpID. Выберите в дереве проекта интересующую тему и нажмите на ячейку «HelpID» в окне свойств страницы (Рисунок 7). Введите требуемое значение и уберите фокус мыши с поля, чтобы сохранить настройки.

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

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

Предварительный просмотр и сохранение проекта

После завершения работы над проектом воспользуйтесь функцией предварительного просмотра — кнопка «Просмотр CHM». Убедитесь в корректном отображении созданного документа и всех его разделов. Для внесения необходимых изменений вернитесь в режим редактирования.

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

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

Для создания файла в формате CHM необходимо экспортировать проект, для этого используйте пункт «Настройки -> Экспорт в CHM» главного меню. Установите метку «Запустить проверку проекта перед экспортом» дляанализа корректности проекта до начала экспорта. Для открытия файла по окончании экспорта, установите флаг «Открыть CHM файл». Чтобы перезаписать ранее сохраненный файл без запроса подтверждения, отметьте поле «Перезаписать молча». Нажмите кнопку «Начать экспорт», после чегов окне «Экспорт в CHM» (Рисунок 8) будет отображаться отчет о ходе процесса. Закройте окно после окончания экспорта.

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

Интеграция CHM-файла в приложение Visual Basic

Для вызова справки в приложении Visual Basic необходимо создать соответствующий элемент управления, например, кнопку.

Для создания элемента управления выполните следующие действия:

откройте ваш проект с помощью средств среды разработки, которую вы используете;
перейдите в редактор форм (Рисунок 9);
в панели элементов выберите «Button»;
разместите кнопку в форме;
в области свойств измените название элемента и его подпись. Название вводится в поле «(Name)», а подпись в поле «Text» - введите интересующие значения, например, «HlpButton» и «Help» соответственно;
перейдите в редактор кода элемента (Рисунок 10).

Рисунок 9. Редактор форм среды разработки Microsoft Visual Studio

Рисунок 10. Редактор кода среды разработки Microsoft Visual Studio

В строке «Private Sub HlpButton_Click(ByVal sender AsSystem.Object, ByVal e As System.EventArgs) Handles HlpButton.Click» отображается имя вашего элемента (в данном случае «HlpButton»). Введите ниже строку – «CallShell("explorer.exe" & My.Application.Info.DirectoryPath + "\help.chm", vbNormalFocus)», где help.chm –имя файла справки в формате CHM. После чего весь код элемента управления должен иметь вид:

Private Sub HlpButton_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles HlpButton.Click Call Shell("explorer.exe" & My.Application.Info.DirectoryPath + "\help.chm", vbNormalFocus) End Sub

проверьте корректную работу элемента управления. Для этого выберите пункт «Debug -> Start debugging» главного меню, после чего на экране появится стартовая форма приложения. При нажатии кнопки «Help» должен открыться файл справки, созданный ранее в программе Dr.Explain;
повторите описанную процедуру для всех форм, в которые необходимо вставить элемент вызова справки.

ОБРАТИТЕ ВНИМАНИЕ! Для корректной работы элемента вызова файла справки необходимо, чтобы файл в формате CHM и файл приложения Visual Basic находились в одной директории. Если есть необходимость разместить файл справки отдельно от файла приложения, используйте следующую строку кода элемента управления «Shell("cmd /cstart D:\work\techwrite\help.chm")», где D:\work\techwrite\help.chm–полный путь до файла справки в формате CHM. Код в целом будет иметь вид:

Private Sub HlpButton_Click(ByVal sender As System.Object, ByVal e AsSystem.EventArgs) Handles HlpButton.Click Shell("cmd /cstart D:\work\techwrite\help.chm") End Sub

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

Будьте внимательны при вводе кодов управляющих элементов, строго соблюдайте синтаксис, приведенный в примерах – это является обязательным условием правильной работы элемента вызова файла справки.

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

Вы можете настроить свойства элементов управления в приложении Visual Basic таким образом, что при нажатии клавиши «F1» будет открываться раздел файла справки, соответствующий объекту, на котором в настоящее время находится фокус:

чтобы добавить компонент «HelpProvider», перетащите его из панели элементов в форму. Компонент отобразится в нижней части окна редактора форм;

ОБРАТИТЕ ВНИМАНИЕ! Вы можете использовать несколько компонентов «HelpProvider», например, по одному для каждой формы, или в случае, если информация о различных объектах хранится в различных файлах справки.

укажите расположение файла справки — поле «HelpNamespace» в окне свойств объекта «HelpProvider»;

ОБРАТИТЕ ВНИМАНИЕ! Вы можете указать только имя файла справки. В таком случае необходимо, чтобы он располагался в одной папке с исполнительным файлом приложения. Полный путь должен быть указан в случае раздельного размещения файлов, тогда при любом изменении места нахождения файла справки, значение параметра «HelpNamespace» должно быть заменено актуальным.

выберите интересующий объект, перейдите в окно свойств и внесите значение Help ID соответствующего объекту раздела файла справки в поле «HelpKeywordon Help Provider1». В поле «HelpNavigator on Help Provider1» выберите значение «TopicId»;

ОБРАТИТЕ ВНИМАНИЕ! Количество параметров«HelpKeyword…» и «HelpProvider…» в свойствах объектов соответствует количеству используемых компонентов«HelpProvider», ацифра в наименовании параметра соответствует номеру компонента. Будьте внимательны при заполнении данных полей.

проверьте корректную работу компонента «HelpProvider». Для этого выберите пункт «Debug -> Start debugging» главного меню, после чего на экране появится стартовая форма приложения. При нажатии клавиши «F1» должен открыться тот раздел файла справки, который соответствует элементу, находящемуся в фокусе;

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

Открытие определенных разделов файла справки с помощью компонента Help Provider

Помимо вызова определенных разделов файла справки по соответствующим им HelpID, компонент «HelpProvider» также может быть использован для адресации разделов с использованием других параметров. Для настройки вызова определенных разделов необходимо установить соответствующие значения полей «HelpKeyword on Help Provider1» и «HelpNavigator on Help Provider1» в свойствах элементов. Для настройки вывода определенных разделов файла справки при нажатии клавиши «F1» проделайте следующие действия:

добавьте компонент «HelpProvider», перетащите его из панели элементоввформу. Компонент отобразится в нижней части окна редактора форм;
укажите расположение файла справки — поле «HelpNamespace» в окне свойств объекта «HelpProvider»;
В окне свойств элемента, в поле «HelpNavigator on Help Provider1» выберите интересующий параметр:

· AssociateIndex— открывает вкладку «Указатель» иподсвечивает в списке первое по порядку ключевое слово, название которого начинается с сочетания символов в поле «HelpKeywordon Help Provider1»

· Index — открывает вкладку «Указатель» и подсвечивает в спискеключевое слово, указанное в поле «HelpKeywordon Help Provider1»

· Find — открывает вкладку «Поиск»

· TableOfContents — открывает оглавление

· Topic — открывает раздел, название которого указано в поле «HelpKeyword on Help Provider1».

ОБРАТИТЕ ВНИМАНИЕ! название раздела указывается в формате «Topic.htm», это необходимо для правильной работы вызова справки;

· TopicId — открываетраздел,которому соответствует параметр HelpID, указанный в поле «HelpKeyword on Help Provider1»

· KeywordIndex — открывает вкладку «Указатель» и выводит список разделов, содержащих ключевое слово, указанное в поле «HelpKeyword on Help Provider1».

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

Если необходимо вызвать определенный раздел справочной системы с помощью кнопки, используйте следующие фрагменты кода:

Код элемента вызова стартовой страницы справки:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Help.ShowHelp(Me, helpfile) End Sub

где help.chm— имя файла справки (файл справки должен быть размещен в одной папке с исполнительным файлом приложения)

Код элемента вызова вкладки «Указатель»:

Код элемента вызова оглавления

Код элемента вызова вкладки «Поиск»:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private findtext As String = "" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.Find Help.ShowHelp(Me, helpfile, navigator, findtext) EndSub

Код элемента вызова поиска по первым буквам ключевого слова:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private AsIndex As String = "me" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.AssociateIndex Help.ShowHelp(Me, helpfile, navigator, AsIndex) EndSub

где "me"— сочетание букв для поиска.

Код элемента вызова поиска по ключевому слову:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private Index As String = "FAQ" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.Index Help.ShowHelp(Me, helpfile, navigator, Index) EndSub

где "FAQ" — ключевое слово

Код элемента вызова раздела по его названию:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private Topic As String = "Overview.htm" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.Topic Help.ShowHelp(Me, helpfile, navigator, Topic) EndSub

где "Overview.htm"— название раздела (ключевое слово всегда указывается в формате Topic.htm)

Код элемента вызова раздела по его HelpID:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private TopicId As String = "1500" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.TopicId Help.ShowHelp(Me, helpfile, navigator, TopicId) EndSub

где "1500" — значение HelpID интересующего раздела

Код вызова списка разделов, содержащих ключевое слово:

Public Class Form1 Inherits System.Windows.Forms.Form Private helpfile As String = "help.chm" Private KeywInd As String = "menu" Private Sub HlpButton_Click(sender As System.Object, e As System.EventArgs) Handles HlpButton.Click Dim navigator As HelpNavigator = HelpNavigator.KeywordIndex Help.ShowHelp(Me, helpfile, navigator, KeywordIndex) EndSub

где "menu"— ключевое слово для поиска разделов.