How to create HTML Help using HTML Help Workshop (HHW)

Topic status automatically displays here - do not remove.

Bookmark me! Bookmark this topic Print me! Print this topic

The HTML Help Project file settings (.HHP)

The HTML Help Project file contains the information HHW uses to collate, create, compile and compress a Compiled HTML help Module (CHM) file.

The HTML Help Contents file settings (.HHC)

The HTML Help Contents file contains the information HHW uses to create and display a graphical tree hierarchical structured Table Of Contents (TOC) within an HTML Help Viewer.

TOC must be binary and must have the following settings applied.

xyz

The HTML Help K-link index file settings (.HHK)

The HTML Help Index file contains the information HHW uses to create and display an alphabetically structured index.

If you click on the Index tab in HHW, and you have not previously nominated an Index file for the project, HHW will prompt you to create a new one, or open (nominate) an existing one. Which ever you select, it will store the file name (and location) in the project file, accessible through the project properties dialog:

xyz

Check the "Include keywords from HTML files" checkbox. This retrieves and collates the index entries automatically from every HTML topic during the HTML Help compile, and adds them to the compiled help index.

Bug

Do not create duplicate primary index entries. If you have an HHK index file and also elect to use the HTMLHelp object embedded within individual topics as an index object, be very careful to check that you don't inadvertently create duplicate primary index entries. No compile errors will occur, however, a run-time error occurs when the HHK primary index entry is selected. It displays the index file as bullets in the html viewer topic window. Unfortunately, it requires the manual examination of the compiled help (before release) to identify this error. You must view the index, and select every primary entry to check if any produce this display error. Click on each one, and if the entry links to more than one topic, a popup list will display. Examine the list to ensure that no topics are labelled "Untitled".

Bug

If you have an HHK index file with primary links that point to themselves (to be a non jumping link), do not mix case between the entry and its destination. This causes no compile error, yet at runtime inhibits the display of the popup instruction to select one of the sub-entries.

HTML Help History and relationship to WinHelp

HTML Help Viewer

HTML Help Workshop (HHW)

HTML Help consists of the following tools:

HTML Help Workshop (Hhw.exe), a Help authoring tool with an easy-to-use graphical interface for creating Help project files, HTML topic files, contents files, index files, and everything else you need to put together a Help system or Help Web site.
The HTML Help ActiveX control (HHCtrl.ocx), for inserting features such as Help navigation and secondary window functionality into an HTML file.
The HTML Help JScript applet (HHCtrl.class and associated .class files), for inserting Help navigation and secondary window functionality into an HTML page when you want to use a JScript applet instead of an ActiveX control.
The Microsoft HTML Help Image Editor (Flash.exe), a tool for creating screenshots; converting, editing, and viewing image files; and browsing thumbnail images.
The HTML Help Authoring Guide, an online guide for using HTML Help Workshop and designing a Help system, plus a complete HtmlHelp API reference for developers and an HTML tag reference for authors.
The HTML Help Viewer program (Hh.exe), which displays and runs your Help system. Topics displayed in the HTML Help Viewer can use the HTML Help ActiveX control so that any navigational elements such as a table of contents, index, full-text search, or related topic jumps specified by the author will be part of the Help system.

Along with these tools, HTML Help provides two important features:

The ability to convert existing Windows Help files to HTML Help files.
The ability to compress your HTML files while compiling them into a single file. This feature greatly reduces the amount of disk space required for your HTML files and simplifies distribution. A compiled HTML Help file (.chm) plays the same role as a compiled Windows Help file (.hlp).

Many of the features available in HTML Help are implemented through the HTML Help ActiveX control (HHCtrl.ocx). The HTML Help ActiveX control is used to provide navigation features (such as a table of contents) to display secondary windows and pop-up definitions, and to provide other features. The HTML Help ActiveX control can be used from topics in a compiled Help system as well as from HTML pages displayed in a Web browser. The functionality provided by the HTML Help ActiveX control will run in the HTML Help Viewer or in any browser that supports ActiveX technology, such as Microsoft Internet Explorer (version 3.01 or later). Some features provided by the HTML Help ActiveX control are available only when it is used from a compiled HTML Help file (.chm) that is displayed by using the HTML Help Viewer.

The most commonly used features supported by the HTML Help ActiveX control are:

Table of contents (displayed in a tree control)
Index
Secondary windows (available only from a .chm file displayed in the HTML Help Viewer)
The ability to size and position windows (available only from a .chm file displayed in the HTML Help Viewer)
Pop-up definitions
Context-sensitive Help (available only from a .chm file displayed in applications that support this functionality)
Shortcut buttons to run other programs (available only from a .chm file displayed in the HTML Help Viewer)
Related Topics links
Training card Help (step-by-step interactive help that is available only from a .chm file displayed in the HTML Help Viewer)
Splash screen

The best way to insert the HTML Help ActiveX control in an HTML file is by opening the HTML file in HTML Help Workshop and clicking HTML Help Control on the Tags menu. A wizard appears that lets you choose what kind of command to use with the control and helps you define other parameters to apply to that command. When you click Finish, the wizard inserts the appropriate <OBJECT> and <PARAM> tags in the HTML file.

