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.
Folding@home is a project from the Standford University. Your help would be appreciated. And it's free!
http://www.stanford.edu/group/pandegroup/folding/
What does Folding@Home do?: Folding@Home is a distributed computing project which studies protein folding, misfolding, aggregation, and related diseases. We use novel computational methods and large scale distributed computing, to simulate timescales thousands to millions of times longer than previously achieved. This has allowed us to simulate folding for the first time, and to now direct our approach to examine folding related disease.
How can you help?: You can help our project by downloading and running our client software. Our algorithms are designed such that for every computer that joins the project, we get a commensurate increase in simulation speed.
Who "owns" the results? What will happen to them?: Unlike other distributed computing projects, Folding@home is run by an academic institution (specifically the Pande Group, at Stanford University's Chemistry Department), which is a nonprofit institution dedicated to science research and education.
We will not sell the data or make any money off of it. Moreover, we will make the data available for others to use.In particular, the results from Folding@home will be made available on several levels. Most importantly, analysis of the simulations will be submitted to scientific journals for publication, and these journal articles will be posted on the web page after publication. Next, after publication of these scientific articles, the raw data of the folding runs will be available for everyone.