Click here to Skip to main content
Click here to Skip to main content

Using the HTML Help control to display contextual help

, 17 Feb 2003
Rate this:
Please Sign up or sign in to vote.
This article explains how to implement contextual help display using HTML Help

Sample Image

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.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Share

About the Author

KaЯl
Team Leader
France France



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.

Comments and Discussions

 
GeneralParsing application available Pinmemberduronebis7-Jun-06 10:54 
Questionnot everything works Pinmembermarcogja21-May-06 13:53 
AnswerRe: not everything works PinmemberK(arl)21-May-06 22:15 
QuestionHow to build The HTML Help project? PinmemberNo-Cloud-Dagon23-Feb-05 3:34 
AnswerRe: How to build The HTML Help project? PinmemberK(arl)23-Feb-05 4:22 
GeneralRe: How to build The HTML Help project? PinmemberNo-Cloud-Dagon23-Feb-05 13:19 
GeneralRe: How to build The HTML Help project? PinmemberK(arl)8-Mar-05 5:37 
Generalhelp me! what is the exact problem PinmemberNo-Cloud-Dagon23-Feb-05 3:10 
Questionhelp! what is wrong with error? PinmemberNo-Cloud-Dagon21-Feb-05 16:27 
AnswerRe: help! what is wrong with error? PinmemberK(arl)21-Feb-05 20:22 
GeneralHTML file in htmlhelp PinsussAnonymous30-Jul-03 11:52 
Generalerror compling this example Pinmember""26-Feb-03 5:56 
GeneralRe: error compling this example PinmemberKaЯl26-Feb-03 6:36 
GeneralRe: error compling this example Pinmember""26-Feb-03 8:18 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140827.1 | Last Updated 18 Feb 2003
Article Copyright 2003 by KaЯl
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid