HTML Help - Creating What's This Help
Created: 9-Aug-02003, by Rob Chandler, MS Help MVP
What's This Help (also know as application popup help) is the field level popup help that appears when the F1 key is pressed. Applications also provide popup help via a [?] button in the title bar. This document discusses how to create What's This help.
Field level help can be very costly to write and maintain.
The help author must write separate help for every control in the application, and the developer must assign a unique Integer ID for every control requiring help. The evaluation effort can be enormous for large applications given that every help link must be tested.
These days most companies provide page or dialog level help. Pressing F1 or clicking the Help button displays a help window containing help for the current page or dialog. But there are still many popular applications (such as MS Office) which still provide field level popup help.
Consider also that What's This help may not suite all applications. Focusing all help assistance on a particular field may not be appropriate.
That said lets now continue with Creating What's This Help for MS HTML Help.
In the beginning there was WinHelp providing excellent rich popups. In the early days of HTML Help the humble HH popup was fairly lame, and even Microsoft themselves continued to use WinHelp popups for sometime. Mixing WinHelp rich popups with HTML Help is still an option, however I hope you will be convinced otherwise shortly.
HTML Help (introduced in 1997 with IE4) initially provides a fairly lame text popup, again read from the help file. A later release (HH Version 1.2?) also allowed you to provide text directly or from a resource string, as well as the ability to set the popup's color and margins. HH popups are plain text only.
KeyHelp is a free ActiveX control from Keyworks.net and providing beautiful rich HTML popups. KeyHelp was developed by Ralph Walden and Cheryl Lockett Zubak. Ralph is x-Microsoft and was heavily involved in the development of WinHelp and HTML Help during his many years at Microsoft. This is the best choice for displaying rich popups.
IKeyPopup::DisplayMapID(1500, 'c:\test\mytest.chm', X, Y);
IKeyPopup::DisplayURL('c:\test\mytest.chm::/index.htm', P.X, P.Y);
Here is a snippet of Delphi code. Other languages will be similar.
Here is some sample script taken from KeyScript.js which comes with the KeyHelp download (you may need to decompile the CHM file to get it).
There are two HH API popup commands, both can display text stored in a CHM help file. This section provides an example of how to define popup text in a .CHM help file.
First create a text file called cshelp.txt:
You can write the context ID number directly into the text file as seen above with Topic 99. Or you can define identifiers in a separate C++ header file as done with the other 2 declarations.
Lastly we need to add the following lines to our help project (.hhp) file and compile it to a CHM file.
Notice I also added cshelp.h and cshelp.txt to the [FILES] section to ensure that the files are definitely compiled into the target .CHM help file.
The HTML Help API provides the application with two popup commands:
Documentation for the HH API calls, including C++ code, can be found in the HTML Help Workshop online help. Examples below are written in Delphi.
We pass an array of DWords containing control handle and topic ID pairs, terminated by two trailing zeros. The API call HtmlHelp() specifies the handle of the control that you are requesting help for, and the path to the popup text definition file (see previous section). The API will look up the relevant popup text in the CHM file using the popup ID, and display the popup over the control.
The HH_DISPLAY_TEXT_POPUP command offers more flexibility. You can set the popup color and popup margins. The popup text can be specified in three different ways: as an explicit text string, as resource string ID and as a popup ID representing a popup defined in a .CHM help file (see previous section).
We simply fill in a THHPopup structure and make the call.
Displaying a popup using supplied text:
In the HH_ShowPopupHelp1() example above, function parameter aParent is the form that will parent the popup, Text is the text string to display and XYPos holds the x-y coordinates for the popup.
Displaying a popup using a string resource ID:
To display a text string based on a resource ID (above) we simply assign hinst=hInstance and idString=resID. For more information on how to store resource strings in an application see your compiler's manual.
Displaying a popup using text defined in a .CHM file:
Finally the third and last example (above) tells the API to grab the popup text defined in a chm. This is much the same as the HH_TP_HELP_CONTEXTMENU example. Notice the second parameter is now defined as the path to the topic text file in the chm.
Just to wrap up the HH_DISPLAY_TEXT_POPUP popup discussion. The color parameters are either –1 for the default color or an RGB value. The easiest way is to specify a color is to use a three byte hexadecimal number where each byte represents a Blue, a Green and a Red value, $00BBGGRR.
The pszFont parameter allows you to specify a font. Use an empty string for the default font or specify ‘facename, point size, char set, BOLD ITALIC UNDERLINE’. You can leave a parameter blank to specify that the default value should be used.
Most applications will also require a “What’s This” toolbar button and help menu item.
In Delphi we need to enable the "What's This" Help_ContextPopup messages (these appear in the OnHelp event) by setting the form property BorderIcons := BorderIcons + [biHelp]; Do this in the FormCreate() or Object Inspector. Note that the What's This button in the title bar will not show if you have a minimize or maximize button. But you can make a toolbar button or menu item behave like a What's This button.
To accomplish this, call the following code. Here is my “What’s This” toolbar button click event code.
Where handle is the current windows handle.
Note: Each Delphi window needs BorderIcons := BorderIcons + [biHelp] if you want the OnHelp event to correctly catch the What's this help event. For Delphi 6 and above OnHelp events do not fire correctly unless you have our free OnHelpFix Unit.
MS HTML Help >