Какой параметр функции htmlhelp указывает html файл url или chm файл

Обновлено: 05.07.2024

На этом шаге мы рассмотрим создание справки HTML Help .

Справочная система HTML Help предлагается фирмой Microsoft в качестве платформы для справочных систем следующего поколения. Для отображения справки в ней применяются разнообразные компоненты Microsoft Internet Explorer : языки HTML и Java , элементы управления на базе ActiveX , сценарии JavaScript и Microsoft Visual Basic Scripting Edition , графические файлы в форматах JPEG и GIF . Все эти элементы позволяют создать справочную систему, обладающую можностями и внешним видом полноценного Web -узла. Эту систему можно снабдить ссылками на внешние ресурсы, чтобы, например, при необходимости обращаться к Web -узлу.

Средство просмотра HTML -справки содержит панель инструментов и элементы управления для оглавления и предметного указателя, предназначенные для перемещения по страницам справки.

Установка HTML Help .
1. Запустите программу Htmlhelp.exe , которая находится в каталоге HtmlHelp на диске 1 дистрибутива Visual C++ или Visual Studio.
2. Следуя инструкциям, установите HTML Help в папку по умолчанию C:\Program Files\HTML Help Workshop .
Преобразование проекта WinHelp .
1. В Visual Studio закройте все открытые проекты. Открыв в Проводнике папку проекта МуАрр , создайте в ней подкаталог hlp .
2. В меню Пуск выберите подменю Программы , затем - HTML Help Workshop и, наконец, HTML Help Workshop .
3. В HTML Help Workshop в меню File щелкните New .
4. Выберите создание нового проекта, щелкнув ОК .

Рис.1. Выбор нового проекта

Рис.2. Установка флажка Convert WinHelp Project

Рис.3. Второй шаг мастера

Рис.4. HTML Help Workshop

Вызов HTML -справки из приложения МуАрр .
В Visual C++ откройте проект МуАрр . В меню Project выберите команду Settings .
Щёлкните вкладку Link . В списке Category выберите Input .
В поле Object/library modules modules введите htmlhelp.lib .
В поле Additional library path задайте путь к каталогу, где находится файл htmlhelp.lib (например C:\Program Files\HTML Help Workshop\lib ).

Рис.6. Окно Project Settings , вкладка Link

Рис.7. Окно Project Settings , вкладка C/C++

Рис.8. Пункт меню &Help Topics

Рис.9. Создание функции OnHelpHelptopics()

В Вашей программе этот кодможет выглядеть иначе, если путь к СНМ -файлу отличается от выбранного нами. Заметьте, что в текстовых строках символ \ должен быть представлен ESC -последовательностью \\ . Разбивая текстовую строку на несколько строк, не забудьте вставлять в конце каждой строки символ продолжения \ .

Метод Help, как видите, может с успехом использоваться в программном коде, позволяя организовать в документах Excel и Power Point выдачу собственных контекстных справок. К сожалению, в приложениях Word и Access такой способ не применим. Существует другой, более мощный способ решения этой проблемы, применимый для всех приложений. Он основан на непосредственном вызове функции API - HtmlHelp , которая реально обеспечивает работу со скомпилированным chm-файлом и всегда вызывается явно или неявно.

Использование функции API - HtmlHelp

Как и другие функции API, функция HtmlHelp написана на языке C и ее "родное" описание имеет следующий синтаксис:

HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData) Параметры этой функции имеют следующий смысл:
hwndCaller - задает описатель окна, вызываемого HtmlHelp , в котором будет появляться справка.
pszFile - указывает HTML-файл, URL или chm-файл. За именем файла может следовать определение окна, отделенное от имени знаком ">".
uCommand - задает команду, определяющую действие, выполняемое данной функцией.
dwData - указывает данные, которые требуются для выполнения той или иной команды.

Список возможных команд велик. С двумя основными командами мы познакомились при тестировании chm-файла, создаваемого в среде HHW. Этими командами являются HH_DISPLAY_TOPIC и HH_HELP_CONTEXT . Обе команды отображают в окне справки HTML-файл, но пользуются разной информацией. Для первой команды параметр pszFile задает имя chm-файла, а параметр dwData должен указывать на файл с разделом справки, являющийся частью скомпилированного chm-файла. Команда HH_HELP_CONTEXT позволяет отобразить в окне справки HTML-файл, заданный числовым идентификатором. Параметр dwData в этом случае задает значение HelpContextID .

