SAMPLE: Context Sensitive Help in a CDialog

The information in this sample applies to:

• The Microsoft Foundation Classes (MFC) included with:

      - Microsoft Visual C++ for Windows, versions 1.0 and 1.5
  

SUMMARY

The DLGHLP sample illustrates implementing context sensitive help in a CDialog object.

DLGHLP.EXE can be downloaded as a self-extracting file from the Microsoft Software Library (MSL) on the following services:

• Microsoft Download Service (MSDL)

        Dial (206) 936-6735 to connect to MSDL
        Download DLGHLP.EXE (size: 100484 bytes) 
  

• Internet (anonymous FTP)

        ftp ftp.microsoft.com
        Change to the \softlib\mslfiles directory
        Get DLGHLP.EXE (size: 100484 bytes) 
  

MORE INFORMATION

The DLGHLP sample implements context sensitive help in a dialog box by overriding CWnd::OnCommandHelp in the dialog class to handle the WM_COMMANDHELP message. WM_COMMANDHELP is a private AFX Windows message that is received by the active window when Help is requested. DLGHLP uses the ID of the currently active control to generate the help context, which is passed on to the CWinApp::WinHelp member.

DLGHLP includes two dialog boxes, each with a number of controls in them. The user is able to set the focus to a particular control and, by pressing F1, bring up help that is specific to that control. Several of the control IDs are used in both dialog boxes. For example, each dialog box contains a radio button control with the ID of IDC_RADIO1. To allow a unique help context value to be generated for each control, the ID of each dialog box is used as a base and is added to the ID of the control.

For example, Dialog Box 1 has an ID of IDD_DIALOGBOX1 and Dialog Box 2 has an ID of IDD_DIALOGBOX2, both of which are defined in the header file RESOURCE.H. IDD_DIALOGBOX1 and IDD_DIALOGBOX2 have been made to differ in value by enough that adding the individual control IDs to them does not generate any overlapping help context values. In this case IDD_DIALOGBOX1 has a value of 101 and IDD_DIALOGBOX2 has a value of 131. Because IDC_RADIO1 has a value of 101, adding IDC_RADIO1 to each of the dialog box IDs gives unique help context values of 202 and 232.

A base value of 0x20000 is also added to the help context value to cause the context value for each control to be in the range of 0x20000 to 0x2FFFF, the help context range for windows and dialog boxes. For more information on help context ranges and context sensitive help in MFC, refer to MFC Technical Note 28: Context-Sensitive Help Support.

DLGHLP illustrates mixing context sensitive help and default help in the same dialog box. Pressing the F1 key when any of the radio buttons in Dialog Box 2 has the focus causes the context sensitive help for the radio button to be used. Pressing F1 when either the OK or Cancel button has the focus causes the default application help index to be invoked. Dialog Box 1 provides context sensitive help for all controls, including the OK and Cancel buttons.

DLGHLP is based on an AppWizard generated application. Files included with the sample, which are directly related to implementing context sensitive help in a dialog box, are:

   DLGBOX1.CPP -
   Implements context sensitive help for Dialog Box 1 by overriding
   CWnd::OnCommandHelp.

   DLGBOX2.CPP -
   Implements context sensitive help for Dialog Box 2 by overriding
   CWnd::OnCommandHelp.

   DLGRES.H -
   Defines the help context IDs based on the ID of the dialog box
   and the specific control.

   DLGCTRLS.HM -
   Help map file that defines the help context IDs for the dialog box
   controls.