How to Implement Context-Sensitive Help for Dialog Controls

The information in this article applies to:

• The Microsoft Foundation Classes (MFC) included with: Microsoft Visual C++, 32-bit Edition, versions 4.0, 4.1

SUMMARY

Context-Sensitive Help for dialog controls can be easily provided with the help of the resource editor. Using the resource editor eliminates the need to build a help ID array in memory.

MORE INFORMATION

The resource editor has the ability to automatically generate context help IDs for dialog controls. To start the process, double-click the control in the resource editor. This opens the control's property page. Select the Help ID check box in the general tab. Then save the resource. The resource editor then generates a file named Resource.hm, which contains help contexts and corresponding ID numbers in the form of #define.

To add the Context-Sensitive Help button to the dialog itself, bring up the properties for the dialog template. Click the Extended Styles tab, and select the Context Help check box.

The help context is generated by prepending an H to the control ID in Resource.h. The help context is what the help text author uses to identify Help topics in .rtf file. The help context ID number is what the programmer associates with each resource. The help context IDs are generated by adding 0x80000000 + (IDD_DIALOG << 16) to the control ID in Resource.h. The help contexts and ID numbers are mapped together in the [MAP] section of the .hpj file.

When your application calls WinHelp, the Windows Help engine uses the context ID your application passes to locate and display the Help topic denoted by that context. At run time, the framework manages the process of supplying the appropriate help context ID. These context help IDs are passed as the dwContextID member of the HELPINFO structure. To provide context help for the dialog control, handle the WM_HELP message for the dialog, and in the handler, call WinHelp with context help ID as the last parameter. Also include the Resource.hm file in the [MAP] section of the .hpj file.

How to Provide Context Help for Property Sheet or Win32s Application

When you add a help ID to any control on a dialog, the resource editor uses a DIALOGEX dialog template for the dialog. DIALOGEX templates are not supported for property sheets or on Win32s. To provide context help for a property sheet or Win32s application, see the DLGHLP32 sample in the following article in the Microsoft Knowledge Base:

   ARTICLE-ID: Q141724
   TITLE     : SAMPLE: Context-Sensitive Help in a CDialog Object

    [MAP]
    #include <resource.hm>

Sample Code

BEGIN_MESSAGE_MAP(CMyDialog, CDialog)

    ON_WM_HELPINFO()

BOOL CMyDialog::OnHelpInfo(HELPINFO* pHelpInfo) {

    if (pHelpInfo->iContextType == HELPINFO_WINDOW)
    {
        AfxGetApp()->WinHelp( pHelpInfo->dwContextId,
                              HELP_CONTEXTPOPUP);
    }

    return TRUE;