SAMPLE: Navigating a Windows Help File Topic Hierarchy (83010)

SUMMARY

In many cases, a Windows Help file presents its information in a hierarchy of topics. For example, the initial screen of a Help file is a listing of the major topics in the file. Selecting a major topic brings up a list of detail topics. Selecting a detail topic displays its corresponding screen of information. The following diagram illustrates a hierarchical table of contents:

                          Table_of_Contents
                                  |
                /-----------------+-----------------\ 
          Major_Topic_1     Major_Topic_2     Major_Topic_3
          /     |     \        /       \         /       \ 
    topic_1 topic_2 topic_3  topic_4 topic_5  topic_6 topic_7

An "Up" button in a Windows Help file provides a convenient method for the user to move up the hierarchy. In a major topic, the Up button displays the table of contents. In a detail topic, the Up button displays the corresponding major topic. In the table of contents, the Up button is disabled because the table of contents is the highest point in the hierarchy.

An Up button and a "Back" button each perform different functions. While the Up button displays the topic on the next higher level of the hierarchy, the Back button returns to the topic previously viewed. In the topic hierarchy, the previous topic can be above, below, or on the same level.

UPHELP is a file in the Microsoft Download Center that contains the files required to build a Help file that implements an Up button. The file contains a graphic image of its title hierarchy. As the user navigates through the file using topic jumps and browse sequences, the graphic changes to indicate the position in the file.

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:

Uphelp.exe

For additional information about how to download Microsoft Support files, click the following article number to view the article in the Microsoft Knowledge Base:

119591 How to Obtain Microsoft Support Files from Online Services

Microsoft scanned this file for viruses. Microsoft used the most current virus-detection software that was available on the date that the file was posted. The file is stored on security-enhanced servers that help to prevent any unauthorized changes to the file.
This article details the steps required to implement an Up button in a Windows Help file to help navigate up the topic hierarchy.

There are two major steps to implementing an Up button:

Placing a button on the button bar.
Programming the button to perform the required jump.

Placing an Up Button on the Button Bar

A Help file adds a button to the button bar with the CreateButton macro. Once a button is created, it will remain on the button bar until a corresponding call is made to the DestroyButton macro. A file can call macros in a topic footnote (which is described below) or in the [CONFIG] section of the Help project (.HPJ) file. The following code adds a button to the button bar:

   [CONFIG]
   CreateButton("Up_Button","&Up","JI(`uphelp.hlp',`Table_of_Contents')")

The added button has the identifier "Up_Button" and text "Up." When the user presses this button, Help displays the "Table_of_Contents" topic in the UPHELP.HLP file.

For more information on the CreateButton macro and on the [CONFIG] section of the HPJ file, please consult the Windows Software Development Kit (SDK) documentation for version 3.1.

Programming the Up Button

At the entry to each topic, it is necessary to change the topic that Help displays when the user presses the Up button. Author an exclamation point (!) footnote into each topic of the Help file. Help executes the macros of an exclamation point footnote before it displays a topic.

The macro for the table of contents topic is different from those in the remainder of the Help file. Because the table of contents is the top of the topic hierarchy, the Up button is disabled in the table of contents topic. The text of the exclamation point footnote for the table of contents topic contains the DisableButton macro.

The exclamation point footnote in the other topics in the Help file contain two macros:

EnableButton, which is required because the topic previously displayed might have been the table of contents. (The user can use the Search feature to jump directly to a topic, bypassing the topic hierarchy.)
ChangeButtonBinding, which changes the action of the button.

Separate the text of the two macros with a semicolon (;).

The following text provides an example of an exclamation point footnote. Note that in an actual Help file, the text below would not contain any line breaks.

   ! EnableButton("Up_Button");
   ChangeButtonBinding("Up_Button",
                       "JI(`uphelp.hlp',`Table_of_Contents')")

The ChangeButtonBinding macro requires two parameters:

This first parameter is the button identifier, in this case "Up_Button".
The second parameter specifies the action of the button, in this case to call the JumpId (JI) macro. JumpID displays a specified topic in a specified Help file.

The Windows SDK documentation, version 3.1, provides additional information about the following Help macros:

ChangeButtonBinding
CreateButton
DisableButton
EnableButton
JumpId (JI)