Displaying Help by Using the HtmlHelp API

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Because the current implementation of the HTML Help ActiveX control can't be inserted in a form and doesn't provide Component Object Model (COM) interfaces, you must call its API directly if you need to use features beyond those supported by the methods and properties available in VBA. Because Word and Access don't currently provide a built-in method for displaying custom Help topics, you must use the HtmlHelp API to display a custom Help topic in those applications.

Before you can use an API call from VBA code, you must create a function declaration in the Declarations section of a form, class, or standard module. The HtmlHelp API requires a single function declaration that looks like this:

Declare Function HtmlHelp Lib "HHCtrl.ocx" Alias "HtmlHelpA" _
   (ByVal hwndCaller As Long, _
   ByVal pszFile As String, _
   ByVal uCommand As Long, _
   dwData As Any) As Long

This declaration uses the ANSI version of the HtmlHelp function exported by HHCtrl.ocx. For more information about using API calls from VBA, see Chapter 10, "The Windows API and Other Dynamic-Link Libraries."

The arguments of the HtmlHelp function provide the following functionality.

Argument	Description
hwndCaller	A handle to an application window or Null. This window handle may be used as a parent, owner, or message recipient for HTML Help, depending on how it is used. In VBA, instead of setting this to vbNullString, set it to 0 (zero).
pszFile	File to display; optionally also specifies which window type to display it in, delimited with the right angle bracket character (filename>windowtype). If you omit the window type, the HtmlHelp function will use the default window type specified in the HTML Help project file. For uCommand values that don't require a source file, pszFile can be Null, or 0 (zero), in VBA. However, a compiled HTML Help file is typically specified.
uCommand	The action to perform; see the remainder of this section for examples of how to display a Help topic by using either the HH_HELP_CONTEXT or HH_DISPLAY_TOPIC command.
dwData	Specifies additional data depending on the value of uCommand. Note that in this declaration this argument is declared As Any, because this argument accepts several different data types. You must be careful to pass the correct data type or risk an invalid page fault (also known as general protection fault [GPF]).

The HtmlHelp function supports a broad variety of HTML Help functionality and provides detailed control unavailable through other programmatic means. The rest of this section describes how to use the HtmlHelp function to display a custom Help topic. For more information about using other commands with the uCommand argument, see the HtmlHelp API Reference in the Help system for HTML Help Workshop.

To make using the HtmlHelp function from VBA simpler, in addition to the function declaration, you should also declare the following constants to pass as the uCommand argument:

Const HH_DISPLAY_TOPIC = &H0
Const HH_HELP_CONTEXT = &HF

The constants in the following table are used to specify which uCommand command to use with the HtmlHelp function to display a Help topic.

uCommand command	Description
HH_DISPLAY_TOPIC	Displays a Help topic by passing the name of the HTML file that contains the topic as the dwData argument.
HH_HELP_CONTEXT	Displays a Help topic by passing the mapped context ID for the topic as the dwData argument.

The command you choose to use depends on whether you have mapped context IDs for each topic as described earlier in this chapter in "Creating a Help File to Use with an Office Solution." If you haven't created context IDs, you must use the HH_DISPLAY_TOPIC command. If you have created context IDs, you can use either command.

When you are using either command from an Office application, you should pass 0 (zero) as the hwndCaller argument so that HTML Help will display the Help topic in siblingmode. Sibling mode (shown in Figure 13.2) causes HTML Help to display Help topics in a separate top-level overlapped Help window that is displayed alongside the calling application. The user can freely switch between the application and the Help window.

Figure 13.2 Sibling Mode

The following line of code shows how to display a Help topic by using the HH_DISPLAY_TOPIC command:

Call HtmlHelp(0, "c:\help\Sample.chm", HH_DISPLAY_TOPIC, By Val "Topic1.htm")

This code will display the topic authored in Topic1.htm, which is compiled in the Sample.chm file. Because no window type was specified for the pszFile argument, the topic will be displayed by using the default window type specified in the HTML Help project file that was used when the Help file was compiled.

The following line of code shows how to display a Help topic by using the HH_HELP_CONTEXT command:

Call HtmlHelp(0, "c:\help\Sample.chm>mso_small", HH_DISPLAY_TOPIC, By Val 2001&)

This code will display the topic specified by the mapped context ID 2001 in the Sample.chm file. The ampersand (&) following the context ID is required to specify that the value being passed to the HtmlHelp function is a Long data type. The topic will be displayed by using the mso_small window type specified in the pszFile argument. In order for this line of code to work correctly, the mso_small window type must be specified in the HTML Help project file that was used when the Help file was compiled.