Help: The MakeHm Tool

|  Overview |  How Do I |  | 

This article describes the tools you use to map help context IDs in your application to Help topics in your Help file. Topics covered include:

• Help context IDs

• Preferred resource ID prefixes

• Example help contexts

• Running the tools

In Windows Help, a help context consists of a string and an ID number. The help context string is what the help text author uses to identify Help topics. The help context ID number is what the programmer associates with each resource. The context strings and ID numbers are mapped together in the [MAP] section of the .HPJ file. When your application calls Windows Help, Windows Help uses the context ID your application passes to locate and display the Help topic denoted by that context. At run time, the framework manages supplying the appropriate help context ID.

To facilitate relating the windows, dialog boxes, and commands in your application to Windows Help contexts, MFC provides the MakeHm.exe tool, which creates the information used in the [MAP] section of the .HPJ file.

AppWizard’s custom build rules on the RESOURCE.H file call MakeHm.exe and then calls the Windows Help Compiler. Makehelp.bat performed this function in prior versions of Visual C++.

Help Context IDs

When you use Visual C++ to create dialog-template resources, menu commands, and the like, Visual C++ writes #define statements in a file named RESOURCE.H. For example, there might be #define statements for such symbols as IDD_MY_DIALOG and ID_PEN_WIDTHS.

The following illustrates the resource IDs that Visual C++ creates in your RESOURCE.H file and the help context IDs that the MakeHm tool creates. IDs in RESOURCE.H like

#define IDD_MY_DIALOG   2000
#define ID_MY_COMMAND    150

would be translated by MakeHm into

HIDD_MY_DIALOG    0x207d0
HID_MY_COMMAND    0x10096

Dialog-box IDs are translated to values beginning at 0x20000. Command and resource IDs are translated to values beginning at 0x10000. That is, the framework reserves specific ranges of values for different kinds of objects. For details, see the custom build rule on the RESOURCE.H file and .

This format is compatible with the Help Compiler, which maps context IDs (the numbers on the right side) to context strings (the symbols on the left). Use these context strings in the .RTF Help files to identify topics.

For more information about how Visual C++ adds symbols to RESOURCE.H and how you can view and manipulate them with the Visual C++ Symbol Browser, see Browsing Through Symbols.

Preferred Resource ID Prefixes

To facilitate using MakeHm, observe the conventions in specifying IDs for your resource objects, as shown in the following table. It is important that different kinds of resource objects have different ID prefixes.

Preferred Resource ID Naming Conventions

For example, here’s a call to the MakeHm tool from a custom build rule:

makehm ID_,HID_,0x10000 IDM_,HIDM_,0x10000 resource.h >>"hlp\$(TargetName).hm"

Build rules expect dialog resources to be named with IDD_ prefixes. The corresponding help contexts will be named with HIDD_ prefixes.

Use the IDS_ prefix for normal string resources, and do not write Help topics for them. For string resources used in message boxes, use the IDP_ prefix and write Help topics for them so the user can get context-sensitive Help by pressing F1 while the message box is displayed.

Example Help Contexts

As your application grows, you’ll define a number of new IDs (symbols). For example, the following lists the RESOURCE.H file for the Scribble application after Step 6 of the tutorial:

//{{NO_DEPENDENCIES}}
// Visual C++ generated include file.
// Used by SCRIBBLE.RC
//
#define IDD_ABOUTBOX                   100
#define IDR_MAINFRAME                  128
#define IDR_SCRIBBTYPE                 129
#define IDD_PEN_WIDTHS                 131
#define IDC_THIN_PEN_WIDTH             1000
#define IDC_THICK_PEN_WIDTH            1001
#define IDC_DEFAULT_PEN_WIDTHS         1002
#define ID_PEN_THICK_OR_THIN           32771
#define ID_PEN_WIDTHS                  32772

Symbols defined for the Scribble tutorial include IDR_SCRIBBTYPE (Scribble’s menus and other application-specific resources), IDD_PEN_WIDTHS (a Pen Widths dialog box), ID_PEN_THICK_OR_THIN (a Thick Line command), and so on. Notice that one Scribble command, ID_EDIT_CLEAR_ALL, doesn’t appear in RESOURCE.H because it’s predefined ID in the class library. AppWizard will already have generated a Help topic for it in the .RTF files it created to get you started.

MakeHm maps these symbols to Windows Help contexts. The following excerpt from custom build rule shows a call to MakeHm:

makehm ID_,HID_,0x10000 IDM_,HIDM_,0x10000 resource.h >>"hlp\$(TargetName).hm"

After you run a custom build rule, an .HM file may look like the following:

// Commands (ID_* and IDM_*)
HID_PEN_THICK_OR_THIN         0x18003
HID_PEN_WIDTHS                0x18004

// Prompts (IDP_*)

// Resources (IDR_*)
HIDR_MAINFRAME                0x20080
HIDR_SCRIBBTYPE               0x20081

// Dialogs (IDD_*)
HIDD_ABOUTBOX                 0x20064
HIDD_PEN_WIDTHS               0x20083

// Frame Controls (IDW_*)

This file contains help contexts for two commands, two resources (menus and other application resources), and two dialog boxes.

Running the Tools

When the custom build rules detect a change in the RESOURCE.H file, they call the MakeHm tool to map the #define statements in RESOURCE.H to Windows Help strings in an .HM file. The MakeHm tool collects #define statements from RESOURCE.H and uses the command-line parameters passed to MakeHm to map defined symbols to help strings in a .HM file. For the example IDs in the previous paragraph, it would create help strings such as HIDD_MY_DIALOG and HID_PEN_WIDTHS. These context strings are formed by prefixing an “H” to the symbol found in RESOURCE.H. MakeHm also maps the ID’s numeric value to a corresponding number for the help context. An example is shown in Example Help Contexts.

The custom build rules will invoke the Windows Help Compiler (HCW.EXE) if the .HPJ file changes and HCW.EXE will uses the .HM files pointed to by the .HPJ file to set up the help contexts in your new Help file. Once you finish compiling your .HLP file, you can use it from your application.

See Also   Help: Authoring Help Topics