About the HTML Help ActiveX control reference

The HTML Help ActiveX control reference provides information about how to use the control in an HTML file and how to set its commands and parameters.

The reference provides the following sections:

  • The overview section describes the functionality of the HTML Help ActiveX control (Hhctrl.ocx) and how it interacts with Microsoft Internet Explorer. They explain how to insert the control into an HTML file and how to code the HTML <OBJECT> and <PARAM> tags. They also discuss how to work with multiple instances of the control.

  • The parameters section explains how to code the <PARAM> tag and provide comprehensive reference information for all parameters with a link to each command that uses a specific parameter.

  • The commands section explains how to specify a command and provide comprehensive reference information for all commands, including syntax descriptions and code examples.

  • The methods section provides comprehensive reference information for all methods, including syntax descriptions and code examples.

© 1998 Microsoft Corporation. All rights reserved. Terms of use.


About the HTML Help ActiveX control

The HTML Help ActiveX control (Hhctrl.ocx) provides a rich feature set for help systems. Key features include: an expanding table of contents, keyword search, shortcuts, and pop-up help topics. The control is one of the authoring components that ships with Microsoft HTML Help. It is also included with many third-party HTML Help authoring tools.

The control provides functionality for two types of help systems:

A compiled help (.chm) file
The control uses both an Internet Explorer DLL (Shdocvw.dll) and the HTML Help compiler to offer a variety of features. Users view compiled help files in the Help Viewer. Compiled help files often ship with the programs that they document.

Uncompiled HTML files on a Web site:
The control uses Microsoft Internet Explorer to provide a subset of its feature set. The features of HTML Help can be used on a Web site to present a wide variety of content, from Web-based help to a Web site focused on entertainment.

Notes

  • The HTML Help ActiveX control is designed to work with Internet Explorer and the Shdocvw.dll component. It does not include the design-time support that is necessary to use it with development tools, such as Microsoft Visual Basic Scripting Edition and Microsoft Visual C++.

  • For more information about ActiveX technology, see Microsoft's Component Object Model (COM) technologies Web site.

link to overview topic About the HTML Help ActiveX control reference


Inserting the HTML Help ActiveX control in a file

You can add the HTML Help ActiveX control to an HTML file by using the standard HTML <OBJECT> tag. The <OBJECT> tag includes a set of parameters that you use to specify which data the control should use, and to control the appearance and behavior of the control.

Whether you use the control in a compiled help (.chm) file or in uncompiled HTML files, you can insert the control using the HTML Help ActiveX Control Wizard, or you can insert it manually, by typing the appropriate <OBJECT> tag code.

Inserting the control using HTML Help Workshop

Use the HTML Help ActiveX Control Wizard, which is included in the HTML Help Workshop, to author any of the commands in an HTML file.

To use the HTML Help ActiveX Control Wizard, start HTML Help Workshop, and then open an HTML file. Position your cursor anywhere between the <BODY> start and end tags, and then click HTML Help ActiveX Control.

HTML Help ActiveX Control

Opens the HTML Help ActiveX Control Wizard, which enables you to insert or edit the control in an HTML file.

To edit an existing instance of the control, position your cursor anywhere within the <OBJECT> start and end tags of the control, and then click HTML Help ActiveX Control.

Inserting the control manually

The easiest way to work with the control is to insert it using the HTML Help ActiveX Control Wizard. However, you can also copy an existing instance of the control from one HTML file into another. You can then edit the <OBJECT> tag code manually.

When you copy an existing control, make sure to copy all the text from the start <OBJECT> tag through the end </OBJECT> tag. You should then paste the text anywhere between the <BODY> start and end tags of an HTML file.


About the HTML Help ActiveX control syntax

All of the code required for an instance of the HTML Help ActiveX control is contained within the HTML <OBJECT> start and end tags. Use the <OBJECT> tag to specify a command, such as Splash or Contents, and to call a method, such as Click or TextPopup.

Using the HTML Help ActiveX Control Wizard in HTML Help Workshop, you can insert the basic syntax automatically.

Coding the HTML <OBJECT> tag

The <OBJECT> tag enables you to embed the HTML Help ActiveX control directly in a file. The attributes in the following table are required by the control.

Attribute Description
ID

Specifies the name by which the HTML Help ActiveX control will be known to the HTML file. The default ID is HHCTRL, but you can specify any name you want.

For example, if you entered Test as the ID, you would use that same ID to refer to the control from a script.

If you use multiple instances of the HTML Help ActiveX control in a file, each instance must have a unique ID.
TYPE

Specifies the MIME type for the object. The HTML Help ActiveX control TYPE is application/x-oleobject.
CLASSID

Uniquely identifies the HTML Help ActiveX control from other ActiveX controls. The HTML Help ActiveX control identifier is the registry key number and is the same for every instance of the control that you use.

The HTML Help ActiveX control CLASSID is
clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11.
CODEBASE

