Adding Context Sensitive Help to Dialogs

Date: 6 January 1997
Author: Christopher Kohlhoff

To provide the functionality for the ? button in your dialogs, OWL provides several macros. To incorporate them, just follow the steps below. You can download the example project from here.

Steps

Derive Your Application From THelpManager

First, change your application class to be like:

#include <owl/hlpmanag.h>

class THelpApp : public TApplication,
                 public THelpFileManager
{
  // ...
};

then change your application constructor to:

THelpApp::THelpApp()
: TApplication("Context Help Example Application"),
  THelpFileManager(".\\helpdlg.hlp")
{
}

and finally, add THelpFileManager to your application's response table: 

DEFINE_RESPONSE_TABLE2(THelpApp, TApplication, THelpFileManager)
  // ...
END_RESPONSE_TABLE;

You may also want to override the ActivateHelp function if you want the context-sensitive help to appear in a popup window rather than the normal frame:

void THelpApp::ActivateHelp(TWindow*, int contextId)
{
  GetMainWindow()->WinHelp(GetHelpFile().c_str(),
                           HELP_CONTEXTPOPUP, contextId);
}

Add Help Context Macros To Your Dialog

The help context macros are similar in structure to the familiar response table macros. Firstly, you add its declaration to your dialog class:

class THelpDialog : public TDialog
{
  // ...
  DECLARE_HELPCONTEXT(THelpDialog);
};

Secondly you add the macros to create and delete the help context for your dialog to its constructor and destructor:

THelpDialog::THelpDialog(TWindow* parent)
: TDialog(parent, IDD_CONTEXTHELP)
{
  SETUP_HELPCONTEXT(THelpApp, THelpDialog);
}

THelpDialog::~THelpDialog()
{
  Destroy(IDCANCEL);
  CLEANUP_HELPCONTEXT(THelpApp, THelpDialog);
}

Finally, you add the help context macros to associate a context with the controls on your dialog:

DEFINE_HELPCONTEXT(THelpDialog)
  // HCENTRY_CONTROL(HELP_CONTEXT, CONTROL_ID)
  HCENTRY_CONTROL(IDH_OKBUTTON,     IDOK),
  HCENTRY_CONTROL(IDH_CANCELBUTTON, IDCANCEL),
  HCENTRY_CONTROL(IDH_EDITBOX,      IDC_EDIT),
  HCENTRY_CONTROL(IDH_LISTBOX,      IDC_LISTBOX),
END_HELPCONTEXT;

That's it!

Note: context help entries defined in dialog base classes can be overridden in any subclasses. However, in the derived classes you must call the SETUP_HELPCONTEXT and the CLEANUP_CONTEXT macros. (Thanks to Mark Caroli.)