Microsoft Office 2000/Visual Basic Programmer's Guide   

Working with the HTML Help ActiveX Control

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 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:

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 NAME="Command" VALUE="Related Topics">
    <PARAM NAME="Button" VALUE="Text:Related Topics">
    <PARAM NAME="Item1" VALUE="First topic;topic1.htm">
    <PARAM NAME="Item2" VALUE="Second topic;topic2.htm">
</OBJECT>

Note   Unlike many 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.

Once 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=JavaScript: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 JavaScript in the <A HREF> tag with VBScript like this:

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

For more information about using script with the HTML Help ActiveX control, see the HTML Help ActiveX Control Reference Web site at http://www.microsoft.com/workshop/author/htmlhelp/hharef.asp.

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

Although the HTML Help Java applet provides much of the same functionality as the HTML Help ActiveX control, the Java applet is more useful when it is used on a Web site than when it is used in a compiled HTML Help file. The Java 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 Java applet allows your Web site to use HTML Help navigation features and still be compatible with browsers that don't support ActiveX controls. For more information about working with the Java applet, see "Working with the HTML Help Java Applet" later in this chapter.