Specifies the version number of the HTML Help ActiveX control. Enables the automatic download mechanism of ActiveX controls and full version checking.
PARAM

The PARAM attribute, which is also an HTML tag with attributes specific to it, lists a sequence of NAME and VALUE attribute pairs that are passed to the HTML Help ActiveX control to specify which HTML Help feature to provide and how to provide it.

Notes

  • Several standard <OBJECT> tag attributes, such as ALIGN, BORDER, CODETYPE, DECLARE, HEIGHT, HSPACE, NAME, SHAPES, STANDBY, USEMAP, VSPACE, and WIDTH, can also be used to define the appearance and position of the HTML Help ActiveX control.
  • WIDTH and HEIGHT values can be expressed in percentage, followed by a percent sign, or in pixels (numeric value only).
  • The HTML Help ActiveX control does not support the <OBJECT> tag DATA attribute.

Coding the <PARAM> tag

The <PARAM> tag is used to pass a sequence of parameters to the HTML Help ActiveX control to specify a feature and any additional information that the feature may require.

The <PARAM> tag is valid only within an <OBJECT> tag. The end tag is optional.

Attribute | Description
NAME | Specifies a parameter. The first parameter in the sequence must be Command.
VALUE | Specifies a valid value for the parameter specified in the NAME attribute.

Note

  • For more information about other attributes supported by the <OBJECT> and <PARAM> tags, see a comprehensive HTML Reference, such as the Microsoft Site Builder Network (SBN) HTML Elements reference.


About using multiple instances of the HTML Help ActiveX control

It is not uncommon for a single HTML file to contain multiple instances of the HTML Help ActiveX control. For example, if you want to add a splash screen, provide a list of Related Topic links, and open a WinHelp topic all from one HTML file, then that file would contain three instances of the control. Each instance would call one command.

If multiple instances of the control are used in the same file, each instance must have a unique name specified in the ID attribute of the <OBJECT> tag. The ID attribute is case-sensitive.


About parameters

A parameter is a set of <PARAM> tags with NAME and VALUE attributes that specify a command and information required by the command.

For example, when you specify the Contents command, you must also specify a contents (.hhc) file using the Item1 parameter.

Some parameters are used with more than one command. For information about a specific instance of a parameter, see the command for which it is used.

Parameters quick reference

  • Button
  • Command
  • Default Topic
  • Flags
  • Font
  • Frame
  • Item
  • Text


Button parameter

Use the Button parameter to create a button that will invoke a command when clicked. You can select from several button styles.

Applies to

ALink
Close
HH Version
KLink
Related Topics
Shortcut
TCard
WinHelp

Valid values

When clicked, the following example buttons each call the HH Version command.

Syntax | Description | Example | Notes
<PARAM name="Button" value="Text:button text"> | Button with a text label. | You can enter text of any length for the label. The text will not wrap.
<PARAM name="Button" value=""> | "Chiclet" button. | To specify a chiclet button, you can remove the Button parameter entirely or use empty quotation marks (value="").
<PARAM name="Button" value="Bitmap:shortcut"> Button with a shortcut icon. ...
<PARAM name="Button" value="Bitmap:path to .bmp file"> | Button with a bitmap image. | You can specify an absolute or relative path.
<PARAM name="Button" value="Icon:path to .ico file"> | Button with an icon. | You can specify an absolute or relative path.

Example

The following example uses a button with a bitmap image to call the HH Version command.

<OBJECT

  id=bitmap

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="HH Version">

  <PARAM name="Button" value="Bitmap:bmpbutton.bmp">

</OBJECT>

Comments

  • You can invoke a command using the Click method instead of a button.
  • Be sure to include all graphic files in the [FILES] section of your HTML Help project (.hhp) file.


Command parameter

Use the Command parameter to specify an HTML Help command.

Applies to

ALink
Close
Contents
HH Version
Index
KLink
Related Topics
Shortcut
Splash
TCard
WinHelp

Valid values

Syntax Description
<PARAM name="Command" value="command name [,menu|,dialog [,popup]]"> Specifies the command to invoke.

The ALink, KLink, and Related Topics commands include a setting ([,menu|,dialog]) that specifies whether to display target topics on a pop-up menu or in a dialog box.

The WinHelp command includes a setting ([,popup]) that specifies the window type in which to display the specified WinHelp topic.

Multiple Command parameter values are delimited by a comma.


Default Topic parameter

Use the Default Topic parameter to specify a topic to navigate to if an ALink or KLink cannot locate the target topic.

Applies to

ALink
KLink

Valid values

Syntax | Description | Notes
<PARAM name="Default Topic" value="File name or HTTP URL"> | Specifies an HTML file name or an HTTP URL to navigate to if the link fails. | The Default Topic parameter is optional.


Flags parameter

Use the Flags parameter to specify how topics should be searched for, and how they should appear, for certain commands.

Applies to

ALink
Contents
KLink

Valid values

