SAMPLE: Navigating a Windows Help File Topic Hierarchy

ID: Q83010

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK) 3.1

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 Software Library 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. Click the file name below to download the file:

Uphelp.exe

For more information about how to download files from the Microsoft Download Center, please visit the Download Center at the following Web address

http://www.microsoft.com/downloads/search.asp

and then click How to use the Microsoft Download Center.

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)

Additional query words: softlib UPHELP.EXE

Keywords : kbfile kbsample kb16bitonly kbWinOS310 TlsHlp
Version : WINDOWS:3.1
Platform : WINDOWS
Issue type :