DOCUMENT:Q83010 23-JUL-2001 [win16sdk] TITLE :SAMPLE: Navigating a Windows Help File Topic Hierarchy PRODUCT :Microsoft Windows Software Development Kit PROD/VER::3.1 OPER/SYS: KEYWORDS:kbfile kbsample kb16bitonly kbOSWin310 ====================================================================== ------------------------------------------------------------------------------- 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 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 (http://download.microsoft.com/download/platformsdk/sample81/3.1/W31/EN-US/uphelp.exe) For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base: Q119591 How to Obtain Microsoft Support Files from Online Services Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that 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: 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')") 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 kbOSWin310 Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310 Version : :3.1 ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 2001.