Help: Message-Map Support

  • Article

|  Overview |  How Do I |  | 

AppWizard adds a new menu command to the two Help menus: Help Topics. Support for this command and for F1 and SHIFT+F1 help is provided through the message map. Topics covered in this article include:

  • Help commands in the message map

  • About the Help commands

  • Completing your application’s Help

Help Commands in the Message Map

To support the Help Topics menu item, F1 help, and SHIFT+F1 help, AppWizard adds four entries to the message map for your CFrameWnd-derived or CMDIFrameWnd-derived class. This message map is in the MainFrm.cpp file, and the relevant message map entries are located below the // Global help commands comment.

After you run AppWizard, click Context-Sensitive Help. The message map for class CMainFrame will look like the following for an MDI application:

// CMainFrame

BEGIN_MESSAGE_MAP(CMainFrame, CMDIFrameWnd)
   //{{AFX_MSG_MAP(CMainFrame)

   // NOTE - the ClassWizard will add and remove mapping macros here.
   //   DO NOT EDIT what you see in these blocks of generated code !
   ON_WM_CREATE()
   //}}AFX_MSG_MAP
   // Global help commands
   ON_COMMAND(ID_HELP_FINDER, CMDIFrameWnd::OnHelpFinder)
   ON_COMMAND(ID_HELP, CMDIFrameWnd::OnHelp)
   ON_COMMAND(ID_CONTEXT_HELP, CMDIFrameWnd::OnContextHelp)
   ON_COMMAND(ID_DEFAULT_HELP, CMDIFrameWnd::OnHelpFinder)
END_MESSAGE_MAP()

For an SDI application, references to CMDIFrameWnd in this code are replaced by references to CFrameWnd.

About the Help Commands

The four help-related message-map entries follow the // Global help commands comment. The following table explains the purpose of each command ID used in these entries.

Help-Related Command IDs

Command ID Purpose
ID_HELP_FINDER Responds to the Help Topics item on the Help menu by displaying the Windows Contents screen.
ID_HELP Responds to F1 by displaying a specific topic in Windows Help.
ID_CONTEXT_HELP Responds to SHIFT+F1 by putting the application into Help mode.
ID_DEFAULT_HELP Used when a specific help context cannot be found.

Notice that all of these commands are mapped to member functions of class CMDIFrameWnd (in the case of an MDI application), or to CFrameWnd (in the case of an SDI application). Unlike most of the other commands you place into the message map, these have handler functions that are predefined by the class library. Making the message-map entry enables the command.

The application’s accelerator table defines F1 for ID_HELP and SHIFT+F1 for ID_CONTEXT_HELP. You can change the keys used for these help functions by using Visual C++ to change the key values in the accelerator table.

When the user chooses a Help menu command (or uses one of the context-sensitive Help techniques described in F1 Help Support and SHIFT+F1 Help Support in the article Help: F1 and SHIFT+F1 Help), the framework calls the CWinApp::WinHelp member function. This action, in turn, starts the Windows Help program and passes context information to it.

Completing Your Application’s Help

Once you have used AppWizard to provide the generic help support, you can complete the help for your application by doing the following:

  1. Add application-specific user-interface elements.

    Use the integrated development environment to create your application’s dialog boxes, menus, and other resources.

  2. Write application-specific Help topics.

    Starting with the .RTF files supplied by AppWizard in your project’s HLP subdirectory, remove topics that don’t apply to your application, edit the remaining material, and add new topics for the menu commands, dialog boxes, toolbar buttons, and so on, that you added to your program. Each Help topic requires a help context ID. The help context is the same as the resource ID with an “H” added to the beginning. For example, if your application’s RESOURCE.H file contains the resource ID ID_PEN_WIDTHS, write a topic with the help-context ID HID_PEN_WIDTHS.

    This mapping between the resource ID and the help-context ID is established by the MakeHm tool. Note that the .RTF file refers the context ID as a string, while the application and the framework refer to the context ID as a number. The article Help: Authoring Help Topics describes the process of mapping these IDs to Help topics and writing the topics in your .RTF files.

  3. Compile Help. See Help: Compiling and Testing Your Help File.

See Also   Example Help Contexts