Q149343: HOWTO: Implement Context-Sensitive Help for Dialog Controls

Article: Q149343
Product(s): Microsoft C Compiler
Version(s): winnt:4.0,4.1
Operating System(s): 
Keyword(s): kbCSHelp kbMFC kbVC400 kbGrpDSMFCATL
Last Modified: 30-JUL-2001

-------------------------------------------------------------------------------
The information in this article applies to:

- The Microsoft Foundation Classes (MFC), included with:
   - Microsoft Visual C++, 32-bit Editions, 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:

  Q141724 SAMPLE: Context-Sensitive Help in a CDialog Object

In the help project (.hpj) file include Resource.hm:

      [MAP]
      #include <resource.hm>

Sample Code
-----------

  BEGIN_MESSAGE_MAP(CMyDialog, CDialog)
      ON_WM_HELPINFO()
  END_MESSAGE_MAP()

  BOOL CMyDialog::OnHelpInfo(HELPINFO* pHelpInfo)
  {
      if (pHelpInfo->iContextType == HELPINFO_WINDOW)
      {
          AfxGetApp()->WinHelp( pHelpInfo->dwContextId,
                                HELP_CONTEXTPOPUP);
      }

      return TRUE;
  }

Additional query words: MfcHelp

======================================================================
Keywords          : kbCSHelp kbMFC kbVC400 kbGrpDSMFCATL 
Technology        : kbAudDeveloper kbMFC
Version           : winnt:4.0,4.1
Issue type        : kbhowto

=============================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.

Copyright Microsoft Corporation 1986-2002.