For example, the following HTML fragment inserts an instance of the HTML Help ActiveX control that creates a Related Topics button to display a dialog box that lists two topics:

<OBJECT ID=HHCtrl TYPE="application/x-oleobject"
    CLASSID="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
    CODEBASE="HHCtrl.ocx#Version=4,73,8259,0"
    WIDTH=12
    HEIGHT=12>

    <PARAM id="Command" VALUE="Related Topics">
    <PARAM id="Button" VALUE="Text:Related Topics">
    <PARAM id="Item1" VALUE="First topic;topic1.htm">
    <PARAM id="Item2" VALUE="Second topic;topic2.htm">
</OBJECT>

Note

Unlike many Microsoft ActiveX controls, the HTML Help ActiveX control can be inserted only in HTML files. Even though the HTML Help ActiveX control is available as the HHCtrl object in the list of controls that you can add to the Toolbox in Office applications, if you try to insert the control in a form or document, an error message is displayed. The version number shown in the previous sample HTML code for the CODEBASE attribute (Version=4,73,8259,0) is the current version of the control at the time of this writing. When you insert an HTML Help ActiveX control by using HTML Help Workshop, the version number will reflect the version of the control that is installed on your computer.

When you have the <OBJECT> tag for an instance of the HTML Help ActiveX control inserted in an HTML page, you can use Microsoft JScript or Microsoft Visual Basic Scripting Edition (VBScript) to work with the control. For example, the following HTML fragment uses an instance of HHCtrl.ocx and the control's TextPopup method in JScript to create a text pop-up:

<OBJECT ID=HHCtrl TYPE="application/x-oleobject"
    CLASSID="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
    CODEBASE="HHCtrl.ocx#Version=4,73,8259,0">
</OBJECT>

<P>This is a 
<A HREF=JScript:HHCtrl.TextPopup(MyText,"Verdana,10",9,9,-1,-1)>
pop-up</A>.
</P>
<SCRIPT>MyText="This is how a text pop-up window looks."
</SCRIPT>

If you prefer to use VBScript, you can create an identical text pop-up by replacing JScript in the <A HREF> tag with VBScript like this:

<A HREF=VBScript:HHCtrl.TextPopup(MyText,"Verdana,10",9,9,-1,-1)>
pop-up</A>.

The HTML Help ActiveX Control vs. the HTML Help JScript Applet

Although the HTML Help JScript applet provides much of the same functionality as the HTML Help ActiveX control, the JScript applet is more useful when it is used on a Web site than when it is used in a compiled HTML Help file. The JScript applet does not provide as many features as the ActiveX control does, and it loads the table of contents and index more slowly than the ActiveX control does. However, the JScript applet allows your Web site to use HTML Help navigation features and still be compatible with browsers that don't support ActiveX controls.

Compiling HTML Help

HTML Help API and linking to programs

HTML Help exposes an API which permits it to be remotely controlled using a suitably coded Windows program, such as Visual Basic (VB). The HTML Help API resides within the HHctrl.ocx ActiveX object distributed with Windows 98, and later OSs. See HTML Help History for details and availability.

Typically, a program uses the HTML Help API to display a particular help topic relative to the current functionality of the program calling the help. Most often, this is in response to an action of the end user of the program, like when the user clicks on a Help menu item, a Help button, a What's this? help button, or presses F1.

Important

Each of these methods for calling the help must be previously specifically setup at both ends of the call, that is, within the program calling the help, and within the help being called.

HTML Help API Direct calling method

The direct calling method is the least complex procedure for calling the HTML Help API from VB. It uses the HH_DISPLAY_TOPIC command and passes the actual filename of the topic to be displayed. You need to know the name and location of the help file, as well as the name and internal path of the topic.

To declare the HTML Help API (using the direct method) in a VB Project

Copy the following code into the project module file or into the declaration section of the form which is to make the call to the help.

 Public Declare Function HTMLHelpS Lib "hhctrl.ocx" Alias "HtmlHelpA" ( _
	ByVal hwnd As Long,  _
	ByVal lpHelpFile As String,  _
	ByVal wCommand As Long, _
	ByVal dwData As String _
	) As Long

Public Const HH_DISPLAY_TOPIC = &H0

Nominate the HTML help file and topic to be called. For example, HTML Help comes with its own help, called "HTMLhelp.chm" which in turn contains a topic named "dsstart.htm" with the title "Start a help system design". To call this help topic, copy the contents of the following Help button click event into your calling procedure.
```
Private Sub cmdHelp_Click()
	Dim hwndHelp As Long
	Dim hwnd As Long
	Dim HelpFileName as String
	Dim HelpTopic as String
	hwnd = 0
	HelpFileName = "C:\WINNT\HELP\HTMLHELP.CHM"
	HelpTopic = "dsstart.htm"
	hwndHelp = HTMLHelpS(hwnd, HelpFileName, HH_DISPLAY_TOPIC, HelpTopic)
End Sub
```
Notes
- You should check that the HTML Help file you're calling does actually exist before you call it. In this example, the file being called is located in the Windows 2000 default help folder "C:\WINNT\HELP\". It may or may not exist on your machine, or may be located in a different folder. Alter your code to point to an actual help file and topic filename.
- You must include the file extension ".CHM" with the declaration of the help filename, and you must include the file extension ".HTM" with the declaration of the topic filename.
Tip