Функция HtmlHelp входит в состав библиотеки, определяющей HTML Help ActiveX элемент управления (HHCtrl. ocx ). Она реализует некоторые функциональные возможности этого элемента. Я напомню, что этот ActiveX элемент входит в состав HTML Help Workshop .

Для того, чтобы эту функцию можно было вызывать в программном коде VBA, необходимо предварительно объявить ее в операторе DECLARE. Необходимо объявить также используемые константы, а в общем случае и типы данных. Основная проблема при этом состоит в том, чтобы правильно отобразить типы языка C на типы языка VB. Приведу два возможных варианта объявления функции HtmlHelp на VBA, которые использовались мной в экспериментах:

Обратите внимание, в первом варианте тип параметра dwData описан как Any . В этом случае при вызове не проверяется тип передаваемых данных, и вся ответственность за корректность вызова лежит на программисте. Это описание функции является универсальным и позволяет вызывать любые возможные команды, доступные для функции HtmlHelp . Во втором варианте описания функции тип параметра dwData зафиксирован. Этот вариант может быть использован при вызове команды HH_HELP_CONTEXT , когда в качестве значения передается числовой идентификатор.

Для иллюстрации возможностей работы с функцией API я использовал предыдущий пример, заменив вызовы метода Help на вызов функции HtmlHelp :

Окно справки задается по умолчанию, все остальные параметры сохранили значение, используемое в методе Help. Замечу, что работа метода Help реально сводится к вызову функции HtmlHelp . Вот как выглядит теперь вызов контекстной справки в нашей игре, открытой в Excel:

Рис. 9.27. Вызов контекстной справки, использующий API функцию HtmlHelp

Осталось выполнить обратный экспорт модифицированной формы в Word и проверить работоспособность данного способа, что я и сделал. Смею Вас уверить, что все работает, как нужно, поскольку вызов функции API и в приложении Word остается вызовом функции API, - слон он и в Африке слон.

Как и другие функции API, функция HtmlHelp написана на языке C и ее "родное" описание имеет следующий синтаксис:

HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData) Параметры этой функции имеют следующий смысл:
hwndCaller - задает описатель окна, вызываемого HtmlHelp, в котором будет появляться справка.
pszFile - указывает HTML-файл, URL или chm-файл. За именем файла может следовать определение окна, отделенное от имени знаком ">".
uCommand - задает команду, определяющую действие, выполняемое данной функцией.
dwData - указывает данные, которые требуются для выполнения той или иной команды.

Список возможных команд велик. С двумя основными командами мы познакомились при тестировании chm-файла, создаваемого в среде HHW. Этими командами являются HH_DISPLAY_TOPIC и HH_HELP_CONTEXT. Обе команды отображают в окне справки HTML-файл, но пользуются разной информацией. Для первой команды параметр pszFile задает имя chm-файла, а параметр dwData должен указывать на файл с разделом справки, являющийся частью скомпилированного chm-файла. Команда HH_HELP_CONTEXT позволяет отобразить в окне справки HTML-файл, заданный числовым идентификатором. Параметр dwData в этом случае задает значение HelpContextID.

Функция HtmlHelp входит в состав библиотеки, определяющей HTML Help ActiveX элемент управления (HHCtrl.ocx). Она реализует некоторые функциональные возможности этого элемента. Я напомню, что этот ActiveX элемент входит в состав HTML Help Workshop.

Устаревший к 1996 г. формат WinHelp был заменен на новый формат HTML Help (CHM). Его полное название — Microsoft Compiled HTML Help. Первая версия CHM вышла в 1997 г. Так как более новые форматы справки, разработанные Microsoft для замены HTML Help, так и не стали публичными, CHM сегодня остается стандартом справки для платформы Windows. Средство для просмотра CHM-файлов поддерживается во всех версиях Windows 10.

Сводная информация

Наименование:

Microsoft Compiled HTML Help (CHM) — система справки для платформы Windows.

Расширение файлов:

Платформы:

Windows 98 – Windows 10

Программа:

HTML Help Workshop

Стандартное средство для просмотра CHM файлов — hh.exe (Microsoft® HTML Help Executable). Начиная с Windows 98, оно входит в любую ОС данного семейства и располагается в папке Windows. Для вывода на экран содержимого справки hh.exe использует основные компоненты Internet Explorer. Поэтому для просмотра CHM-справки в ОС Windows достаточно, чтобы был установлен Internet Explorer.

