Displaying Context-Sensitive Help

Context-sensitive help, for the purpose of this discussion, refers to help support for the controls in a dialog box that users access with:

• The F1 key.

• By right-clicking a control (What's This? Help).

• By using the question-mark pointer (the What's This? Help pointer).

Context-sensitive help also refers to accessing the help viewer via a command button or menu option.

To implement help for a dialog-box control, you must first create a text file that you include in your HTML Help project and then create a two-dimensional array. Then, you can implement code that supports F1, right-click, or question-mark-pointer access to text in the help file.

The source information for context-sensitive help is stored in a .txt file that you include in your HTML Help project.

To create the context-sensitive help text file

1. Use a text editor to create a .txt file.

2. Format the topics as follows:

   .topic 1
   help text for control 1
   .topic 2
   help text for control 2
   

Note   For more information, see "Designing context-sensitive help" in HTML Help's online help. From the Help menu (in HTML Help Workshop), choose Help Topics.

To support help for resources in a dialog box, you must create a two-dimensional array that maps control IDs to help IDs (topic numbers).

To create the two-dimensional array

• In the .cpp file, for every class that represents a dialog box, add a two-dimensional array to the end of the class. For example:

  static DWORD myarray[] = {
  IDC_CHECK1, 1,
  IDC_CHECK2, 2,
  IDC_CHECK3, -1,
  0,0
  };
  

Each entry in the two-dimensional array pairs a resource ID for a dialog-box control with a topic number from the context-sensitive help text file. If you do not want a specific resource to have What's This? Help, use –1. The last pair in this array should be 0,0.

What's This? Help displays the control's help when a user right-clicks the control.

To implement right-click What's This? Help

• Implement a handler for the WM_CONTEXTMENU message (in each dialog-box class where you want What's This? Help) and implement the following code for the handler:

  void CMyDialog::OnContextMenu(CWnd* pWnd, CPoint point)
  {
  HtmlHelp(
  pWnd->GetSafeHwnd(),
  "my_chm.chm::/ctrlhlp.txt",
  HH_TP_HELP_CONTEXTMENU,
  (DWORD)(LPVOID)myarray);
  }
  

F1 access to context-sensitive help means that users will be able to press F1 when a control has focus to access help.

To implement F1 access to context-sensitive help

• Implement a handler for the WM_HELPINFO message (in each dialog-box class where you want F1 access to context-sensitive help) and implement the following code for the handler:

  BOOL CMyDialog::OnHelpInfo(HELPINFO* pHelpInfo)
  {
  if (pHelpInfo->iContextType == HELPINFO_WINDOW)
  {
  return HtmlHelp(
  (HWND)pHelpInfo->hItemHandle,
  "my_chm.chm::/ctrlhlp.txt",
  HH_TP_HELP_WM_HELP,
  (DWORD)(LPVOID)myarray)
  != NULL;
  }
  return TRUE;
  }
  

If you already implement F1 access to context-sensitive help, you can easily enable the What's This? pointer, which causes a question mark to appear on the title bar, in the upper right-hand corner of the dialog box.

To enable the What's This? Help question-mark pointer

• Select the Context help check box in the Extended Styles tab of the dialog box properties.

Back to Help Topics (HTML Help)