SAMPLE: Navigating a Windows Help File Topic Hierarchy

• Microsoft Windows Software Development Kit (SDK) for Windows version 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 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.

Download UPHELP.EXE, a self-extracting file, from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download UPHELP.EXE (size: 26674 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the \SOFTLIB\MSLFILES directory
        Get UPHELP.EXE (size: 26674 bytes) 
  

MORE INFORMATION

There are two major steps to implementing an Up button:

1. Placing a button on the button bar.

2. 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')")

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.

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')")

• 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.

• ChangeButtonBinding
• CreateButton
• DisableButton
• EnableButton
• JumpId (JI)