Help Command Processing

You've seen the components of a help file, and you've seen the effects of F1 and Shift-F1. You know how the application element IDs are linked to help context IDs. What you haven't seen is the application framework's internal processing of the help requests. Why should you be concerned? Suppose you want to provide help on a specific view window instead of a frame window. What if you need help topics linked to specific graphics items in a view window? These and other needs can be met by mapping the appropriate help messages in the view class.

Help command processing depends on whether the help request was an F1 request or a Shift-F1 request. The processing of each help request will be described separately.

F1 Processing

The F1 key is normally handled by a keyboard accelerator entry that AppWizard inserts in the RC file. The accelerator associates the F1 key with an ID_HELP command that is sent to the OnHelp member function in the CFrameWnd class.

In an active modal dialog or a menu selection in progress, the F1 key is processed by a Windows hook that causes the same OnHelp function to be called. The F1 accelerator key would otherwise be disabled.

The CFrameWnd::OnHelp function sends an MFC-defined WM_COMMANDHELP message to the innermost window, which is usually the view. If your view class does not map this message or if the handler returns FALSE, the framework routes the message to the next outer window, which is either the MDI child frame or the main frame. If you have not mapped WM_COMMANDHELP in your derived frame window classes, the message is processed in the MFC CFrameWnd class, which displays help for the symbol that AppWizard generates for your application or document type.

If you map the WM_COMMANDHELP message in a derived class, your handler must call CWinApp::WinHelp with the proper context ID as a parameter.

For any application, AppWizard adds the symbol IDR_MAINFRAME to your project and the HM file defines the help context ID HIDR_MAINFRAME, which is aliased to main_index in the HPJ file. The standard AfxCore.rtf file associates the main index with this context ID.

For an MDI application named SAMPLE, for example, AppWizard also adds the symbol IDR_SAMPLETYPE to your project and the HM file defines the help context ID HIDR_SAMPLETYPE, which is aliased to HIDR_DOC1TYPE in the HPJ file. The standard AfxCore.rtf file associates the topic "Modifying the Document" with this context ID.

Shift-F1 Processing

When the user presses Shift-F1 or clicks the Context Help toolbar button, a command message is sent to the CFrameWnd function OnContextHelp. When the user presses the mouse button again after positioning the mouse cursor, an MFC-defined WM_HELPHITTEST message is sent to the innermost window where the mouse click is detected. From that point on, the routing of this message is identical to that for the WM_COMMANDHELP message, described previously in "F1 Processing".

The lParam parameter of OnHelpHitTest contains the mouse coordinates in device units, relative to the upper-left corner of the window's client area. The y value is in the high-order half; the x value is in the low-order half. You can use these coordinates to set the help context ID specifically for an item in the view. Your OnHelpHitTest handler should return the correct context ID; the framework will call WinHelp.