Help: The MakeHm Tool
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
| Predefined ID | Object |
| IDP_ | Message-box prompt |
| IDD_ | Dialog-box ID |
| ID_ | Toolbar or menu command (IDM_ is okay too) |
| IDR_ | Frame-related resources |
| IDW_ | Control bar |
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