Создание файла помощи - файла справки - в формате CHM для .NET Windows-приложения - с примерами

Введение

В этой статье рассматривается вопрос создания файла справки в формате CHM с помощью программы Dr.Explain, а также его интеграция в .NET-приложение.
Из статьи вы узнаете:

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

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

Вы можете скачать установочный файл программы Dr.Explain на официальном сайте по адресу https://www.drexplain.ru/download/. Для этого воспользуйтесь кнопкой «Скачать бесплатно». После того как файл будет загружен, запустите его. Для установки программы пройдите стандартную процедуру, следуя указаниям мастера установки (Рисунок 1). При использовании пробной версии Dr.Explain доступны все функции, но все изображения в экспортированных файлах помечаются водяными знаками и есть ограничение на размер создаваемого проекта.

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

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

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

Рисунок 2. Окно Dr.Explain «Список проектов»

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

Наполнение дерева разделов в файле справки

Чтобы получить удобную исчерпывающую структуру файла справки создайте отдельные темы для описания всех форм и объектов .NET-приложения.

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

Рисунок 3. Управление деревом проекта «Dr.Explain»

Настройте порядок и иерархию разделов, используя команды контекстного меню «Выше» и «Ниже» . Изменить названия темы можно с помощью пункта «Переименовать», либо просто нажав клавишу F2.

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

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

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

Для создания описания интерфейса вашего .NET-приложения и его отдельных элементов воспользуйтесь функцией захвата скриншота - кнопка — «Схватить экран».

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

После открытия окна «Захват объекта» (Рисунок 5) установите метки в поле «Accessible -объект» или «Win 32-окно», затем выполните захват скриншота интересующей формы одним из способов, предложенных в окне захвата. В дерево разделов будет автоматически добавлен раздел, содержащий аннотированное изображение формы (Рисунок 6). В окне Дизайнера можно добавить и удалить аннотацию или изменить порядок следования описания отдельных элементов.

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

Настройка значений Help ID для создания контекстной помощи

Для того, чтобы впоследствии можно было выполнить привязку разделов файла справки к конкретным элементам интерфейса .NET-приложения, необходимо определить значения Help ID-идентификаторов для всех разделов. Выберите в структуре проекта нужный раздел и перейдите в поле «Help ID» свойствах раздела (Рисунок 7). При необходимости измените значение, для сохранения изменений просто уберите фокус с этого поля.

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

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

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

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

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

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

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

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

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

Создайте в форме .NET-приложения элемент вызова файла справки, например, кнопку. Для этого выполните следующие действия:

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

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

• в редакторе кода (Рисунок 10) в строке «private void HlpButton _Click(object sender, EventArgs e)» отображается имя элемента вызова файла справки (в данном случае "Help Button"). Введите ниже строку – «Help.ShowHelp(this, "Help.chm");», где Help.chm — имя файла справки в формате CHM. Код элемента управления в целом должен иметь вид:

 private void HlpButton_Click(object sender, EventArgs e)
 {
	Help.ShowHelp(this, "Help.chm");
 }
 

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

• убедитесь в правильной работе кнопки вызова файла справки. Запустите отладку — пункт «Debug -> Start debugging» главного меню, после чего произойдет запуск приложения. Нажмите кнопку «Help» созданный ранее файл справки в формате CHM должен открыться в отдельном окне;


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

ОБРАТИТЕ ВНИМАНИЕ: Для правильной работы кнопки вызова справки располагайте CHM файл и исполняемый файл .NET-приложения в одной папке. Если необходимо иное размещение файлов, используйте для кнопки вызова справки следующий код:

string commandText = @"D:\work\techwrite\help.chm”;
var proc = new System.Diagnostics.Process();
proc.StartInfo.FileName = commandText;
proc.StartInfo.UseShellExecute = true;
proc.Start();

где @"D:\work\techwrite\help.chm” - полный путь до файла справки в формате CHM. Код элемента в целом будет иметь вид:

