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

Введение

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для повышения удобства поиска по файлу справки создайте и настройте ключевые слова. Откройте окно ключевых слов — кнопка «Ключевые слова» (Рисунок 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 — открывает вкладку «Указатель» и подсвечивает в спискеключевое слово, указанное в поле «HelpKeyword on Help Provider1»;

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

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

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

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

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

·KeywordIndex — открывает вкладку «Указатель» и выводит список разделов, содержащих ключевое слово, указанное в поле «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 эвристик для оценки удобства использования (юзабилити) вашей документации