Choosing Help from the Help Menu

Every application should provide a Help menu to allow the user to open the Help file with either the mouse or the keyboard. The Help menu should contain at least one Contents menu item that, when chosen, displays the Contents or the main topic in the Help file. To support the Help menu, the application’s main window procedure should check for the Contents menu item and call the WinHelp function, as in the following example:

case WM_COMMAND:
        switch (wParam) {
        case IDM_HELP_CONTENTS:
               WinHelp(hwnd, "myhelp.hlp", HELP_CONTENTS, 0L);
               return 0L;
               .
               .
               .

        }
        break;

You can add other menu items to the Help menu for topics containing general information about the application. For example, if your Help file contains a topic that describes how to use the keyboard, you can place a Keyboard menu item on the Help menu. To support additional menu items, your application must specify either the context string or the context identifier for the corresponding topic when it calls the WinHelp function. The following example uses a Help macro to specify the context string IDM_HELP_KEYBOARD for the Keyboard topic:

case IDM_HELP_KEYBOARD:
         WinHelp(hwnd, "myhelp.hlp", HELP_COMMAND,
                          (DWORD)(LPSTR)"JumpID(\"myhelp.hlp\",\"IDM_HELP_KEYBOARD\")");
         return 0L;

A better way to display a topic is to use a context identifier. To do this, the Help file must assign a unique number to the corresponding context string, in the [MAP] section of the Help project file. For example, the following section assigns the number 101 to the context string IDM_HELP_KEYBOARD:

[MAP]
IDM_HELP_KEYBOARD      101

An application can display the Keyboard topic by specifying the context identifier in the call to the WinHelp function, as in the following example:

#define IDM_HELP_KEYBOARD   101
WinHelp(hwnd, "myhelp.hlp", HELP_CONTEXT, (DWORD)IDM_HELP_KEYBOARD);

To make maintenance of an application easier, most programmers place their defined constants (such as IDM_HELP_KEYBOARD in the previous example) in a single header file. As long as the names of the defined constants in the header file are identical to the context strings in the Help file, you can include the header file in the [MAP] section to assign context identifiers, as shown in the following example:

[MAP]
#include <myhelp.h>

If the defined constants in the header file are different from the context strings in the Help file, you can use Help Author to perform the context mapping.