private void HlpButton_Click(object sender, EventArgs e)
{
	string commandText = @"D:\work\techwrite\help.chm”;

	var proc = new System.Diagnostics.Process();
 	proc.StartInfo.FileName = commandText;
 	proc.StartInfo.UseShellExecute = true;
 	proc.Start ();
 }
 

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

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

Привязка тем файла CHM к объектам .NET-приложения

Альтернативный вариант вывода справки, заключается в вызове определенных разделов справки, которые соответствуют отдельным элементам .NET- приложения. Такой способ можно использовать самостоятельно, либо совместно с описанным выше методом. При нажатии клавиши «F1» выводится тот раздел фала справки, который соответствует элементу приложения, находящемуся в фокусе в момент нажатия. Для реализации такого метода выполните следующие действия:

• добавьте компонент «Help Provider» путем егоперемещения в форму приложения из панели элементов. Значок компонента появится в нижней части окна редактора форм;

ОБРАТИТЕ ВНИМАНИЕ: Допускается использование нескольких компонентов «Help Provider». Это удобно в том случае, когда информация о различных элементах содержится в различных файлах справки. Также вы можете использовать отдельные компоненты для различных форм;

• в окне свойств элемента «Help Provider» укажите расположение файла справки — поле «HelpNamespace»

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

• в окне свойств объекта внесите значение Help ID соответствующего объекту раздела справки в поле «HelpKeyword on Help Provider1». Выберите значение «TopicId» для поля «Help Navigator on Help Provider1»

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

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

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

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

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

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

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

·Index — откроет вкладку CHM-файла «Указатель» и подсвечивает в списке ключевое слово, указанное в поле «HelpKeyword on Help Provider1»;

·Find — откроет вкладку CHM-файла «Поиск»;

·TableOfContents — откроет оглавление CHM-файла;

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

Важно: Название раздела указывается в формате «Topic.htm», это необходимо для правильной работы вызова файла справки.

·TopicId — откроет раздел CHM-файла, которому соответствует значение параметра Help ID, определенное в поле «HelpKeyword on Help Provider1»;

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

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

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

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            Help.ShowHelp(this, helpfile);

        }
    }
}

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

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            Help.ShowHelpIndex(this, helpfile);

        }
    }
}

Код вызова оглавления:

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.TableOfContents;
            Help.ShowHelp(this, helpfile, navigator);

        }
    }
}

Код вызова вкладки «Поиск»:

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string findtext = "";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.Find;
            Help.ShowHelp(this, helpfile, navigator, findtext);

        }
    }
}

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string AsInd = "me";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.AssociateIndex;
            Help.ShowHelp(this, helpfile, navigator, AsInd);

        }
    }
}

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

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string Index = "FAQ";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.Index;
            Help.ShowHelp(this, helpfile, navigator, Index);

        }
    }
}

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

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string Topic = "Overview.htm";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.Topic;
            Help.ShowHelp(this, helpfile, navigator, Topic);

        }
    }
}

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

Код вызова раздела по его HelpID:

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string TopicId = "1500";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.TopicId;
            Help.ShowHelp(this, helpfile, navigator, TopicId);

        }
    }
}

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

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

namespace WindowsFormsApplication1
{
    public partial class Form1 : Form
    {
        private const string helpfile = "help.chm";
        private const string KeywInd = "menu";
        public Form1()
        {
            InitializeComponent();
        }

        private void Form1_Load(object sender, EventArgs e)
        {

        }

        private void HlpButton_Click(object sender, EventArgs e)
        {
            HelpNavigator navigator = HelpNavigator.KeywordIndex;
            Help.ShowHelp(this, helpfile, navigator, KeywInd);

        }
    }
}

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

Смотрите также

• Разработка пользовательской документации для включения программного продукта в Реестр отечественных программ Минцифра России
• Создание help-файла (справки) в формате CHM для Visual Basic (VB.NET)-приложения для Windows при помощи Dr.Explain
• 10 эвристик для оценки удобства использования (юзабилити) вашей документации