Jack and Keith are the principals of TriStar Systems, Inc. a consulting firm specializing in C and C++ applications and training. They can be contacted via TriStar at 122 E. Morningside Dr., Oak Ridge, TN 37830 or on CompuServe at 70312,132 or 72203,3612.
Introduction
MS-Windows 3.x applications typically incorporate a robust, application-specific help system. This system, usually accessed via the application's help menu or by pressing the F1 key, allows for context-sensitive responses, keyword searches, and hypertext links between topics. The key to the system is the MS-Windows help engine, winhelp.exe, which the Windows setup program installs so that every windows installation has access to it. The help engine provides the user with a consistent interface to both system and application help. It also means that you, as a developer, have access to the help engine used by contemporary, Windows-based software.To use the help engine, you create and ship with your program a Windows resource file with the extension of .hlp. An application accesses this file through an API call to the Winhelp engine. Most of the help features (except for context-sensitive help) are available independent of your program. Thus you can add a professional help system with little effort and even less code.
In this article we show you how to build and use a basic Windows help system (Listing 1, Listing 2, Listing 3, Listing 4, Listing 5, Listing 6, and Listing 7 contain code for a demonstration system). You will find that most of the basic features are only adequately documented in Microsoft's SDK and that most Windows "cookbooks" treat the subject tangentially, if at all (Petzold's book, Windows Programming 3.1, is an example). For supplementary information or for information on subjects we haven't covered here (such as including bitmapped images, using child windows inside help topics, and dynamically updating them at runtime, etc.) consult the source listed in the Bibliography.
Process
The steps required to enable your application to use the help engine are:
Your program will access this .HLP file by making a call to the windows api function WinHelp, as shown in the sample program, helpdemo.c (Listing 1. )
- Create a help topic file with the .RTF (Rich Text Format) extension. This file will contain special commands or characters, and although it is recommended that you use a word processor capable of producing the special RTF characters, such as Microsoft Word, the truth is that any ASCII editor will do.
- Create a project file to control the compiler's operation. This file, with the extension of .HPJ, is a normal ASCII file that tells the help compiler how to build the. .HLP file.
- Compile the .RTF file into a binary (.HLP) file that winhelp.exe will access. (This binary file is in a proprietary format, and you should be aware that the format changed between windows version 3.0 and 3.1.) Most MS-Windows development systems include the help compiler, hc.exe for 3.0 or hc31.exe for 3.1, under license from Microsoft.
The .HPJ File
The .HPJ file is essentially a project file that is supplied to the help compiler tool hc.exe (or hc31.exe for Windows 3.1). This file consists of nine distinct sections, but most of these are optional. For this article, our discussion is limited to the three most useful sections: OPTIONS, FILES, and MAP. Each of these tokens must be enclosed in square brackets.Strictly speaking, the OPTIONS section is also optional, but its use is highly recommended. If used, it must be the first entry in the .HPJ file (see Listing 5) . The following are recommended entries in the [OPTIONS] section:
In the next major section, the MAP, help topics are defined and given a unique numerical value. It is best to place these in a header file, and include it in both the [MAP] section and the source code for your Windows application. By allowing one file to service both the help side and the application side of your project, you can greatly simplify maintenance requirements. See Listing 4 for examples of #define help topics.
- TITLE — A brief description of the associated application
- COMPRESS — This option determines if the .HLP file will be stored in compressed form. While developing, you should leave this as FALSE to save time; set to TRUE for your final build.
- WARNING — Level of error reporting, 1-3 (1 is least, 3 is most). Set to 3 during development.
- CONTENTS — This is the string token for the help file's "table of contents"; again, its use is highly recommended. If it is omitted, the first topic found in the .RTF file is assumed to be the table of contents.
In the last section, FILES, you direct the help compiler to find the actual help material, the .RTF file. While our example only has one .RTF file, you can have more than one; in fact, for large projects, you may wish to divide your help files into logical categories and give each its own .RTF file.
You may insert comments in your .HPJ file by prefacing them with a semicolon.
The .RTF File
The .RTF file is where the work begins. You can use any of a considerable number of text-formatting tokens; for the sake of simplicity, the sample program, helpdemo.rtf (Listing 6) is restricted to just the basics. Still, these are quite powerful, and will allow you to select fonts and specify their colors and sizes, to underline, to use bold typeface, and to perform other utilitarian functions. Like the .HPJ file, the .RTF file consists of logical units, as follows:
The entire .RTF file must be enclosed in the traditional C curly braces { }. The first token in the file must be \rtf1 followed by the name of the character set to use and the default font. The default font must be one of the stock fonts shipped with Windows. This allows Windows to make a graceful substitution if you've specified a font that can't be found on the target platform. The character set is generally set to ANSI. So, the first line of the .RTF file is usually:
- The font table, which describes which fonts are to be used
- The color table, which defines the colors that are available
- The table of contents, if specified in the .HPJ file
- The text associated with each help topic defined in the MAP section of the .HPJ file or in the header file.
{\rtf1\ansi\deff0}where f0 is defined in the font table. Listing 6 contains the .RTF file for the sample program; if you examine the font table found there, you'll see that each font is defined as follows:
{\fontnumber \fontsize font name}Hence, the entry that defines "font zero" might look like this:
{\f0\fs12 Courier}This declares f0 to be 12-point Courier.The color table which is defined next, is also delimited by braces, and is declared with the token:
\colortbl;Each color value is defined by the Windows RGB macro (Red, Green, Blue), which allows you to set colors by assigning each color a value between 0 and 255, and delimiting each color value a backslash. Each color definition in the table is terminated with a semicolon. (See Table 1 for some examples of typical color values.)To specify a color table containing only the colors black and red, your .RTF entry would look like this:
{\colortbl;\red0\green0\blue0; \red255\green0\blue0;}Referencing the colors is similar to indexing an array, with one caveat. The first color in the table is assigned the number 1, not 0, which most C programmers would expect. The process of selecting a color for display may best be explained via an example. Given the following statement
{\f0\fs22\cf2 Write this line in RED using the above color table.}WinHelp would display "Write this line in RED using the above color table." using 22-point Courier font, in red. The key here is the \cf2 token. As a mnemonic, it may be helpful to think of \cf as "Color Font."The last significant components of the .RTF file are the tokens for declaring the content topics and the content text. The "label" of a context string is defined by a "#" concatenated with the string assigned in the [MAP] section or header file. This is how WinHelp does a "go to" when you select a topic or click on a hypertext word from inside Help. A topic begins with a \footnote token and ends with a \page token. Everything between these tokens comprises the topic, including the caption, browse sequences, and search keywords. Within WinHelp, there is a button labeled "Search." When pressed, it brings up a dialog box that allows you to search for topics. These topics are identified with the letter K in the \footnote token. There is a special case when the search word also begins with the letter "K" — you must insert an extra space between the \footnote and the search word.
Topic captions (or titles) are identified with the character $ and the \footnote token. These strings are displayed when you select Search or History from WinHelp. The .RTF file in Listing 6 shows how these are actually implemented.
The text associated with a topic is delimited with the \footnote statement and the \page token. You can also create hypertext links inside your topic text by using the \uldb token (also demonstrated in the sample program). Hypertext words should be displayed in a contrasting, consistent color. They usually follow some descriptive text such as "See also:", etc.
A closing word about formatting the text itself: use the token \par to insert a blank line, \tab to insert a tab character, and use \b to display something in bold typeface. Since so much of the Help Compiler's operations is undocumented, you can probably learn best by experimenting with these command tokens.
Summary
Incorporating Windows help gives your application an extra level of professionalism that is easy to implement and maintain. In addition, since WinHelp functionality is consistent across all Windows applications, including it gives the user a greater level of confidence in your application. Further questions on advanced and undocumented topics may be referred to the authors.
Bibliography
Conger, James L. The Windows API Bible. The Waite Group.Mischel, Jim. "A Guide to Windows Help." PC Techniques. Feb/Mar 1993.
Microsoft Corp. The Windows Interface: An Application Design Guide. Redmond, WA: Microsoft Press.
Sidebar: "The WinHelp API Call"