Adding Context Help

CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Environment: Visual C++ 5 & 6

This is an supplement to the article submitted by Joep
Oude Veldhuis. Please follow his description and instruction to install Microsoft HTML
Help 1.21 or read the story at Microsoft.

By adding context help to your application expand the use and enhance the user
experience. The context help can be recognized by the arrow cursor associated with the
question mark. Dialog boxes supporting this can be recognized by the ? icon in the upper
right-hand corner of the box. If the user have trouble understanding the function of some
of the control, the solution is to click the icon, move the cursor into the control of
question, and left-click the mouse. Alternative is for controls that have the input focus
without generating a command message (like edit controls), is simply pressing the F1 key
that has the same effect. A popup windows appears containing help text that you declared.
Adding context help using the HTML popup can be described in four steps:

1. Enable the context help for the dialog at the ‘Dialog Properties’ ‘Extended Styles’
   page.
2. Assign help text for the control in your ‘String Table’.
3. Trap the WM_HELPINFO message in the dialog box class.
4. CopyPaste the code below into your desired class

BEGIN_MESSAGE_MAP(CDlg, CDialog)
 ON_WM_HELPINFO()
END_MESSAGE_MAP()

It is important that the id used in your String Table is the same you named the
control, try use the combo box at the ‘String Properties’ dialog. The message handler for
the WM_HELPINFO message goes like this,

afx_msg BOOL OnHelpInfo(HELPINFO* pHelpInfo);

BOOL CDlg::OnHelpInfo(HELPINFO* pHelpInfo)
{
 // This method does all the work	
 ShowContextHelp(CWnd::FromHandle((HWND)pHelpInfo->hItemHandle),
  pHelpInfo->MousePos, pHelpInfo->iCtrlId);

 // We will proceed the message, so skip the base class
 // return CDialog::OnHelpInfo(pHelpInfo);
 return TRUE;
}

As mentioned in the comment, the ShowContextHelp(…) is the method that have our
attention. The method takes two arguments: a pointer to the window, and the POINT
structure where the help request occurred.

void CDlg::ShowContextHelp(CWnd* pWnd, POINT pt, int iCtrlID)
{
CString s;

 // Load help text from String Table
 if(s.LoadString(iCtrlID))
 {
  HH_POPUP hPop; // HTML Help popup structure

  // Initialize structure to NULLs	
  memset(&hPop, 0, sizeof(hPop));

  // Set size of structure
  hPop.cbStruct         = sizeof(hPop);

  // Yellow background color
  hPop.clrBackground    = RGB(255, 255, 208);

  hPop.clrForeground    = -1; // Font color	
  hPop.rcMargins.left   = -1;
  hPop.rcMargins.bottom = -1;
  hPop.rcMargins.right  = -1;
  hPop.pt               = pt;
  hPop.pszText          = s; // Message from String Table
  hPop.pszFont          = NULL; // Font

  HtmlHelp(pWnd->GetSafeHwnd(), NULL,
   HH_DISPLAY_TEXT_POPUP, (DWORD)&hPop);
 } // End if found a help string for this request
} // End ShowContextHelp(...)

The HH_POPUP structure is used to display the context help in a
popup window. The structure has members for setting the foreground/background colors, for
adjusting where the popup will be displayed, and for selecting the font to use. If you
skip the first parameter, be typing NULL, you will experience that the popup window
is acting like a modaless dialog, which was not the intention.

The second parameter for the HtmlHelp(…) method, point to a
file object where the string resource also could be placed.

Hope you will find it usefull.