Context-Sensitive Help for Applications
Context-sensitive help assists users by providing help based on a specific dialog box or control in a program. This enables users to get specific information about whatever part of the program they are using at any given moment.
Help authors usually work together with developers to create context-sensitive help. The help author creates a compiled help (.chm) file that contains the context-sensitive help topics and information that maps the topics to specific dialog boxes or controls. The developer modifies the program code so that the correct topic appears when a user requests help.
Context-sensitive help commonly appears in a pop-up window, which displays a help topic about a specific user interface element. For example, you can design your program to have a question mark button in the title bar of a dialog box. When a user clicks the question mark button, and then clicks anywhere in the dialog box, they will see a pop-up help topic that provides information about the user interface element they clicked.
Source for the HTMLHelp project file
Open your .hhp file in a text editor and add the sections ALIAS and MAP to the HTMLHelp project file and add the files to your help project:
[OPTIONS]
Auto Index=Yes
...
[WINDOWS]
main="Online Help","CHM-example.hhc",...
wndTopic="New Topic Window","CHM-example.hhc", ...
[FILES]
design.css
index.htm
Context-sensitive_example\contextID-10000.htm
Context-sensitive_example\contextID-10010.htm
Context-sensitive_example\contextID-20000.htm
Context-sensitive_example\contextID-20010.htm
Garden\flowers.htm
Garden\garden.htm
Garden\tree.htm
HTMLHelp_Examples\CloseWindowAutomatically.htm
HTMLHelp_Examples\Jump_to_anchor.htm
HTMLHelp_Examples\shortcut_link.htm
HTMLHelp_Examples\Simple_link_example.htm
images\blume.jpg
...
[ALIAS]
#include alias.h
[MAP]
#include map.h
#include topic.h
[TEXT POPUPS]
topic.h
topic.txt
[INFOTYPES]
ALIAS and MAP files
The purpose of the two files is to ease the coordination between developer and help author. The mapping file links an ID to the map number - typically this can be easily created by the developer and passed to the help author. Then the help author creates an alias file linking the IDs to the topic names.
ALIAS file
In a text editor enter the ALIAS details like IDH_90000=index.htm. Save the file as 'alias.h' in same folder as your help project file.
;----------------------------------------
; alias.h file example for HTMLHelp (CHM)
; www.help-info.de
;
; All IDH's > 10000 formatted for better reading
; last edited: 2006-07-09
;----------------------------------------
IDH_90000=index.htm
IDH_10000=Context-sensitive_example\contextID-10000.htm
IDH_10010=Context-sensitive_example\contextID-10010.htm
IDH_20000=Context-sensitive_example\contextID-20000.htm
IDH_20010=Context-sensitive_example\contextID-20010.htm
Multiple map numbers for one topic:
The HTMLHelp ALIAS file will certainly let you assign multiple map IDs to one topic, e.g.
Anchor in the middle of the topic:
If you would like to jump from your program to an anchor in the middle of a topic you have to add e.g. following line to your alias.h file:
But you'll get e.g. the following error message:
HHC3015: Warning: An alias has been created to "HTMLHelp_Examples\jump_to_anchor.htm#AnchorSample" but the file does not exist.
The KeyTools HTMLHelp Error Message Reference (CHM in ZIP) says that you can safely ignore this error message - the link should still work. If it bothers you, though, you can suppress the message by changing your aliases to, for example:
But note - this means renaming the CHM will break the alias!MAP file
In a text editor enter the MAP details like #define IDH_90000 90000;frmMain. Save the file as 'map.h' in same folder as your help project file.
;--------------------------------------
; map.h file example for HTMLHelp (CHM)
; www.help-info.de
;
; All IDH's > 10000 formatted for better reading
; ;comment at end of line related to GUI
;--------------------------------------
#define IDH_90000 90000;frmMain
#define IDH_10000 10000;frmAddressDataContextID-1
#define IDH_10010 10010;frmAddressDataContextID-2
#define IDH_20000 20000;frmAddressDataContextID-3
#define IDH_20010 20010;frmAddressDataContextID-4
Multiple map numbers for a topic
HTMLHelp will certainly let you assign multiple map IDs to one topic. Please note the assignment in the ALIAS file.
#define IDH50000_0 50000;comment-0
#define IDH50000_1 50001;comment-1
#define IDH50000_2 50002;comment-2
Anchor in the middle of the topic
If you would like to jump from your program to an anchor in the middle of a topic (see above) you have to add e.g. following line to your map.h file:
#define IDH_30000 30000;frmAddressDataContextID-5
Recompile your .HHP file. Now your application can call help using context help ID's instead of topic file names.
Topic-ID and Topic-Text for "What's this?" Help
topic.h
;-------------------------------------------------------------
; topic.h file example for HTMLHelp (CHM)
; www.help-info.de
;
; All IDH's < 10000 to avoid same ID in map.h
; This is a mapping of "What's this?" or F1 PopUp help for VB6
; ;comment at end of line
;-------------------------------------------------------------
#define IDH_900 900;nohelp
#define IDH_100 100;PopUp_AddressData_btnOK
#define IDH_110 110;PopUp_AddressData_txtFirstName
#define IDH_120 120;PopUp_AddressData_txtLastName
topic.txt
;-------------------------------------------------
; topic.txt file example for HTMLHelp (CHM)
; www.help-info.de
;
;
; This is a file including the ID and PopUp text
;-------------------------------------------------
.topic IDH_900
Sorry, no help available!
.topic IDH_100
This is context sensitive help text for a button (ID: IDH_100).
.topic IDH_110
This is context sensitive help text for a text box (ID: IDH_110).
.topic IDH_120
This is context sensitive help text for a text box (ID: IDH_120).