Syntax | Description | Notes
<PARAM name="Flags" value="1"> | Used with the ALink or KLink commands to specify that when a single target topic is found, the topic should appear in the window type specified in the Command parameter. | If this parameter is empty (value=" "), clicking the ALink or KLink navigates directly to the target topic when a single topic is found.
<PARAM name="Flags" value=",,1"> | Used with the ALink or KLink commands to specify that when a target topic cannot be found, the ALink or KLink button (or text) should be unavailable. | If this parameter is empty (value=" "), clicking the ALink or KLink opens a Topic Not Found dialog box when the topic cannot be located.
<PARAM name="Flags" value="numeric value of selected window styles"> | Used with the Contents command to store the numeric value of the selected window style attributes. | The window style hexadecimal numeric values are not currently mapped. We recommend that you use the HTML Help ActiveX Control Wizard to select window styles. The wizard automatically inserts the appropriate parameter values in the format 0xn.


Font parameter

Use the Font parameter to specify font attributes for the Text or Button parameter.

Applies to

ALink
Close
HH Version
KLink
Related Topics
Shortcut
TCard
WinHelp

Valid values

Syntax | Description | Notes
<PARAM name="Font" value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]"> | Specifies the following font attributes: font family, point size, character set, color, and format options. | The Font parameter is optional. The default font settings are: "Helvetica,12,,,PLAIN" For best results, specify only standard system fonts. The Font parameter may be ignored if the character set conflicts with the language ID of the help file.


Frame parameter

Use the Frame parameter to specify the frame in which you want target topics to appear.

Applies to

ALink
KLink
Related Topics

Valid values

Syntax | Description | Notes
<PARAM name="Frame" value="frame name"> | If you are using a frameset, specifies the frame for the selected topic to appear in. | The Frame parameter is optional.


Item parameter

The Item parameter is dependent on the specified command. For usage information, see the individual commands that use this parameter.

Applies to

ALink
Contents
Index
KLink
Related Topics
Shortcut
Splash
TCard
WinHelp

Valid values

Syntax Description

<PARAM name="Item1" value=" ">

<PARAM name="Item2" value=" ">

<PARAM name="Item3" value=" ">

Valid values depend on which command is specified.

  • Alink: Specifies the .chm file path and one or more ALink names to look up.
  • Contents: Specifies the .hhc file path.
  • Index: Specifies the .hhk file path.
  • KLink: Specifies the .chm file path and one or more keywords to look up.
  • Related Topics: Specifies an entry in the Related Topics list.
  • Shortcut: Specifies the program to open. Depending on the functionality you want to implement with the Shortcut command, you may need to supply additional information.
  • Splash: Specifies the image file path and length of time the image will appear.
  • TCard: Specifies the wPARAM and lPARAM values to pass to the Windows WM_TCARD message. Depending on the functionality you want to implement with TCard, you may need to supply additional information.
  • WinHelp: Specifies the .hlp file path and topic ID (or map number).


Text parameter

Use the Text parameter to create a link that will invoke a command when clicked.

Applies to

ALink
Close
HH Version
KLink
Related Topics
Shortcut
TCard
WinHelp

Valid values

Syntax | Description | Notes
<PARAM name="Text" value="Text: Link text"> | Specifies the link text. | The Text parameter is optional.


About commands

The Command parameter supports a set of values, known as commands. Each value specifies an action for the HTML Help ActiveX control to carry out. Most of the commands require that you specify additional parameters that determine exactly how to carry out the action.

Use the commands to add functionality to a compiled help (.chm) file or a set of uncompiled HTML files. For example, the Contents command adds a graphical table of contents to your help system based on a contents (.hhc) file that you specify.

Notes

  • All of the commands are available in HTML Help Workshop through the HTML Help ActiveX Control Wizard. The wizard guides you through the process of inserting the HTML Help ActiveX control in a file.
  • Only one command can be specified in any single instance of the control.
  • A command should be located in an HTML file exactly where you want the feature to appear.

Commands quick reference

Command

Use with a compiled help file

Use with uncompiled HTML files
ALink X ...
Close X ...
Contents | X | X
HH Version | X | X
Index | X | X
KLink X ...
Related Topics | X | X
Shortcut X ...
Splash | X | X
TCard X ...
WinHelp X ...


ALink

ALink command

Purpose

Creates Associative links (ALinks) that jump to target HTML files that contain the specified ALink names. The list of target topics appears on a pop-up menu or in a dialog box.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command"       value="ALink [,menu|,dialog]">

<PARAM  name="Item1"         value=".chm file path">

<PARAM  name="Item2"         value="ALink text">

[<PARAM name="Button"        value="[Text: Button text|Bitmap:Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Default Topic" value="File name or HTTP URL">]