Разработчик, 1-й релиз:

Майкрософт, 1997 г.

HTML Help 1.0 Beta (1996) и HTML Help 1.0. (1997) вышли под руководством системного архитектора Ральфа Уолдена (Ralph Walden).

С 1998 г. разработку возглавлял Шейн МакРобертс (Shane McRoberts).

История:

1996 — Анонс и выход HTML Help 1.0 Beta.

1997 — выход HTML Help 1.0 с IE4.

1998 — выход HTML Help 1.1 с Windows 98.

1999 — выход HTML Help 1.21 с IE5.

2000 — выход HTML Help 1.3 с Windows 2000. HTML Help стал обновляться с ОС Windows.

2000 – выход HTML Help 1.32 с Windows Me и IE5,5.

2001 — выход HTML Help 1.33 с Windows XP и IE6.

2002 — выход HTML Help 1.4 SDK (версия HTML Help 1.3) с Windows XP SP1 и IE6 SP1. После этого разработка была заморожена.

2004-2005 — обновления системы безопасности, запрет на работу из ЛС.

Формат - предшественник:

Формат-преемник:

Microsoft Help 2 (не публичный формат — в 2003 г. Майкрософт решила не выпускать новую платформу для справки MS Help 2).

Поддержка контекстной
справки:

Возможность изменения
внешнего вида под
пользователя:

область отображения раздела – полностью;

область отображения содержания — ограниченно, но возможно.

Применение формата

Формат HTML Help задумывался, как система доставки информации с широким спектром применения: от разработки справки для приложений, работающих под управлением ОС Windows, до создания электронных книг и интерактивных систем обучения.

Плюсы

Вся информация сохранена в одном файле.
Небольшой размер файла (алгоритм сжатия LZX).
Встроенная система полнотекстового поиска.
Возможности форматирования HTML и
Единственный на сегодня формат, поддерживающий модульные системы справки (общие оглавление и указатель формируются во время запуска).
Единственная на сегодня система справки с
Безопасность — при загрузке файлов CHM из сети содержимое файла блокируется (для разблокировки требуется участие пользователя).

Минусы

Как выглядит HTML Help

Ниже в левой части окна отображается (2) навигационная панель с вкладками Содержание, Указатель, Поиск, Избранное. Навигационную панель можно временно скрыть во время работы со справкой при помощи кнопки Скрыть (Показать – снова вывести на экран). Часть вкладок может быть полностью скрыта. Например, вкладка Избранное используется очень редко и, как правило, скрывается. Аналогично можно скрыть вкладку Поиск. Вкладка Указатель скрывается только автоматически, если в файле справки нет ни одного ключевого слова.

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

На вкладке Поиск расположены элементы управления полнотекстовым поиском по всему содержимому файла справки. Результаты поиска также отображаются на данной вкладке. При открытии найденных разделов в области просмотра автоматически подсвечивается поисковый контекст (искомый термин или термины).

На вкладке Избранное можно добавить ссылки на разделы справки для быстрого доступа к ним. Список избранных разделов справки сохраняется и отображается каждый раз при запуске файла справки. Ссылки на избранные разделы можно удалять.

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

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

Как устроен HTML Help

Контекстная справка на HTML Help

История справочных систем от Microsoft насчитывает четыре версии:

Автором WinHelp и HH является Ральф Уолден (Ralph Walden), работавший на MS с 1987 до начала 1998 года. После ухода из MS он основал KeyWorks Software.

На настоящий момент наиболее удобным форматом, с точки зрения как разработки (наличие обширного инструментария), так и распространения (поддержка операционной системой), несомненно, является HTML Help 1.3.

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

Проект

Основным файлом справки является файл проекта (.HHP), описывающий опции компиляции и содержащий ссылки на все другие файлы, участвующие при сборке. Структура .HHP-файла – это структура INI-файла. Обычно нет необходимости редактировать файл проекта вручную — все, что нужно, может быть задано с помощью HTML Help Workshop (HHW). Новый проект может быть создан с помощью мастера — командой File > New > Project.

Файл проекта может быть создан и вручную. Вот пример типичного .HHP-файла:

Содержание и предметный указатель