To determine the filename of a topic within a compiled HTML help file, activate the help file, click the Windows System icon (located in the upper top left corner of the HTML help viewer), select the Jump to URL menu item, and view the Current URL field. In the above example, this field displays the string "mk:@MSITStore:C:\WINNT\Help\htmlhelp.chm::/dsstart.htm ". The topic file name is positioned at the end of the string. The internal path within the help file to the topic is everything positioned between the double colon after the help file name, to the topic file name. In this case, the path consists of a single forward slash indicating that this topic file exists in the root folder of the compiled help file.
Save your project and run it. The help should display the requested topic.

xyz Example

The HTML Help API ships with its own help file called "API.chm", also located in the Windows 2000 default Help folder "C:\WINNT\HELP\", and contains a topic named "how_calling_the_html_help_api.htm" with the title "About the HTML Help API function". (Don't ask me why they named it that — ask MS). That help actually details the procedure for calling HTML Help from a C++ program. However, to call this help topic in VB, copy the contents of the following Help button click event into your calling procedure.

Private Sub cmdHelp_Click()
	Dim hwndHelp As Long
	Dim hwnd As Long
	Dim HelpFileName as String
	Dim HelpTopic as String
	hwnd = 0
	HelpFileName = "C:\WINNT\HELP\API.CHM"
	HelpTopic = "how_calling_the_html_help_api.htm"
	hwndHelp = HTMLHelpS(hwnd, HelpFileName, HH_DISPLAY_TOPIC, HelpTopic)
End Sub

Note Notes

The only differences between this example and the previous are the help file and topic file names. They call up separate topics from separate helps.
The first parameter hwnd is set to NULL (long data type containing a zero) as it is ignored by the HTMLHelpS function in this call.
The return value is ignored here as it serves no purpose in this example.

Unfortunately, the direct calling method hard codes the help topic filename into the button click event, so requires a change in the calling program every time the topic filename is changed within the help project, and visa-versa. Both ends of the call must match exactly, or the help call will fail, or the wrong topic will be displayed.

There may be situations where the help author cannot change (or have someone else change) the calling program topic filenames. To overcome this difficulty, HTML Help supports an indirect calling method using a mapping facility which permits ID numbers to be passed instead of names. This too, must be setup at both ends of the call, however once setup, permits the ready change of topics within the help file without the need to change the calling program.

HTML Help API Indirect calling method

The indirect calling method involves a slightly more complex procedure than the direct calling method when calling the HTML Help API from VB. It uses the HH_HELP_CONTEXT command and passes a unique ID number representing the topic to be displayed. You still need to know the name and location of the help file, however you don't need to know the name or path of the topic file for the call.

The topics are identified through the use of a mapped ID value, which must be setup in the both the calling program and the help project before each is compiled. Two additional files must also be created and added to the HTML Help project to enable topic ID mapping: a header file (*.h), and an alias file (*.ali).

To add topic ID mapping to an HTML Help project

Create the .h and .ali text files
Add the mapping files to the project file
Compile and test the HTML Help file

Add the HTML Help API declaration to the calling VB project
Add the html Help API call function to the VB project
Compile and test the VB project HTML Help API calls

To declare the HTML Help API (using the indirect method) in a VB Project

Copy the following code into the project module file or into the declaration section of the form which is to make the call to the help.

 Public Declare Function HTMLHelpS Lib "hhctrl.ocx" Alias "HtmlHelpA" ( _
	ByVal hwnd As Long,  _
	ByVal lpHelpFile As String,  _
	ByVal wCommand As Long, _
	ByVal dwData As String _
	) As Long

Public Const HH_DISPLAY_TOPIC = &H0

Nominate the HTML help file and topic to be called. For example, HTML Help comes with its own help, called "HTMLhelp.chm" which in turn contains a topic named "dsstart.htm" with the title "Start a help system design". To call this help topic, copy the contents of the following Help button click event into your calling procedure.
```
Private Sub cmdHelp_Click()
	Dim hwndHelp As Long
	Dim hwnd As Long
	Dim HelpFileName as String
	Dim HelpTopic as String
	hwnd = 0
	HelpFileName = "C:\WINNT\HELP\HTMLHELP.CHM"
	HelpTopic = "dsstart.htm"
	hwndHelp = HTMLHelpS(hwnd, HelpFileName, HH_DISPLAY_TOPIC, HelpTopic)
End Sub
```
Note

You should check that the HTML Help file you're calling does actually exist before you call it. In this example, the file being called is located in the Windows 2000 default help folder "C:\WINNT\HELP\". It may or may not exist on your machine, or may be located in a different folder. Alter your code to point to an actual help file and topic filename.