A Help Command Processing Example—EX21B

EX21B is based on example EX20D from Chapter 20. It's a two-view MDI application with view-specific help added. Each of the two view classes has an OnCommandHelp message handler to process F1 help requests and an OnHelpHitTest message handler to process Shift-F1 help requests.

Header Requirements

The compiler recognizes help-specific identifiers only if the following #include statement is present:

#include <afxpriv.h>

In EX21B, the statement is in the StdAfx.h file.

CStringView

The modified string view in StringView.h needs message map function prototypes for both F1 help and Shift-F1 help, as shown here:

afx_msg LRESULT OnCommandHelp(WPARAM wParam, LPARAM lParam);
afx_msg LRESULT OnHelpHitTest(WPARAM wParam, LPARAM lParam);

Here are the message map entries in StringView.cpp:

ON_MESSAGE(WM_COMMANDHELP, OnCommandHelp)
ON_MESSAGE(WM_HELPHITTEST, OnHelpHitTest)

The OnCommandHelp message handler member function in StringView.cpp processes F1 help requests. It responds to the message sent from the MDI main frame and displays the help topic for the string view window, as shown here:

LRESULT CStringView::OnCommandHelp(WPARAM wParam, LPARAM lParam)
{
    if (lParam == 0) { // context not already determined
        lParam = HID_BASE_RESOURCE + IDR_STRINGVIEW;
    }
    AfxGetApp()->WinHelp(lParam);
    return TRUE;
}

Finally the OnHelpHitTest member function handles Shift-F1 help, as shown here:

LRESULT CStringView::OnHelpHitTest(WPARAM wParam, LPARAM lParam)
{
    return HID_BASE_RESOURCE + IDR_STRINGVIEW;
}

In a more complex application, you might want OnHelpHitTest to set the help context ID based on the mouse cursor position.

CHexView

The CHexView class processes help requests the same way as the CStringView class does. Following is the necessary header code in HexView.h:

afx_msg LRESULT OnCommandHelp(WPARAM wParam, LPARAM lParam);
afx_msg LRESULT OnHelpHitTest(WPARAM wParam, LPARAM lParam);

Here are the message map entries in HexView.cpp:

ON_MESSAGE(WM_COMMANDHELP, OnCommandHelp)
ON_MESSAGE(WM_HELPHITTEST, OnHelpHitTest)

And here is the implementation code in HexView.cpp:

LRESULT CHexView::OnCommandHelp(WPARAM wParam, LPARAM lParam)
{
    if (lParam == 0) { // context not already determined
        lParam = HID_BASE_RESOURCE + IDR_HEXVIEW;
    }
    AfxGetApp()->WinHelp(lParam);
    return TRUE;
}

LRESULT CHexView::OnHelpHitTest(WPARAM wParam, LPARAM lParam)
{
    return HID_BASE_RESOURCE + IDR_HEXVIEW;
}

Two new symbols were added to the project's Resource.h file. Their values and corresponding help context IDs are shown here.

Symbol	Value	Help Context ID	Value
IDR_STRINGVIEW	101	HIDR_STRINGVIEW	0x20065
IDR_HEXVIEW	102	HIDR_HEXVIEW	0x20066

Help File Requirements

Two topics were added to the AfxCore.rtf file with the help context IDs HIDR_STRINGVIEW and HIDR_HEXVIEW, as shown here.

The generated ex21b.hm file, in the project's \hlp subdirectory, should look like this:

// MAKEHELP.BAT generated Help Map file.  Used by EX21B.HPJ.

// Commands (ID_* and IDM_*)
HID_WINDOW_NEW_STRING                   0x18003
HID_WINDOW_NEW_HEX                      0x18005

// Prompts (IDP_*)


// Resources (IDR_*)
HIDR_STRINGVIEW                         0x20065
HIDR_HEXVIEW                            0x20066
HIDR_MAINFRAME                          0x20080
HIDR_EX21BTYPE                          0x20081

// Dialogs (IDD_*)
HIDD_ABOUTBOX                           0x20064

// Frame Controls (IDW_*)

Open a string child window and a hexadecimal child window. Test the action of F1 help and Shift-F1 help within those windows. If the help file didn't compile correctly, follow the instructions in step 1 of the help example in "A Help Example—No Programming Required."