Advanced MFC Programming

Chapter 16. Context Sensitive Help
page, make sure that “None” is selected from the “Underline” combo box, and check “Hidden” check box
within “Effects” section.
ID Mapping
In order to support context sensitive help, we must link the footnotes to their corresponding command
IDs. In our case, we need to link “help_test_A” to ID_HELPTEST_TESTA, “help_test_B” to
ID_HELPTEST_TESTB… and so on.
This ID mappings are implemented in “.hm” file, so by opening file “Help.hm” with a text editor, we
will see all the IDs of the help items supported in the sample. Generally help IDs are generated according to
certain rules: it bases the help ID of a control (or a window) on its resource ID. By default, for a command
whose ID starts with “ID_”, MFC generates symbolic help ID by prefixing a character ‘H’ to the resource
ID. For example, for command ID_HELPTEST_TESTA, the help ID generated by MFC is
HID_HELPTEST_TESTA. For the actual ID value, MFC generates it by adding a fixed number to the
corresponding resource ID value. For example, if the value of ID_HELPTEST_TESTA is 0x8004, the value of
HID_HELPTEST_TESTA would be 0x18004 ⎯ here a number of 0x1000 is added to the command resource
ID.
By doing this, when the user executes a command in the help mode (When the mouse cursor changes
to a question mark after the user clicks command ID_CONTEXT_HELP), the application will first find out the
resource ID of the command being executed, add a fixed value, then pass the result to the help. By using
this rule to generate ID for a help item, it is easier for us to implement context-sensitive help.
Although the ID mapping is customizable, which means we can prefix different character(s) to a
resource ID for generating help ID (For example, the help ID of command ID_HELPTEST_TESTA could be
HLID_HELPTEST_TESTA), and we can add any value to the resource ID to generate a help ID, it is more
convenient if we stick to the rules of MFC. For example, if we add 0x20000 instead of 0x10000 to the
resource ID to make a help ID, we also need to add some code to the program to customize its default
behavior.
Another problem still remains: since we’ve already added footnotes and defined our own tags, the
command IDs are still not directly linked to the footnote tags. For example, the help ID of command
ID_HELPTEST_TESTA is HID_HELPTEST_TESTA, while the footnote tag implemented in the help file is
“help_test_A”. This can be solved by defining alias names in the help project file. By opening “*.HPJ” file,
we will see an [ALIAS] session. Under this session, a help ID can be linked directly to a footnote tag. In
our case, the footnote tags are “help_test_A”, “help_test_B”…, and the help IDs automatically generated
by MFC are HID_HELPTEST_TESTA, HID_HELPTEST_TESTB…. To link them together, we can add the following
to alias session:
……
[ALIAS]
HID_HELPTEST_TESTA=help_test_A
HID_HELPTEST_TESTB=help_test_B
HID_HELPTEST_TESTC=help_test_C
HID_HELPTEST_TESTD=help_test_D
Obviousely, if we use the default help ID strings to implement footnote tags (i.e., use
HID_HELPTEST_TESTA instead of help_test_A as the footnote tag), the ID mapping could be eleminated.
By doing this, when the user executes certain command in the help mode, the corresponding help page
will be automatically brought up.
Help Topics Dialog Box
The footnotes can also be referenced from “Help Topics” dialog box. This dialog box is activated
when the user executes command ID_HELP_FINDER. The contents contained in “Help Topics” dialog box
are stored in “.cnt” file. To edit this file, we can open it using Help Workshop. In the Help Workshop, we
can add two types of items: Heading and Tab Entry. A heading will not be linked to any footnote. Under
each heading, we can add several tab entries, which need to be linked to footnotes. A new item can be
added by clicking buttons labeled “Add Above…”, “Add Below…”. After that, a dialog box will pop up
asking us to input the description text as well as the help ID (the footnote tag). The description of an item
485