Содержание справки редактируется на вкладке Contents и содержится в .HHC-файле. Структура содержания — иерархическая, каждый элемент поименован, имеет иконку (выбирается из списка), к элементу содержания может быть привязана одна или несколько тем (HTML-файлов).

Предметный указатель описывается на вкладке Index и хранится в .HHK-файле.

ПРЕДУПРЕЖДЕНИЕ

.HHC и .HHK сохраняются из HHW в виде, похожем на HTML, но здесь есть одна тонкость. Если вы хотите формировать .HHC или .HHK сторонними средствами, НЕДОСТАТОЧНО, чтобы это был XML, сформированный по тому же DTD —файл должен содержать ту же шапку и такие же отступы в каждой строке — лишь в этом случае он будет принят в HHW и корректно прочитан компилятором.

ПРИМЕЧАНИЕ

Если вы хотите иметь возможность использовать в .HHC- и .HHK-файлах русский язык, не редактируйте эти файлы в HTML WorkShop – это средство не умеет работать с русским языком. – прим.ред.

Рекомендуется описать используемые во всех топиках стили с помощью CSS и поместить описание в отдельном файле — например, Manual.css — который подключать в заголовке каждой темы:

Сборка (компиляция)

В некоторых случаях может понадобиться возможность сборки справочника в автоматическом режиме — используйте утилиту hhc.exe с параметром — именем файла проекта:

Контекстная справка

Будем считать, что у нас уже написаны HTML-файлы, описывающие отдельные объекты программы (главное окно, диалоги и т.п.), и нам остается только связать программу с этими файлами.

2. В проекте справки заводим файл Map.h вида:

т.е. здесь мы описываем то же, что и в HelpContextID enum, но в другом формате. HelpContextID enum и Map.h должны быть «синхронизированы» — чтобы ID в программе и в справке всегда совпадали. В C/C++ это было проще — формат файла Map.h был специально приспособлен для того, чтобы входной файл для справки совпадал с файлом, используемым в самой программе.

В проекте справки заводим файл Aliases.h вида:

Здесь задается отображение символического имени, заданного в Map.h, на конкретную тему и место в ней.

Вызов контекстной справки происходит так: в HTML Help API передается идентификатор справки — целое число, которое определяется в HelpContextID enum — по нему (используя Map.h) определяется символическое имя, затем по символическому имени (используя Aliases.h) определяется тема, которая будет показана.

В файле проекта справки задаем ссылки на Aliases.h и Map.h:

Здесь g_HelpFilePath — глобальная переменная с полным путем к файлу справки. g_ApplicationContext — глобальная переменная с контекстом приложения, используется для получения главного окна — можно его получать любым другим способом.

Вызов из программы

Везде, где нужен вызов справки, расставляем вызовы вида:

Вызов содержания справки и предметного указателя:

Вызов средствами Win32

Хотя класс System.Windows.Forms.Help и предоставляет необходимую функциональность, бывают случаи, когда ее недостаточно. Например, окно справки всегда лежит поверх окна основного приложения, переданного первым параметром в функцию ShowHelp(). Окно справки может занимать значительное место и закрывать большую часть окна приложения — поэтому может оказаться удобным, чтобы окно справки могло перекрываться окном основного приложения. Но функция ShowHelp() не имеет такой функциональности — вы не можете передать первым параметром Nothing, поскольку получите исключение. В таком случае придется воспользоваться функцией WinAPI:

Собственно вызов выглядит так:

Теперь все отлично — окно справки висит отдельно, работать в программе не мешает.

Helpware FAR

Основной недостаток HTML Help Workshop — это его непредсказуемость. HHW может неожиданно «вылететь» практически в любой момент — например, при сохранении содержания справки, которое вы долго и мучительно редактировали. Второй недостаток — крайне неудобный интерфейс — чтобы добавить новый пункт в содержание, требуется выполнить десяток действий. Все это кажется ерундой, пока вы делаете простую справку для первой версии вашей программы — и превращается в настоящую проблему, если нужно создать мощную справочную систему с сотнями тем.

К счастью, помимо HHW существуют и другие средства разработки HTML Help, среди которых я бы особо выделил Helpware FAR — бесплатный набор утилит для работы над справкой формата HH. Вот некоторые из его возможностей:

Распространение продукта

Практически все используемые в настоящее время версии Windows уже содержат HTMLHelp:

Читайте также: