SAMPLE: Context Sensitive Help in a CDialog

ID: Q110506

The information in this article applies to:

The Microsoft Foundation Classes (MFC), included with:
- Microsoft Visual C++ for Windows, 16-bit edition, versions 1.0, 1.5

SUMMARY

The DLGHLP sample illustrates how to implement context sensitive help in a CDialog object.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

DLGHLP.EXE

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

DLGHLP.EXE was archived as a self-extracting file using the PKware file- compression utility. The archived file contains subdirectories, and therefore, the -d switch needs to be used when decompressing the file to disk.

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.

Additional query words: MfcUI kbfile


Keywords          : kbfile kbsample kb16bitonly kbMFC KbUIDesign kbVC kbVC100 kbVC150 
Version           : 1.00 1.50
Platform          : WINDOWS 
Issue type        :

Last Reviewed: August 8, 1999