[<PARAM name="Font"          value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Flags"         value=",,1">]

[<PARAM name="Flags"         value="1">]

[<PARAM name="Frame"         value="Frame Name">]

[<PARAM name="Text"          value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the ALink command and specifies whether to display target topics on a pop-up menu or in a dialog box. If you do not specify a display option, a dialog box appears by default. To specify the Topics Found dialog box, type dialog. To specify a pop-up menu, type menu.
Default Topic | Specifies the topic to navigate to if the look up fails. Optional.
Flags | Specifies how to behave if only one target is found or if the target is unavailable.
Font | Specifies the font attributes. Optional.
Frame | Specifies the frame in which to display the selected topic. Optional.
Item1 | Specifies the compiled help file that contains the target topics.
Item2 | Specifies the text for one ALink name. This text must match an ALink name that has previously been inserted into one or more topics using the Compiler Information feature. Subsequent ALink names are specified as Item3, Item4, etc.
Text | Specifies the link text. Optional.

Example

Note that in this example ALink targets will appear in the Topics Found dialog box because neither dialog nor menu is specified in the Command parameter value.

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="ALink">

  <PARAM name="Button" value="Text:See Also">

  <PARAM name="Item1" value="c:\Help\MyFile.chm">

  <PARAM name="Item2" value="overview">

  <PARAM name="Item3" value="bibliography">

</OBJECT>

Sample ALink command

Comments

  • The Button parameter is omitted when this command is invoked by a script.
  • To add ALink names to an HTML file, use the Compiler Information command, which is available on the Edit menu of HTML Help Workshop.


Close

Close command

Purpose

Closes the window in which the current topic appears.

You can use the Close command to close a secondary window that does not include a Close button.

The Close command could also be used with a help wizard. For example, a user could answer the question "Did this solve your problem?" by clicking No, which would link to the next topic, or clicking Yes, which would close the window.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command" value="Close">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Text"    value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the Close command.
Font | Specifies the font attributes. Optional.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="Close">

  <PARAM name="Button" value="Text:Close this window!">
</OBJECT>

Comments

  • The Button parameter is omitted when this command is invoked by a script.


Contents

Contents command

Purpose

Creates a graphical table of contents that displays a specified contents (.hhc) file.

This command can be used with either a compiled help (.chm) file or uncompiled HTML files.

Syntax

<PARAM name="Command" value="Contents">

<PARAM name="Item1"   value=".hhc file path">

<PARAM name="Flags"   value="0xn,0xn">

Property | Description
Command | Calls the Contents command.
Flags | Specifies ExWindow Styles and Window Styles values for the selected window style attributes. The values are stored as hexadecimal numbers in the format 0xn. We recommend that you use the HTML Help ActiveX Control Wizard to select window styles. The wizard automatically inserts the appropriate parameter values in the format 0xn.
Item1 | Specifies the contents (.hhc) file path.

Example

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100%

  height=100%

>

  <PARAM name="Command" value="Contents">

  <PARAM name="Item1" value="C:\toc.hhc">

  <PARAM name="Flags" value="0x4000,0x800035>
</OBJECT>

Comments

  • The Flags parameter will overwrite any ExWindow Styles and Window Styles parameter values that have been set in the specified contents (.hhc) file using the Table of Contents dialog box in HTML Help Workshop.


HH Version

HH Version command

Purpose

Displays the version number of the HTML Help ActiveX control (Hhctrl.ocx) in a dialog box.

This command helps users to determine whether they are using the most current version of HTML Help.

This command can be used with either a compiled help (.chm) file or uncompiled HTML files.

Syntax

<PARAM  name="Command" value="HH Version">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Text"    value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the HH Version command.
Font | Specifies the font attributes. Optional.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="HH Version">

  <PARAM name="Button" value="Text:Click for version number">

</OBJECT>

Sample HH Version command

Click here to see the version number of the HTML Help ActiveX control used in this topic.

Comments

  • The Button parameter is omitted when this command is invoked by a script.


Index

Index command

Purpose

Creates a graphical index that displays a specified index (.hhk) file.

This command can be used with either a compiled help (.chm) file or uncompiled HTML files.

Syntax

<PARAM name="Command" value="Index">

<PARAM name="Item1"   value=".hhk file path">

Property | Description
Command | Calls the Index command.
Item1 | Specifies the index (.hhk) file path.

Example

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100%

  height=100%

>

  <PARAM name="Command" value="Index">

  <PARAM name="Item1" value="c:\Index Files\MyIndex.hhk">

</OBJECT>


KLink

KLink command

Purpose

Creates Keyword links (KLinks) that jump to target HTML files that contain the specified keyword(s). The list of target topics appears on a pop-up menu or in a dialog box.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command"       value="KLink [,menu|,dialog]">

<PARAM  name="Item1"         value=".chm file path">

<PARAM  name="Item2"         value="keyword text">

[<PARAM name="Button"        value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Default Topic" value="File name or HTTP URL">]

[<PARAM name="Font"          value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Flags"         value=",,1">]

[<PARAM name="Flags"         value="1">]

[<PARAM name="Frame"         value="Frame Name">]

[<PARAM name="Text"          value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the KLink command and specifies whether to display target topics on a pop-up menu or in a dialog box. If you do not specify a display option, a dialog box appears by default. To specify the Topics Found dialog box, type dialog. To specify a pop-up menu, type menu.
Default Topic | Specifies the topic to navigate to if the look up fails. Optional.
Flags | Specifies how the command will behave if only one target is found or the target is unavailable.
Font | Specifies the font attributes. Optional.
Frame | Specifies the frame in which to display the selected topic. Optional.
Item1 | Specifies the compiled help (.chm) file that contains the target topics.
Item2 | Specifies a keyword. This text must match a keyword that has previously been inserted into one or more topics using the Compiler Information command. Subsequent keywords are specified as Item3, Item4, etc.
Text | Specifies the link text. Optional.

Example

Note that KLink targets will appear on a pop-up menu in this example because menu is specified in the Command parameter.

<OBJECT

  id=MyControl

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="KLink, menu">

  <PARAM name="Button" value="Text:Animal Diets">

  <PARAM name="Item1" value="animals.chm">

  <PARAM name="Item2" value="omnivore">

  <PARAM name="Item3" value="carnivore">
</OBJECT>

Sample KLink command

Comments

  • The Button parameter is omitted when this command is invoked by a script.
  • To add keywords to a target HTML file, use the Compiler Information command, which is available on the Edit menu of HTML Help Workshop.


Related Topics

Related Topics command

Purpose

Displays a list of target topics that a user can jump to. The Item parameter stores information about each target. The list of target topics appears on a pop-up menu or in a dialog box.

This command can be used with either a compiled help (.chm) file or uncompiled HTML files.

Syntax

<PARAM  name="Command" value="Related Topics [,menu|,dialog]">

<PARAM  name="Item1"   value="Topic1;Main URL for Topic1;Alternate URL for Topic1">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Frame"   value="Frame Name">]

[<PARAM name="Text"    value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command Calls the Related Topics command and specifies whether to display target topics on a pop-up menu or in a dialog box.

If you do not specify a display option, a dialog box appears by default.

To specify the Topics Found dialog box, type dialog.

To specify a pop-up menu, type menu.
Font | Specifies the font attributes. Optional.
Frame | Specifies the frame in which to display the selected topic. Optional.
Item1 Specifies the following information about the target topic:
  • Topic title as you want it to appear in the Topics Found dialog box or on a pop-up menu.
  • Topic file path.
  • Alternate topic to display if the first topic is unavailable.

Multiple values are delimited by a semicolon.

To specify subsequent topic information, use Item2, Item3, etc.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=candomble

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="Hhctrl.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="Related Topics, MENU">

  <PARAM name="Button" value="Text:See Also">

  <PARAM name="Item1" value="About Oxala;oxala.html;http://example.microsoft.com/">

  <PARAM name="Item2" value="About Yemanja;Yemanja.html;http://example.microsoft.com/">

  <PARAM name="Item3" value="About Oba;oba.html;http://example.microsoft.com/">

  <PARAM name="Item4" value="About Ogum;ogum.html;http://example.microsoft.com/">

  <PARAM name="Item5" value="Bad Link;bad_link.html;http://example.microsoft.com/">
</OBJECT>

Sample Related Topics command

Comments

  • The Button parameter is omitted when this command is invoked by a script.


Shortcut

Shortcut command

Purpose

Creates a shortcut to a specified action by passing Windows-based messages and parameters. For example, if a topic discusses a homeure that involves a specific dialog box, you can provide a link that a user can click in the topic to open the dialog box in the program.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command" value="ShortCut">

<PARAM  name="Item1"   value="window class,program name,parameters">

<PARAM  name="Item2"   value="message ID,wPARAM,lPARAM">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Text"    value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the Shortcut command.
Font | Specifies the font attributes. Optional.
Item1 | Specifies the window class, file path to the program, and any parameters to be sent to the program. These values are delimited by a comma. HTML Help does not support %WINDIR% or other system variables in the file path.
Item2 | Specifies the message ID of a standard Windows message, a wPARAM value, and a lPARAM value. These values are delimited by a comma.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=shortcut

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="hhctrl.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="ShortCut">

  <PARAM name="Button" value="Bitmap:shortcut">

  <PARAM name="Item1" value="notepad,notepad.exe,">

  <PARAM name="Item2" value="273,1,1">
</OBJECT>

Sample Shortcut command

Comments

  • The Button parameter is omitted when this command is invoked by a script.


Splash

Splash command

Purpose

Displays an image for a specified number of seconds when the file that contains the HTML Help ActiveX control is opened. For example, using the Splash command, you could display a product logo or welcome message when a compiled help (.chm) file or Web page is first opened.

This command can be used with either a compiled help file or uncompiled HTML files.

Syntax

<PARAM  name="Command" value="Splash">

<PARAM  name="Item1"   value="image file path">

<PARAM  name="Item2"   value="millisecond value">

[<PARAM name="Item3"   value="alternate image file path">]

Property | Description
Command | Calls the Splash command.
Item1 | Specifies the image file path. Supported image file formats are .gif, .jpeg, or .bmp.
Item2 | Specifies the length of time to display the image in milliseconds (1000 milliseconds = 1 second).
Item3 | Specifies an alternate image file to display if the user's display configuration supports more than 256 colors. Optional.

Example

<OBJECT

  id=splash

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="Hhctrl.ocx#Version=4,72,8252,0"

>

  <PARAM name="Command" value="Splash">

  <PARAM name="Item1" value="test.gif">

  <PARAM name="Item2" value="5000">

</OBJECT>

Sample Splash command

Click here to see a splash screen.

Comments

  • You should insert the HTML Help ActiveX control between the <BODY> start and end tags of the file. Use of the control within the <FRAMESET> start and end tags is currently not supported. If you want to use the Splash command with a frameset, insert the control within the default HTML file that is specified in the frameset document.


TCard

TCard command

Purpose

Sends a Windows WM_TCARD message to the calling program to invoke a training card topic or to perform some other action.

Training cards are help topics that interact with the calling program by sending the appropriate message parameters via WM_TCARD in response to a user action, such as clicking a button within the help window. The calling program then handles the message and responds by performing a specific action. The action can be anything from calling an HTML Help API function to opening an application dialog box.

Typical uses of training cards include guiding users through the steps of a certain task or a troubleshooting process.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command" value="TCard">

<PARAM  name="Item1"   value="wPARAM, lPARAM">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Text"    value="Text: Link text">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

Property | Description
Button | Specifies the button style. Optional.
Command | Calls the TCard command.
Font | Specifies the font attributes. Optional.
Item1 | Specifies the wPARAM and the lPARAM parameter values to pass to the WM_TCARD message. wPARAM usually identifies a user action; this value must be numeric. lPARAM may contain additional data, depending on the value of wPARAM; this value may be numeric or string.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=training

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="HHCTRL.ocx#Version=4,72,8252,0"

  width=100

  height=100

>

  <PARAM name="Command" value="TCard">

  <PARAM name="Button" value="Text: This is a training card">

  <PARAM name="Item1" value="5555, MyText">
</OBJECT>

Comments

  • The TCard command accepts both numeric and string arguments.
  • To call the TCard command multiple times using a scripting language, use the TCard method.
  • To implement training card topics, code must be added to the calling program to handle WM_TCARD messages.


WinHelp

WinHelp command

Purpose

Displays a WinHelp topic in the WinHelp primary window, a WinHelp secondary window, or in a WinHelp pop-up window. The specific window attributes, such as size and position, background color, and button bar items, are based on the definitions in the [WINDOWS] section of the specified WinHelp project (.hpj) file.

This command can be used only with a compiled help (.chm) file.

Syntax

<PARAM  name="Command" value="WinHelp [,Popup]>

<PARAM  name="Item2"   value="topic ID|map number">

<PARAM  name="Item1"   value="WinHelp (.hlp) file path [>window name]">

[<PARAM name="Button"  value="[Text: Button text|Bitmap: Bitmap file path|Icon:Icon file path]">]

[<PARAM name="Font"    value="Facename[, point size[, charset[, color[, PLAIN BOLD ITALIC UNDERLINE]]]]">]

[<PARAM name="Text"    value="Text: Link text">]

Property | Description
Button | Specifies the button style. Optional.
Command Calls the WinHelp command and specifies a WinHelp window type.
  • To display a pop-up WinHelp window, type Popup.

  • To display a secondary WinHelp window, do not specify a window type and specify a window name in the Item1 parameter.

  • To display the WinHelp main window, do not specify a window type or a window name (in the Item1 parameter).
Font | Specifies the font attributes. Optional.
Item1 Specifies the file path of the WinHelp (.hlp) file in which the WinHelp topic is stored, and the window name of the target window.

The window name must be preceded by the ">" character.

Do not specify a window name if you typed Popup in the Command parameter or if you want the topic to appear in the WinHelp main window.

Item2 | Specifies the topic ID or map number of the WinHelp topic to display.
Text | Specifies the link text. Optional.

Example

<OBJECT

  id=winhelp

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="hhctrl.ocx#Version=4,72,8252,0"

  width=100

  height=100
>

  <PARAM name="Command" value="WinHelp">

  <PARAM name="Button" value="Text: Candomble Overview">

  <PARAM name="Item1" value="c:\winhelp\candomble_wh.hlp>MyWindow">

  <PARAM name="Item2" value="myth_candomble_overview">

</OBJECT>

Comments

  • The Button parameter is omitted when this command is invoked by a script.


About methods

Methods enable you to access functionality within the HTML Help ActiveX control through the use of a scripting language, such as JavaScript or Visual Basic Scripting Edition. Generally, methods use the information specified in the <PARAM> tags of the specified HTML Help ActiveX control to determine what functionality is actually to be invoked.

The following example uses the Click method to invoke a command:

<A HREF=JavaScript:related.Click()>Example</A>

where JavaScript is the scripting language, related is the ID of the HTML Help ActiveX control being referenced, Click() is the method, and Example is the text link. The Click() method requires that the control contain <PARAM> tags that specify which command to invoke.

Some methods do not require any parameters to access functionality within the HTML Help ActiveX control. In these cases, if <PARAM> tags are present in a referenced control, they are ignored by the method being called. This lets you reuse an existing instance of the control in your HTML file.

In addition, you can call multiple methods from a single instance of the HTML Help ActiveX control. For example, if you are already using an instance of the control to call the Related Topics command, you can reference the ID of that same control to call the TextPopup method.

If you need to insert a new instance of the control to call a method that does not require parameters, you can omit the <PARAM> tags from the <OBJECT> tag as shown in the following example:

<OBJECT

id=for_script

type="application/x-oleobject"

classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

>

</OBJECT>

where for_script is the ID of the HTML Help ActiveX control that you will reference to call a method. Methods that do not require <PARAM> tags are listed in the table, below.

Methods quick reference

Method | Use with a compiled help file | Use with uncompiled HTML files | Does not require <PARAM> tags
Click | X | X | ...
HHClick | X | X | ...
Print | X | X | ...
SyncURL | X | ... | ...
TCard | X | ... | ...
TextPopup | X | X | X


Click method

Click and HHClick method

Purpose

Use the Click method to invoke any command that supports the Button parameter.

Commands that do not support the Button parameter, such as Splash, are invoked as soon as your HTML file is loaded and, therefore, cannot be called from a method.

This method can be used with either a compiled help (.chm) file or uncompiled HTML files. However, not all commands are supported in uncompiled HTML files.

Applies to

Alink
Close
HH Version
KLink
Related Topics
Shortcut
TCard
WinHelp

Syntax

Click() or HHClick()

The Click method takes no parameters.

Example

The following example shows how to use the Click method to invoke the HH version command.

The code for the control:

<OBJECT

  id=test3

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="hhctrl.ocx#Version=4,72,8252,0"

>

  <PARAM name="Command" value="HH Version">

</OBJECT>
The JavaScript code to invoke the control:

<a href=JavaScript:test3.Click()>On Click, do HH Version</a>

Show Me

Comments

  • If you are using Microsoft Visual Basic Scripting Edition (VBScript), always use HHClick, which provides the same functionality as Click, but prevents a naming conflict with the VBScript Click method.


Print method

Purpose

Use the Print method to print one or more topics in a specified contents (.hhc) file.

This method can be used with either a compiled help (.chm) file or uncompiled HTML files.

Applies to

Contents

Syntax

Print()

The Print method takes no parameters.

Example

The following example shows how to use the Print method to invoke the Contents command.

The code for the Contents command:

<OBJECT

  id=test2

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="hhctrl.ocx#Version=4,72,8252,0"

  width=55%

  height=45%

>

  <PARAM name="Command" value="Contents">

  <PARAM name="Item1" value="methods.hhc">

</OBJECT>
The JavaScript code to call the Print method:

<a href=JavaScript:test2.Print()>Print Contents</a>

Show Me

link to overview topic About methods


SyncURL method

Purpose

Use the SyncURL method to select the contents (.hhc) file entry for a topic that you specify.

The instance of the HTML Help ActiveX control that you reference when using the SyncURL method must specify the Contents command.

This command can be used only with a compiled help (.chm) file.

Applies to

Contents

Syntax

SyncURL(BSTR pszUrl)

PARAM name | Values
pszUrl | Specifies the topic whose corresponding contents entry you want to select.

Example

The following example shows how to use the SyncURL method to select entries in a contents (.hhc) file.

The code for the control:

<OBJECT

  id=sync

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

  codebase="hhctrl.ocx#Version=4,72,8252,0"

  width=35%

  height=25%

>

  <PARAM name="Command" value="Contents">

  <PARAM name="Item1" value="methods.hhc">

  </OBJECT>

The JavaScript code to invoke the control:

<a href=JavaScript:sync.syncURL('textpopup.htm')>Go to textpopup.htm</a>

Show Me

Comments

  • The SyncURL method provides the same functionality as clicking the Locate button on the HTML Help Viewer toolbar.


TCard method

Purpose

Use the TCard method to send a WM_TCARD message from a help window to a program. This method provides the same functionality as the TCard command with the exception that the method accepts only numeric arguments.

Using the TCard method reduces the number of instances of the control in an HTML file. If you plan on using multiple TCard commands in a single HTML file, then you should insert a single <OBJECT> tag, and then call the TCard method.

The instance of the HTML Help ActiveX control that you reference using the TCard method must specify the TCard command.

This command can be used only with a compiled help (.chm) file.

Applies to

TCard

Syntax

TCard(WPARAM wPARAM, LPARAM lPARAM)

PARAM name | Values
wPARAM | Specifies the value to pass to the WM_TCARD message. wPARAM usually identifies a user action. This value must be numeric.
lPARAM | Specifies the value to pass to the WM_TCARD message. Contains additional data, depending on the value of wPARAM. This value must be numeric.

Example

The code for the control:

<OBJECT

  id=test

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

>

  <PARAM name="Command" value="TCard">

  <param name="Button" value="Call TCard command">

  <param name="Item1" value="123, MyText">

</OBJECT>

The JavaScript code to invoke the control:

<a href="JavaScript:test.TCard (5555, 10056)">TCard Example</a>

Comments

  • The TCard method accepts only numeric arguments. To pass a string argument in lPARAM, use the TCard command.


TextPopup method

Purpose

Use the TextPopup method to open a pop-up window.

The instance of the HTML Help ActiveX control that you reference using the TextPopup method does not need to specify a command.

This method can be used with either a compiled help (.chm) file or uncompiled HTML files.

Applies to

This method is independent of any of the HTML Help ActiveX control commands.

Syntax

TextPopup(BSTR pszText, BSTR pszFont, int horzMargins, int vertMargins, COLORREF clrForeground, COLORREF clrBackground)

PARAM name | Values
pszText | A string variable that specifies the text to display in the pop-up window.
pszFont A string variable that specifies the following font attributes:
  • Font family
  • Point size
  • Character set
  • Color
  • Format options

The format is as follows:

Facename[, point size[, charset[, PLAIN BOLD ITALIC UNDERLINE]]]

The default font settings are: "Helvetica,12,,PLAIN"
horzMargins | An integer that determines, in pixels, the side margins relative to the center of the pop-up window.
vertMargins | An integer that determines, in pixels, the top and bottom margins relative to the center of the pop-up window.
clrForeground | Specifies the color of the text in RRGGBB format. To specify the default text color (black), type -1.
clrBackground | Specifies the background color of the pop-up window in RRGGBB format. To specify the default background color (pale yellow), type -1.

Example

The code for the control:

<OBJECT

  id=test

  type="application/x-oleobject"

  classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"

>

</OBJECT>

The JavaScript code to specify the text and font variables:

<script>
FontFace="Verdana,8,,bold"
TopicText="This is an HTML Help pop-up window. This window can display text only."
TopicText2="This is another HTML Help pop-up window."
</script>

The JavaScript code to invoke the control:

<a href="JavaScript:test.TextPopup (TopicText, FontFace, 10,10,10,10)"> TextPopup Example</a>

Show Me

Comments

  • Colors do not display properly.
  • You can store text variables in a separate text file with a .js extension.


Splash command example

This page demonstrates the use of the Splash command. The timeout for this splash screen is set for 5 seconds. Click the image to dismiss the splash window before the allotted time.


Sample: Click method

Sample 1

Click the following link to invoke the HH Version command.

What version am I?

Sample 2

Click the following link to invoke the Related Topics command.

Show me a list of related topics


Print method

Sample: Print method

Click the following link to invoke the Print method, which opens the Print dialog box and allows you to print one or more topics from the contents (.hhc) file.

Print one or more topics in the table of contents


Sample: TextPopup method

Click the following links to call the TextPopup method.

  • The side margin at a value of 99 pixels.
  • The top margin at a value of 99 pixels.
  • The text color at a value of 8855416.
  • The background color at a value of 0.


SyncURL method

Sample: SyncURL method

Click the links, below, to invoke the SyncURL method, which selects the topic in the contents (.hhc) file that displays.

  1. Select TextPopup
  2. Select Click
  3. Select Print
  4. Select SyncURL
  5. Select Click
  6. Select Print
  7. Select SyncURL
  8. Select TextPopup


HTML Help window types

Topics Found display options

When you use the ALink, KLink, and Related Topics commands, you can specify, in the Command parameter, whether to display the list of topics in a dialog box or on a pop-up menu. Both display options will list up to 127 topics.

The following are examples of each display type:

Dialog box

To specify a dialog box, type ,dialog after the command name as in the following example:

<PARAM name="Command" value="Related Topics, dialog">

Pop-up menu

To specify a a pop-up menu, type ,menu after the command name as in the following example:

<PARAM name="Command" value="KLink, menu">

Note

  • If no option is specified in the Command parameter, the Topics Found dialog box is used by default.


WinHelp window types

When using the WinHelp command, specify one of the following WinHelp window types. Specify a pop-up window in the Command parameter:

Pop-up WinHelp window

This graphic is not yet available

Secondary WinHelp window

This graphic is not yet available

Primary WinHelp window (main)

This graphic is not yet available

Notes

  • The specific window attributes, such as size, position, and background color, are based on the definitions in the [WINDOWS] section of the specified WinHelp project (.hpj) file.
  • If you do not specify a window type or a window name, the main window is used.