Using the HTML Help control to display contextual help

• Download demo project - 23 Kb
• Download source - 3 Kb

Introduction

This article explains how to use HTML Help to display contextual help on dialog controls. To do so, HTML Help Workshop will be required. The version 1.3 of the Workshop may be downloaded at download.microsoft.com

The basics

What is contextual help?

Contextual help is help relative to a specific graphical element, like dialog box controls, and is generally displayed through a tool tip. The functionality is activated either by pressing Shift-F1 on the active control, or, if available, using the "?" button on the dialog box and then using the mouse cursor to select the control to explain. Contextual help adds a real value to the product by giving user-oriented information.

What can HTML Help do for us?

To implement contextual help, HTML Help provides us an interesting functionality: it may display a text in a tooltip. Moreover, the ActiveX is able to manage an association between a text and a numerical value inside a compiled-HTML file, or CHM. We will use this numerical value as an identifier for the text to display.

To display a tooltip, the HTML Help API provides the function below:

HWND WINAPI HtmlHelp(HWND hwndCaller, LPCTSTR pszFile, UINT uCommand, 
                     DWORD_PTR dwData)

where:

hwndCaller is the HWND of calling window

pszFile is the CHM file name

uCommand is equal to HH_DISPLAY_TEXT_POPUP

dwData is the address of a HH_POPUP structure we will use to give the ActiveX the parameters it needs to display the text we want.

The concept

We use this API to call a description text associated with the controls of our dialog boxes. The trick is the following: we determine a unique identifier for each control on the dialog boxes. With this identifier we associate a string describing the control. Knowing the control, the application is able to get the identifier, and asks to HTML Help to display the corresponding data. Easy, isn't it?

To build the identifier, we make the assumption that controls and dialogs use 16-bit identifiers. It's probably not always true, but with some attention in graphic design it may be. Knowing that the ID of a control is unique through a specific dialog box, and a dialog box identifier is unique through the application, we combine the two identifiers on a 32-bits unique one using the macro MAKELPARAM, specifying as the control as the dialog box.

The application

The application implements contextual help by using the class CContextDialog as base class for its dialogs. A dialog object is responsible for the initialization of its base class, by setting with the method CContextDialog::SetChmFile(LPCTSTR lpszChmName) the CHM file name to use. The object does this in the method OnInitDialog of its derived class. The CContextDialog base class intercepts the messages WM_HELP and WM_HELP_INFO, builds the identifier for the caller control and calls HtmlHelp. The CContextDialog base class also whether or not to display the contextual help button in the dialog box title bar according to the presence or not of the CHM file.

The HTML Help project

The HTML Help project is basically composed of three files:

• The project file, with the extension HHP.
• The text file, generally named cshelp.txt, because it's the default name used by HTML Help, so we won't have to manage this parameter later
• The index file, generally named cshelp.h for the same reasons.

It is possible to automate the build of the index file and a template for the text file with a console application taking as parameters the resource files (resource.rc and resource.h) of the graphic application and parsing them.

Conclusion

Using this technique, implementing contextual help becomes a simple task. The main advantages are little modifications to the source code, a separation of the help text and the application, easing the localization process, and the use of standard Windows components. The main disadvantage is the synchronization of the resources of the application and the HTML Help project, for example when updating.