История справочных систем от Microsoft насчитывает четыре версии:
- WinHelp — Появилась вместе с Windows 3.0. Исходный формат базируется на RTF. Поддерживается всеми версиями Windows, но в настоящее время для новых приложений практически не используется.
- HTML Help 1.x (далее «HH») — Вышла в 1997 г. вместе с IE4. Использует для тем формат HTML и движок IE. Входит в состав всех используемых в настоящее время версий Windows.
- MS Help 2.x — Выпущена в начале 2002 г. Также использует формат HTML и движок IE. В основном используется для интеграции со справкой Visual Studio .NET
- Longhorn Help — Новая справочная система, которая будет включена в Windows Longhorn. Подробнее — Introducing Windows «Longhorn» Help
Автором WinHelp и HH является Ральф Уолден (Ralph Walden), работавший на MS с 1987 до начала 1998 года. После ухода из MS он основал KeyWorks Software.
На настоящий момент наиболее удобным форматом, с точки зрения как разработки (наличие обширного инструментария), так и распространения (поддержка операционной системой), несомненно, является HTML Help 1.3.
Создание справочного файла chm в help and manual
Создание простейшей справки
Проект
Основным файлом справки является файл проекта (.HHP), описывающий опции компиляции и содержащий ссылки на все другие файлы, участвующие при сборке. Структура .HHP-файла – это структура INI-файла. Обычно нет необходимости редактировать файл проекта вручную — все, что нужно, может быть задано с помощью HTML Help Workshop (HHW). Новый проект может быть создан с помощью мастера — командой File > New > Project.
Файл проекта может быть создан и вручную. Вот пример типичного .HHP-файла:
[OPTIONS] Binary Index=No Compatibility=1.1 or later Compiled file=MyAppHelp.chm Contents file=MyAppHelp.hhc Default Window=main Default topic=HTMLWelcome.htm Display compile progress=No Index file=MyAppHelp.hhk Language=0x419 Русский Title=Мое приложение — Справка [WINDOWS] main=,»MyAppHelp.hhc»,»MyAppHelp.hhk»,»HTMLWelcome.htm»,»HTMLWelcome.htm». 0x72520,,0x60305e,[112,11,896,658],0x100b0000. 0 [FILES] HTMLManual.css
Содержание справки редактируется на вкладке Contents и содержится в .HHC-файле. Структура содержания — иерархическая, каждый элемент поименован, имеет иконку (выбирается из списка), к элементу содержания может быть привязана одна или несколько тем (HTML-файлов).
Предметный указатель описывается на вкладке Index и хранится в .HHK-файле.
ПРЕДУПРЕЖДЕНИЕ
.HHC и .HHK сохраняются из HHW в виде, похожем на HTML, но здесь есть одна тонкость. Если вы хотите формировать .HHC или .HHK сторонними средствами, НЕДОСТАТОЧНО, чтобы это был XML, сформированный по тому же DTD —файл должен содержать ту же шапку и такие же отступы в каждой строке — лишь в этом случае он будет принят в HHW и корректно прочитан компилятором.
Если вы хотите иметь возможность использовать в .HHC- и .HHK-файлах русский язык, не редактируйте эти файлы в HTML WorkShop – это средство не умеет работать с русским языком. – прим.ред.
7 частых ошибок начинающих сценаристов
Темы
Страницы справки (темы) для HH — это обычные HTML-страницы, для создания которых может быть использован любой HTML-редактор — начиная от простейших Notepad и FAR+Colorer до монстрообразных MS Word и FrontPage.
Рекомендуется описать используемые во всех топиках стили с помощью CSS и поместить описание в отдельном файле — например, Manual.css — который подключать в заголовке каждой темы:
Сборка (компиляция)
Для сборки готового .CHM файла из HHW используйте команду File > Compile или соответствующую кнопку на панели команд.
В некоторых случаях может понадобиться возможность сборки справочника в автоматическом режиме — используйте утилиту hhc.exe с параметром — именем файла проекта:
«C:Program FilesHTML Help Workshophhc.exe» AMADocBase.hhp
Контекстная справка
Будем считать, что у нас уже написаны HTML-файлы, описывающие отдельные объекты программы (главное окно, диалоги и т.п.), и нам остается только связать программу с этими файлами.
1. В проекте на VB.NET заводим отдельный модуль (например, HelpSystem). В нем мы описываем все вещи в программе, для которых у нас будет контекстная справка, например:
Public Enum HelpContextID FormMain = 2001 FormLogin = 2002 FormError = 3010 FormWait = 3030 . EndEnum
2. В проекте справки заводим файл Map.h вида:
#define FormMain 2001 #define FormLogin 2002 #define FormError 3010 #define FormWait 3030 .
т.е. здесь мы описываем то же, что и в HelpContextID enum, но в другом формате. HelpContextID enum и Map.h должны быть «синхронизированы» — чтобы ID в программе и в справке всегда совпадали. В C/C++ это было проще — формат файла Map.h был специально приспособлен для того, чтобы входной файл для справки совпадал с файлом, используемым в самой программе.
В проекте справки заводим файл Aliases.h вида:
FormLogin=HTML2_2.htm FormMain=HTML3_1.htm#FormMain FormWait=HTML2_2.htm .
Здесь задается отображение символического имени, заданного в Map.h, на конкретную тему и место в ней.
Вызов контекстной справки происходит так: в HTML Help API передается идентификатор справки — целое число, которое определяется в HelpContextID enum — по нему (используя Map.h) определяется символическое имя, затем по символическому имени (используя Aliases.h) определяется тема, которая будет показана.
В файле проекта справки задаем ссылки на Aliases.h и Map.h:
[ALIAS] #include Aliases.h [MAP] #include Map.h
3. В программе на VB.NET описываем вызов справки:
‘ Показывает TOC или Index справочной системы. ‘ HelpNavigator.TableOfContents или HelpNavigator.Index Public Sub ShowHelp(ByVal val As HelpNavigator) IfNot CheckHelpFileExists() ThenExitSubDim mainForm As Form = Common.g_ApplicationContext.MainForm Help.ShowHelp(mainForm, g_HelpFilePath, val) EndSub’ ‘ Показывает страницу справочной системы, соответствующую значению contextID. ‘ PublicSub ShowHelp(ByVal contextID AsInteger) IfNot CheckHelpFileExists() ThenExitSubDim id AsInteger = contextID Dim mainForm As Form = Common.g_ApplicationContext.MainForm Help.ShowHelp(mainForm, g_HelpFilePath, CType(15, HelpNavigator), id) EndSub’ ‘ Показывает страницу справочной системы, соответствующую значению contextID. ‘ PublicSub ShowHelp(ByVal parent As Control, ByVal contextID AsInteger) IfNot CheckHelpFileExists() ThenExitSubDim id AsInteger = contextID Dim mainForm As Form = Common.g_ApplicationContext.MainForm Help.ShowHelp(parent, g_HelpFilePath, CType(15, HelpNavigator), id) EndSub
Здесь g_HelpFilePath — глобальная переменная с полным путем к файлу справки. g_ApplicationContext — глобальная переменная с контекстом приложения, используется для получения главного окна — можно его получать любым другим способом.
Вызов из программы
Везде, где нужен вызов справки, расставляем вызовы вида:
Private Sub btnHelp_Click(ByVal sender AsObject, _ ByVal e As System.EventArgs) Handles btnHelp.Click HelpSystem.ShowHelp(Me, HelpContextID.FormContactProps) EndSub
Вызов содержания справки и предметного указателя:
HelpSystem.ShowHelp(HelpNavigator.TableOfContents) HelpSystem.ShowHelp(HelpNavigator.Index)
Вызов средствами Win32
Хотя класс System.Windows.Forms.Help и предоставляет необходимую функциональность, бывают случаи, когда ее недостаточно. Например, окно справки всегда лежит поверх окна основного приложения, переданного первым параметром в функцию ShowHelp().
Окно справки может занимать значительное место и закрывать большую часть окна приложения — поэтому может оказаться удобным, чтобы окно справки могло перекрываться окном основного приложения. Но функция ShowHelp() не имеет такой функциональности — вы не можете передать первым параметром Nothing, поскольку получите исключение. В таком случае придется воспользоваться функцией WinAPI:
Public Enum HTMLHelpCommand HH_DISPLAY_TOPIC = 0 HH_DISPLAY_TOC = 1 HH_DISPLAY_INDEX = 2 HH_DISPLAY_SEARCH = 3 HH_HELP_CONTEXT = H12 EndEnum «hhctrl.ocx», EntryPoint:=»HtmlHelp», CharSet:=CharSet.Auto)> _ Function HTMLHelp( _ ByVal hWndCaller As IntPtr, ByVal pszFile AsString, _ ByVal uCommand AsInteger, ByVal dwData AsInteger) AsIntegerEndFunction
Собственно вызов выглядит так:
WinAPI.HTMLHelp(Nothing, filePath, HTMLHelpCommand.HH_HELP_CONTEXT, contextID) WinAPI.HTMLHelp(Nothing, filePath, HTMLHelpCommand.HH_DISPLAY_TOC, 0)
Теперь все отлично — окно справки висит отдельно, работать в программе не мешает.
Helpware FAR
К счастью, помимо HHW существуют и другие средства разработки HTML Help, среди которых я бы особо выделил Helpware FAR — бесплатный набор утилит для работы над справкой формата HH. Вот некоторые из его возможностей:
- Редактор проекта (.HHP).
- Редактор содержания (.HHC) и предметного указателя (.HHK).
- Утилита проверки связей в .CHM (Link Checker).
- Сжатие .CHM.
Распространение продукта
Практически все используемые в настоящее время версии Windows уже содержат HTMLHelp:
| Windows 95 | не содержит |
| Windows 95 OSR2 | не содержит |
| Windows NT 4 | не содержит |
| Windows 98 | 1.1a |
| Windows 98 SE | 1.21 |
| Windows ME | 1.32 |
| Windows 2000 | 1.30 |
| Windows 2000 SP1-3 | 1.31 |
| Windows XP | 1.33 |
| Windows XP SP1 | 1.4 |
| Windows XP SP2 | 1.4e |
В Windows 95/98/NT можно установить HH с помощью дистрибутива HHUPD.EXE, который доступен после установки HHW. Для работы HH требуется IE 3.0 и выше. Для использования DHTML, очевидно, нужен IE версии 4, для XML понадобится IE версии 5 и выше. Последние версии IE включают в себя обновление HH — например, в состав IE 6.0 SP1 входит HH 1.4. Более подробно — см.
HTML Help — Tech Info.
Ссылки
Общая информация
- MSDN — Microsoft Help Technologies Start Page
- MSDN — HTML Help Frequently Asked Questions
- MSHelpWiki
- http://www.winwriters.com/
- http://www.g2meyer.com/usablehelp/
- Help Technology Centre — Resources and Techniques for Help Systems
Инструментарий
- Microsoft HTML Help Downloads
- http://helpware.net/
- KeyWorks Software
Написание руководства пользователя
- MetaGuide — Руководство для разработчиков технической документации к программному обеспечению
- Форум технических писателей и переводчиков
- КТ №43 / В поисках тленного стиля
- КТ №43 / Милостивый государь, технический писатель
- Как сделать хорошее руководство пользователя
Источник: www.rsdn.org
Примеры help для программы
Работа с кнопкой Help в заголовке окна
В самом начале развития Windows во многих приложениях очень часто встречалась кнопка «Help» в заголовке окна. Кликнув на нее и переместив курсор на нужный элемент, пользователь мог получить подсказку, например, какие данные надо вводить в конкретное текстовое поле или что получится, если нажать какую-нибудь кнопку.
Сейчас UIX-дизайнеры прокачали свои навыки, кнопка справки стала уже не так популярна, по крайней мере я не встречал ее ни в одном современном приложении. Но может быть кому-нибудь будет интересно, как ей пользоваться и как правильно обрабатывать ее сообщения. Начнем с интерфейса. Чтобы в заголовке окна появилась кнопка справки, оно должно быть изначально создано с расширенным стилем WS_EX_CONTEXTHELP. Для динамического управления кнопкой справки можно воспользоваться способом, описанным в этой статье.
Из программной части нам понадобится одна структура, которую почему-то не знает коробочный FASM. Хотя, блин, чему я удивляюсь.
Code (Assembler) : Убрать нумерациюВыделить код
- struct HELPINFO
- cbSize dd ?
- iContextType dd ?
- iCtrlId dd ?
- hItemHandle dd ?
- dwContextId dd ?
- MousePos POINT
- ends
Суть контекстной справки заключается в том, чтобы при выборе пользователем какого-либо элемента диалогового окна, ему была предоставлена информация именно по этому элементу. Для персонализации справки можно назначить конкретному элементу окна контекстный идентификатор справки при помощи функции SetWindowContextHelpId. Это один из вариантов, с помощью которого в дальнейшем можно будет персонализировать справку.
Code (Assembler) : Убрать нумерациюВыделить код
- . wminitdialog :
- ; Назначить контекстный идентификатор справки элементу окна
- invoke GetDlgItem , [ hwnddlg ] , ID_BUTTON_1
- invoke SetWindowContextHelpId , eax , 777
При нажатии кнопки справки в заголовке окна и выборе какого-нибудь элемента диалогового окна, родительскому окну отправляется сообщение WM_HELP, которое мы должны обработать.
Когда окну приходит сообщение WM_HELP, в параметре lParam передается указатель на структуру HELPINFO, в которой содержится исчерпывающая информация об элементе и координатах окна, по которым пользователь запросил справку.
Code (Assembler) : Убрать нумерациюВыделить код
- cmp [ msg ] , WM_HELP
- je . wmhelp
- . . .
- . wmhelp :
- ; Указатель на структуру HELPINFO
- movesi , [ lparam ]
- ; Проверить контекстный идентификатор справки
- cmpdword [ esi + HELPINFO . dwContextId ] , 777
- je . info_1
- ; Проверить хэндл элемента окна
- invoke GetDlgItem , [ hwnddlg ] , ID_EDIT_FIELD_01
- cmpdword [ esi + HELPINFO . hItemHandle ] , eax
- je . info_2
- ; Проверить ID элемента окна
- cmpdword [ esi + HELPINFO . iCtrlId ] , ID_EDIT_FIELD_02
- je . info_3
- ; Проверить по координатам элемента окна
- invoke GetDlgItem , [ hwnddlg ] , ID_BUTTON_2
- invoke GetWindowRect , eax , pos
- invoke PtInRect , pos , [ esi + HELPINFO . MousePos . x ] , [ esi + HELPINFO . MousePos . y ]
- oreax , eax
- jnz . info_4
- . . .
В поле iCtrlId передается ID элемента, в поле hItemHandle — хэндл элемента, в dwContextId — контекстный идентификатор справки, назначенный ранее функцией SetWindowContextHelpId, а во вложенной структуре MousePos — координаты в окне, на которых была запрошена справка. Определив координаты клика, можно определить их вхождение в границы нужного элемента или область окна с помощью функции PtInRect. В зависимости от решаемой задачи, вы можете применить тот или иной способ для определения, какой раздел справки хотел бы увидеть пользователь.
Теперь, зная, к какому элементу диалогового окна пользователь запросил подсказку, можно открыть файл справки на требуемом разделе, вывести окно сообщения с подсказкой или еще как-нибудь помочь пользователю с запрошенной информацией.
В приложении пример программы с исходным текстом, которая использует контекстную справку для элементов диалогового окна.
Пример программы с исходным текстом (FASM)
Источник: www.manhunter.ru
LCL Lazarus. Разработка справочной системы.
уважаемые посетители блога, если Вам понравилась, то, пожалуйста, помогите автору с лечением. Подробности тут.
Не так давно я писал в блоге о разработке chm-справки для своих Delphi-программ. Сегодня рассмотрим те возможности, которые предоставляет нам Lazarus для разработки справочной системы программы. В целом, поработав некоторое время в различных операционных системах невольно приходит на ум мысль вообще забыть про всякого рода chm, hlp и прочие файлы справок, а сделать простую справку из набора html-файлов, избавив себя тем самым от головной боли типа “А запуститься справка на том компьютере? А на этом?”, если нет, то “Какой формат справки сделать?” и т.д.
С одной стороны простые html-файлы значительно проигрывают в удобстве той же справке сделанной в виде chm – нет удобного поиска, индекса и т.д. и т.п. Но с другой стороны – нет проблем с запуском. И как раз для работы с HTML-справкой в LCL (Lazarus Component Library) есть два довольно простых компонента:THTMLHelpDatabase и THTMLBrowserHelpViewer. Первый предназначен для хранения информации по справочной системы, а второй — для её (информации) представления пользователю.
В начале рассмотрим довольно простой пример как быстро и без особых хлопот внедрить справочную систему в программу, созданную в Lazarus.
Содержание скрыть
1. Подготовка справки
В принципе материал этой части статьи больше относится к работе с HTML, чем к Lazarus и FreePascal. Все, что от Вас требуется – это создать в директории с Вашим проектом ещё одну, например, с названием help и в этой директории разместить все html-файлы справочной системы. Что содержит справка – сейчас совершенно не важно.
2. Работа с THTMLHelpDataBase
Компонент THTMLHelpDataBase управляет содержимым. В качестве содержимого может выступать как набор HTML-файлов (как в нашем случае) так и XML-файлы, созданные утилитой fpdoc или chm-файлы.
THTMLHelpDataBase имеет всего 5 свойств из которых 2 (Name и Tag) не требуют от нас какого-либо пристального изучения – про них мы и так знаем. Три остальных – это:
AutoRegister: boolean – если значение этого свойства True, то справочная система создается автоматически и отпадает необходимость впоследствии выполнять метод RegisterSelf для создания необходимых элементов справочной системы.
BaseURL: string – путь к файлам справочной системы. В нашем путь можно задавать как относительно директории приложения, например, так: file://help/, так и задавать абсолютный пусть, например, C:myproghelp. Так же, можно указывать и URL’ы.
KeywordPrefix: string – определяет с какой подстроки должны начинаться ключевые слова (свойство HelpKeyword компонентов).
Теперь создадим новое приложение, разместим на форме компонент THTMLHelpDataBase и установим для него следующие свойства:
Сохраним проект и в директории с проектом создадим ещё одну с названием help в которую поместим несколько html-файлов, которые будем отображать в зависимости от запросов пользователя.
3. Работа с THTMLBrowserHelpView.
По большому счёту необходимость использования этого компонента может потребоваться только для того, чтобы сократить время на разработку и буквально в два клика мышкой создать просмотрщик HTML-файлов, основанный на работе с Web-браузером, установленным в системе. При желании, можно обойтись и без этого компонента, создав свой просмотрщик на основе базового класса THelpViwer. Но так как сегодня мы рассматриваем способ быстрого создания справочной системы, то воспользуемся этим компонентом.
У THTMLBrowserHelpView определены следующие свойства:
AutoRegister: boolean — как и в случае с предыдущим компонентом, если это свойство равно True, то просмотрщик автоматически регистрируется в системе.
BrowserParams: string – параметры командной строки для браузера. По умолчанию свойство равно %s. Т.е. это означает, что при запуске браузера ему будет передаваться в параметрах строка – URL или путь до HTML-файла.
BrowserPath: string – путь до исполняемого файла браузера. Вообще не желательно указывать этот путь сразу же в свойствах компонента, т.к., сами понимаете, браузер может быть установлен и не ам где Вы ожидаете его увидеть на компьютере пользователя. Поэтому к этому свойству мы ещё вернемся.
Размещаем компонент THTMLBrowserHelpView на форме нашего приложения и устанавливаем свойство AutoRegister равным True. И теперь займемся работой со свойством BrowserPath. Вообще-то у компонента определен один замечательный метод:
FindDefaultBrowser(out Browser, Params: string);
Который возвращает путь и параметры запуска браузера по умолчанию. Но вот сейчас его попробовал использовать и метод возвращает в browser пустую строку. Раньше работал 🙂 Не работает и бог с ним, воспользуемся более грубым, но тем, не менее рабочим способом. Если на компьютере используется ОС Windows, то в BrowserPath необходимо указать путь до rundll32.exe, например:
C:/windows/system32/rundll32.exe
а в параметрах следующую строку:
url.dll,FileProtocolHandler %s
Всё, что по большому счёту необходимо – это определить путь до Windows. В случае с Ubuntu (Linux) строка для BrowserPath может выглядеть как:
usr/bin/xdg-open
а в BrowserParams:
Теперь вне зависимости от того сколько браузеров есть у пользователя на компьютере все HTML-файлы справки будут запускаться в браузере по умолчанию.
И остается только продемонстрировать как работает наша простая справочная система. Для этого достаточно установить следующие свойства главной формы:
HelpType = htKeyword
HelpKeyword = ‘help/index.html’
Теперь запустите приложение и нажмите F1 – в браузере откроется страничка Index.html (если она у Вас, конечно была в директории help). Аналогичным образом можно настроить и показ справки для других компонентов, расположенных на формах Вашего приложения.
Так, буквально за пять минут мы создали с вами простейшую справочную систему для приложения. Как я уже сказал в начале, эта система не лишена некоторых недостатков, но, для первого раза сойдет :).
Источник: webdelphi.ru