About the HTML Help API

The HTML Help application programming interface (API) enables a Windows program to create a help window that displays a help topic. The Windows program has complete control over the type, style, and position of the help window.

The fundamental feature of the HTML Help API is the help window. Through the API commands, you can create a help window that hosts a Microsoft Internet Explorer DLL (Shdocvw.dll) and displays an HTML file that you specify. The help window is owned by the window you specify. As an owned window, a help window automatically stays on top of its owner and closes when the owner is closed.

You define the styles, coordinates, captions, and display state of the help window. This level of control allows you to embed the help window in a non-OLE activated Windows program.

In addition to creating help windows, the HTML Help API commands also enable you to provide:
  • Context-sensitive help.
  • Keyword lookups.
  • Interaction between a Windows program and a compiled help (.chm) file.
  • Control over the Navigation pane in the standard HTML Help Viewer.

ANSI and Unicode versions of the HTML Help API

The HTML Help API supports both ANSI (HtmlHelpA) and Unicode (HtmlHelpW) parameters. Specify the appropriate version of the API in your code:
  • When a program is compiled ANSI, the ANSI version of the API is used by default, allowing you to specify either HtmlHelpA() or HtmlHelp().
  • When a program is compiled Unicode, HtmlHelpW() becomes the default and you can specify either HtmlHelpW() or HtmlHelp().

Note

  • The HTML Help API function is modeled after the WinHelp API function to simplify the process of updating existing programs from WinHelp to HTML Help. However, the HTML Help API command names and parameters are not the same as those in the WinHelp API, and the output file formats are very different.


About the HTML Help API function

The HTML Help API has one function that displays a help window. Using the API commands, you can specify which topic to display in the help window, whether the help window is a three-pane Help Viewer or a pop-up window, and whether the HTML topic file should be accessed via a context ID, an HTML Help URL, or a Keyword link (KLink) lookup.

HTML Help API syntax

HWND HtmlHelp(

              HWND    hwndCaller,

              LPCSTR  pszFile,

              UINT    uCommand,

              DWORD   dwData) ;
Parameter | Description
hwndCaller Specifies the handle (hwnd) of the window calling HtmlHelp(). The help window is owned by this window.

When the help window is closed, HtmlHelp() will return focus to the owner unless the owner is the desktop. If hwndCaller is the desktop, then the operating system determines where focus is returned.

In addition, if HtmlHelp() sends any notification messages from the help window, they are sent to hwndCaller as long as you have enabled notification message tracking in the help window definition.
pszFile Depending on the uCommand value, specifies the file path to either a compiled help (.chm) file, or a topic file within a specified help file.

A window type name can also be specified, preceded with a greater-than (>) character.

If the specified command does not require a file, this value may be NULL.
uCommand | Specifies the command to complete.
dwData | Specifies any data that may be required, based on the value of the uCommand parameter.

Return value

Depending on the specified uCommand and the result, HtmlHelp() returns one or both of the following:
  • The handle (hwnd) of the help window.
  • NULL. In some cases, NULL indicates failure; in other cases, NULL indicates that the help window has not yet been created.

Example

The following example calls the HH_DISPLAY_TOPIC command to open the help file named Help.chm and display its default topic in the help window named Mainwin. Generally, the help window specified in this command is a standard HTML Help Viewer.

HWND hwnd =

   HtmlHelp(

            GetDesktopWindow(),

            "c:\\Help.chm::/Intro.htm>Mainwin",

            HH_DISPLAY_TOPIC,

            NULL) ;


Accessing the HTML Help API

The functionality provided by the HTML Help API resides in the HTML Help ActiveX control (Hhctrl.ocx), which is installed when you set up HTML Help Workshop.

To gain access to the HTML Help API, you link to the Htmlhelp.lib file and include the Htmlhelp.h file in your Windows program. Both of these files are installed on your system when you set up HTML Help Workshop.

About Htmlhelp.lib

Htmlhelp.lib is an export library that exposes the HTML Help API and loads Hhctrl.ocx only when HtmlHelp() is called. In addition, Htmlhelp.lib locates the registered Hhctrl.ocx.

By default, Htmlhelp.lib is located in the following directory:

C:\Program Files\HTML Help Workshop\Lib

About Htmlhelp.h

Htmlhelp.h is a header file that contains the declarations for HtmlHelp(). It must be included in your Windows program.

By default, Htmlhelp.h is located in the following directory:

C:\Program Files\HTML Help Workshop\Include

Notes

  • Copy Htmlhelp.lib to your Lib folder and Htmlhelp.h to your Include folder, so the compiler can find these files.
  • If you are using the HTML Help API with Windows 95 and Internet Explorer 3.x, you must either set up DCOM for Microsoft Windows® 95, version 1.2, or set up Internet Explorer 4.x. Otherwise, the calls that you make to HtmlHelp() may not be processed correctly.


About HTML Help URLs

Many of the HTML Help API commands require that you specify an HTML Help URL in the pszURL parameter.

An HTML Help URL specifies a compiled help (.chm) file or a topic within a help file. Usually, a window type in which to display the HTML Help URL is also specified.

Specifing an HTML Help URL

The following example shows the syntax to display a compiled help file:

    Helpfile.chm[>Window name]

where Helpfile.chm is the name of the compiled help file and Window name is the name of the help window in which you want the topic to appear.

To specify a topic within a compiled help file, use the following syntax:

    Helpfile.chm::/Topic.htm[>Window name]

where Helpfile.chm is the name of the compiled help file, Topic.htm is the name of the HTML file that you want to open and Window name is the name of the help window in which you want the topic to appear.

Specifing a topic file path

A compiled help file retains the folder structure in which it was organized before compilation, unless the option to compile flat has been selected.

For example, if a project is organized in three folders (one for HTML files, one for images, and one for style sheets), the help file will contain those same folders internally. The folder in which the project file resides is considered the root.

To correctly link to a topic file, you must specify the full path. The following example specifies an overview topic:

    Helpfile.chm::/Html/Overview/Topic.htm[>Window name]

where Overview is a folder within the Html folder.

Notes

  • When coding an HTML <A> tag in an HTML file, or when specifying a compiled help file path in the HTML Help ActiveX control, you must include the prefix ms-its, which determines where the help file resides on a user's computer. The prefix ms-its is a pluggable protocol that follows standards set up by the World Wide Web Consortium (W3C). The ms-its protocol works with Microsoft Internet Explorer 4.0 or later, but is not supported in all browsers.
  • The prefix mk:@MSITStore is an earlier version of the ms-its protocol that works with Microsoft Internet Explorer 3.0 or later.
  • The following examples show the syntax to use when including the prefix:

      • ms-its:Helpfile.chm::/Topic.htm[>Window name]

      mk:@MSITStore:Helpfile.chm::/Topic.htm[>Window name]


About window types

A window type is used to display a help topic and to provide users with a way to navigate through a compiled help (.chm) file. A help window is based on an HH_WINTYPE structure and hosts a Microsoft Internet Explorer DLL (Shdocvw.dll) to display a help topic.

Any help window that you create through the HTML Help API is owned by the calling, or parent, program. This allows the help window to stay on top of its parent, yet not be on top of any other program that has focus.

In addition, any help window that you create through the API is bound by the actions of its owner. For example, if the user minimizes the calling program, the help window goes away until the owner is restored. If the user exits the calling program, the help window also closes without requiring any action from its owner. Because the calling program created the help window, it can change the position and properties of that window without affecting the procedural help of any other program.

Defining window types

Either the help author can define window types in the project (.hhp) file using HTML Help Workshop, or the developer can define window types programmatically using the HTML Help API.

A window type definition, such as the standard HTML Help Viewer, includes all of the necessary information about the window such as window style attributes and any navigational elements (such as a table of contents, index, or full-text search). When the window type is created, part of its definition are the file locations of its navigational elements. These navigational elements do not change during the life of the window type.

Window types are specific to the compiled help (.chm) file for which they are created, unless the window type is a global window. Associating a window type with a single compiled help file enables you to create multiple help files that all contain a window type of the same name. For example, you could create fifty compiled help files and define a window type named Main in each file without the different window types conflicting with each other.

The total number of window types that can be defined, and the total number of windows that can be displayed at any one time, is limited solely by available memory and system resources.

Opening a help window

To create or access a help window, the developer can call the HTML Help API or the user can double-click a compiled help (.chm) file.

If a call to HtmlHelp() is made specifying a window type that does not exist, a type will be created using the specified name, but with default properties.

When a user double-clicks a compiled help (.chm) file, the HTML Help executable program (Hh.exe) calls the HTML Help API and the correct help window and topic appears. Accessing a help window using this method is slightly different than invoking a window through the HTML Help API.

By default, when a user double-clicks a help (.chm) file, the file opens in the window type defined in the help project (.hhp) file and displays the default help topic that is also defined in the project file. If no window is defined in the project file, then the default Help Viewer is used. If no default topic is defined in the project file, then a random help topic appears.


About the HTML Help Viewer

The HTML Help Viewer is the standard three-pane help window in which a compiled help (.chm) file appears. Each pane of the Help Viewer can be manipulated through an HH_WINTYPE structure.

The Help Viewer is shown below. Click a pane for more information:

The three-pane Help Viewer

Note

  • The parent help window (hwndHelp) can be used to manipulate the entire Help Viewer and all of its panes.


About global windows

About global window types

A global window is a help window that can be used to display one or more compiled help (.chm) files. Global window types provide backward compatibility for a bug in HTML Help version 1.1/1.1a. Unlike HTML Help v1.2, previous versions did not require a window type to be owned by a specific compiled help (.chm) file.

By default, all window types are specific to the compiled help (.chm) file for which they were defined. That is, a window type is owned by a particular .chm file. However, after you define a global window type, it is not specific to a particular .chm file and can be shared by an unlimited number of .chm files.

A popular use for global window types is to provide a simple help window to display a topic from any .chm file. Global window types are most useful when they do not include a Navigation pane because the data in the Navigation pane does not update when a different .chm is loaded.

Defining global window types

There are two ways to define a global window type:

  • Call the HH_SET_WIN_TYPE command with NULL as the value of the pszFile parameter.
  • Add the prefix $global_ to your window type name.

    • For example, MyWindow is a standard window type name, but $global_MyWindow is a global window type name.

Working with global windows

Like a standard window type, which is associated with a single set of navigational elements (toc, index, and full text search), a global window type is also associated with navigational elements that cannot be modified. Therefore, even though you can use one global window type to view multiple .chm files, the global window will not update the table of contents (.hhc) file, the index (.hhk) file, or any other navigational element to match the current .chm file.

For example, if A.chm and B.chm each have a global window type named $global_main, the two definitions will conflict with each other. In most cases, the first global window type that is created controls the navigational elements that display. This means that if A.chm creates $global_main first, you will see the navigational elements defined in A.chm. However, if B.chm creates $global_main first, you will see the navigational elements defined in B.chm. After a global window is created, the navigational elements cannot be refreshed.

Notes

  • If you plan to use global windows, define only one global window type for a single .chm file and make sure to load that .chm before loading any other .chm that uses the global window type.
  • After you define a global window type, all navigational elements are frozen. Regardless of the .chm file being displayed, the table of contents, index, and search information is based on the first .chm that is loaded in the window.
  • Due to a bug in HTML Help v1.1/1.1a, all window types were treated as global. HTML Help v1.2 provides global window types to ensure backward compatiblity.


About Help Window Types

About pop-up windows

Pop-up windows are based on an HH_POPUP structure and include the following default properties:
  • The pop-up window is positioned relative to the mouse. The calling program can override this with a specific position.
  • The width and height of the pop-up window are determined by the amount of text. The help author or the program can specify an exact width or height.
  • If there is insufficient screen real estate to display the text, the text is clipped. A pop-up window never includes a scroll bar.
  • The pop-up window is dismissed when the user clicks inside or outside the window, presses Esc, or when the pop-up window loses focus.


About the reference section

The reference section provides comprehensive information about how to use the HTML Help API commands, data structures, and notification messages. There are three sections:

  • The commands reference provides syntax descriptions and code examples for all commands (uCommand parameter values) that can be passed to HtmlHelp().
  • The structures reference provides syntax descriptions for all data structures used by HtmlHelp().
  • The notification messages reference provides syntax descriptions for all notification messages sent by HtmlHelp().


About commands

The HTML Help API supports a set of commands (uCommand values) that enable you to access functionality programmatically.

The most basic of the commands is HH_DISPLAY_TOPIC, which enables you to open a compiled help (.chm) file in a specific help window and display a specific topic within the help file.

Commands quick reference

Category Commands

Window types
  • HH_CLOSE_ALL
  • HH_GET_WIN_HANDLE
  • HH_GET_WIN_TYPE
  • HH_SET_WIN_TYPE

Context-sensitive help
  • HH_DISPLAY_TEXT_POPUP
  • HH_DISPLAY_TOPIC
  • HH_HELP_CONTEXT
  • HH_TP_HELP_CONTEXTMENU
  • HH_TP_HELP_WM_HELP

Keyword lookups
  • HH_ALINK_LOOKUP
  • HH_KEYWORD_LOOKUP

Navigation pane
  • HH_DISPLAY_INDEX
  • HH_DISPLAY_SEARCH
  • HH_DISPLAY_TOC

Error messages
  • HH_GET_LAST_ERROR

Contents synchronization
  • HH_SYNC

Single threading
  • HH_INITIALIZE
  • HH_PRETRANSLATEMESSAGE
  • HH_UNINITIALIZE


HH_ALINK_LOOKUP command

Looks up one or more Associative link (ALink) names in a compiled help (.chm) file.

The ALink names to search for, and the action to be taken if no matches are found, are specified in the HH_AKLINK structure.

pszFile | dwData
Specifies the compiled help (.chm) file that contains ALink names. | Points to an HH_AKLINK structure.

Example

HH_AKLINK link;

link.cbStruct =     sizeof(HH_AKLINK) ;

link.fReserved =    FALSE ;

link.pszKeywords =  "open" ;

link.pszUrl =       NULL ;

link.pszMsgText =   NULL ;

link.pszMsgTitle =  NULL ;

link.pszWindow =    NULL ;

link.fIndexOnFail = TRUE ;

HtmlHelp(

          GetDesktopWindow(),

          "c:\\MyHelp.chm",

          HH_ALINK_LOOKUP,

          (DWORD) &link) ;

Return value

The handle (hwnd) of the help window.

Comments

  • You must first call the HH_DISPLAY_TOPIC command before calling this command, to ensure that the help window is created.
  • Help authors insert ALink names into target topic files using the HTML Help Compiler Information feature.
  • An ALink name lookup can also be invoked using the HTML Help ActiveX control ALink command.
  • ALink name/KLink keyword lookups are case sensitive. Multiple keywords are delimited by a semicolon.

See also

HH_KEYWORD_LOOKUP


HH_CLOSE_ALL command

Closes all windows opened directly or indirectly by the calling program.

hwndCaller | pszFile | dwData
Must be NULL. | Must be NULL. | Must be zero.

Example

HtmlHelp(

         NULL,

         NULL,

         HH_CLOSE_ALL,

         0) ;

Return value

NULL.

Comments

  • This command closes any compiled help (.chm) files that are open.
  • This command only closes help windows that have been created by the calling program.


HH_DISPLAY_INDEX command

Selects the Index tab in the Navigation pane of the HTML Help Viewer and searches for the keyword specified in the dwData parameter.

pszFile | dwData
Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. | Specifies the keyword to select in the index (.hhk) file.

Example

HtmlHelp(

         hwnd,

         "cat.chm",

         HH_DISPLAY_INDEX,

         (DWORD)"meow") ;

Return value

The handle (hwnd) of the help window.

See also

HH_DISPLAY_TOC
HH_DISPLAY_SEARCH

link to overview topic About commands


HH_DISPLAY_SEARCH command

Selects the Search tab in the Navigation pane of the HTML Help Viewer and performs a search for the term specified in the pszSearchQuery parameter of the HH_FTS_QUERY structure.

pszFile | dwData
Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. | Specifies a pointer to an HH_FTS_QUERY structure.

Example

HH_FTS_QUERY q ;

q.cbStruct         = sizeof(HH_FTS_QUERY) ;

q.fUniCodeStrings  = FALSE ;

q.pszSearchQuery   = "culture";

q.iProximity       = HH_FTS_DEFAULT_PROXIMITY ;

q.fStemmedSearch   = FALSE :

q.fTitleOnly       = FALSE ;

q.fExecute         = FALSE ;

q.pszWindow        = NULL ;

HtmlHelp(

         hwnd,

         "cat.chm",

         HH_DISPLAY_SEARCH,

         (DWORD)&q) ;

Return value

The handle (hwnd) of the help window.

See also

HH_DISPLAY_INDEX
HH_DISPLAY_TOC

link to overview topic About commands


HH_DISPLAY_TEXT_POPUP command

Opens a pop-up window that displays the contents of one of the following:

  • An explicit text string.
  • A text string based on a resource ID.
  • A text string ID based on a text file contained in a compiled help (.chm) file.

pszFile dwData

To use an explicit text string:

Specify a NULL value.

To use a text string from a resource:

Specify a NULL value.

To use text string from a text file contained in a compiled help file:

Specify the .chm file and the text file within the .chm file. 		Specifies a pointer to an HH_POPUP structure.

Example

HtmlHelp(

         hwndCTRL,

         NULL,

         HH_DISPLAY_TEXT_POPUP,

         (DWORD)&popup) ;

Return value

The handle (hwnd) of the pop-up window.

See also

HH_TP_HELP_CONTEXTMENU
HH_TP_HELP_WM_HELP

link to overview topic About commands


HH_DISPLAY_TOC command

Selects the Contents tab in the Navigation pane of the HTML Help Viewer.

pszFile | dwData
Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. | Specifies NULL or a pointer to a topic within a compiled help file.

Example

HtmlHelp(

         GetDesktopWindow(),

         "c:\\MyHelpFile.chm::/intro.htm",

         HH_DISPLAY_TOC,

         NULL) ;

Return value

The handle (hwnd) of the help window.

Comments

  • This command provides the same functionality as HH_DISPLAY_TOPIC.

See also

HH_DISPLAY_INDEX
HH_DISPLAY_SEARCH
HH_DISPLAY_TOPIC

link to overview topic About commands


HH_DISPLAY_TOPIC command

Opens a help topic in a specified help window.

If a window type is not specified, a default window type is used. If the window type or default window type is open, the help topic replaces the current topic in the window.

pszFile | dwData
Specifies a compiled help (.chm) file, or a specific topic within a compiled help file. To specify a defined window type, insert a greater-than (>) character followed by the name of the window type. | Specifies NULL or a pointer to a topic within a compiled help file.

Example

HWND hwnd =

   HtmlHelp(

             GetDesktopWindow(),

             "c:\\help.chm::/intro.htm>mainwin",

             HH_DISPLAY_TOPIC,

             NULL) ;

Return value

The handle (hwnd) of the help window.

Comments

  • For backward compatibility with WinHelp(), HH_DISPLAY_TOPIC and HH_HELP_FINDER provide the same functionality.
  • A default help window contains only the Topic pane and is not a three-pane Help Viewer.

See also

HH_HELP_CONTEXT


HH_GET_LAST_ERROR command

Returns information about the last error that occurred in the HTML Help ActiveX control (Hhctrl.ocx).

pszFile | dwData
Must be NULL. | A pointer to a HH_LAST_ERROR structure.

Example

USES_CONVERSIONS; // For Unicode to ANSI string conversion

HH_LAST_ERROR lasterror ;

HWND hwnd = HtmlHelp(

                     hOwner,

                     NULL,

                     HH_GET_LAST_ERROR,

                     reinterpret_cast<DWORD>(&lasterror)) ;

// Make sure that HH_GET_LAST_ERROR succeeded.

if (hwnd != 0)

{

    // Only report an error if we found one:

    if (FAILED(lasterror.hr))

    {

        // Is there a text message to display...

        if (lasterror.description)

        {

            // Convert the String to ANSI

            TCHAR* pDesc = OLE2T(lasterror.description) ;

            ::SysFreeString(lasterror.description) ;

            // Display

            MessageBox(hOwner, pDesc,

                       "Help Error", MB_OK) ;

        }

    }

}

Return value

  • On failure, zero.
  • On success, non zero.

Comments

  • There is no user interface (UI) associated with this command. The caller is responsible for returning error codes and text to a UI, such as a message box or a text file, and/or responding to an error.
  • This command reports on a limited range of possible errors. If a call to HtmlHelp() returns NULL, HH_GET_LAST_ERROR may not always report an error.


HH_GET_WIN_HANDLE command

Returns the handle (hwnd) of a specified window type.

pszFile | dwData
Specifies the name of the compiled help (.chm) file in which the window type is defined. | Specifies the name of the window type whose handle you want to return.

Example

HtmlHelp(

         hwndCaller,

         "c:\\MyHelpFile.chm,

         HH_GET_WIN_HANDLE,

         (DWORD) "MyWindowType") ;

Return value

  • The handle (hwnd) of the window type specified in the dwData parameter.
  • NULL, if the help window has not yet been created.

Comments

  • Always specify the name of the compiled help (.chm) file in which the window type is defined when calling an API command. If the window type is not defined in a compiled help file, then specify NULL.

See also

HH_GET_WIN_TYPE
HH_SET_WIN_TYPE

link to overview topic About commands


HH_GET_WIN_TYPE command

Retrieves a pointer to the HH_WINTYPE structure associated with a specified window type.

pszFile dwData

Specifies the name of the window type whose information you want to get and the name of the compiled help (.chm) file in which the window type is defined.

The window name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file it is defined in.

Specifies a pointer to an HH_WINTYPE structure.

Deep copy the structure to which dwData points before modifying the structure.

Example

HH_WINTYPE* pWinType ;

HtmlHelp(

          GetDesktopWindow(),

          "Help.chm>mainwin",

          HH_GET_WIN_TYPE,

          (DWORD) &pWinType) ;

Return value

  • On success, the handle (hwnd) of the parent help window, if the specified window type has been defined.
  • On success, NULL, if the help window has not yet been created.
  • On failure, -1, if the specified window type has not been defined.

Comments

  • Always specify the name of the compiled help file in which the window type is defined when calling an API command. If the window type is not defined in a .chm file, then specify NULL.

See also

HH_SET_WIN_TYPE


HH_HELP_CONTEXT command

Displays a help topic based on a mapped topic ID.

If a window type is not specified, a default window type is used. If the window type or default window type is open, the help topic replaces the current topic in the window.

pszFile | dwData
Specifies the compiled help (.chm) file that contains the mapping information. To specify a defined window type, insert a greater-than (>) character followed by the name of the window type. | Specifies the numeric ID of the topic to display. You must map symbolic IDs of dialog boxes to numeric IDs in the [MAP] section of your project (.hhp) file.

Example

HtmlHelp(

          GetDesktopWindow(),

          "help.chm",

          HH_HELP_CONTEXT,

          5000) ;

Comments

  • A default help window contains only the Topic pane and is not a three-pane Help Viewer.

See also

HH_DISPLAY_TOPIC


HH_INITIALIZE command

This command initializes the help system for use and must be the first HTML Help command called. It returns a cookie which must be used in the HH_UNINITIALIZE call.

HH_INITIALIZE configures HTML Help to run on the same thread as the calling application instead of a secondary thread by setting the global property HH_GPROPID_SINGLETHREAD to VARIANT_TRUE. Running HTML Help on the same thread as the calling application requires the calling application to send messages to HTML Help by calling the HH_PRETRANSLATEMESSAGE command.

pszFile | dwData
Must be NULL. | Specifies a pointer to a DWORD. This call returns a cookie that you must pass as the value of dwData when you call HH_UNINITIALIZE.

Example

DWORD dwCookie = NULL;

HtmlHelp(

         NULL,

         NULL,

         HH_INITIALIZE,

         (DWORD)&dwCookie) ; // Cookie returned by Hhctrl.ocx.

Comments

  • Call HH_INITIALIZE before calling any other command and call HH_UNINITIALIZE only when your application ends. You should call these commands once during the life of your application.

See also

HH_PRETRANSLATEMESSAGE
HH_UNINITIALIZE

link to overview topic About commands


HH_KEYWORD_LOOKUP command

Looks up one or more keywords in a compiled help (.chm) file.

The keywords to search for and the action to be taken if no matches are found are specified in the HH_AKLINK structure.

pszFile | dwData
Specifies the compiled help (.chm) file that contains keywords. | Points to an HH_AKLINK structure.

Example

HH_AKLINK link;

link.cbStruct =     sizeof(HH_AKLINK) ;

link.fReserved =    FALSE ;

link.pszKeywords =  "open" ;

link.pszUrl =       NULL ;

link.pszMsgText =   NULL ;

link.pszMsgTitle =  NULL ;

link.pszWindow =    NULL ;

link.fIndexOnFail = TRUE ;

HtmlHelp(

          GetDesktopWindow(),

          "c:\\myhelp.chm",

          HH_KEYWORD_LOOKUP,

          (DWORD)&link);

Return Value

The handle (hwnd) of the help window.

Comments

  • You must first call the HH_DISPLAY_TOPIC command before calling this command to ensure that the help window is created.
  • Help authors insert keywords into topic files using the HTML Help Compiler Information feature.
  • A keyword lookup can also be invoked using the HTML Help ActiveX control KLink command.
  • ALink Name/Keyword lookups are case sensitive, and multiple keywords are delimited by a semicolon (;).

See Also

HH_ALINK_LOOKUP


HH_PRETRANSLATEMESSAGE command

This command is called in the message loop of your Windows application to ensure proper handling of Windows messages, especially keyboard messages when running HTML Help single thread.

The HTML Help API is not thread safe and must be called from one and only one thread in a process.

pszFile | dwData
Must be NULL. | Points to a Win32 MSG structure.

Example

MSG msg;

while (GetMessage (&msg, NULL, 0, 0))  //Retrieve a message from the

 {                                     //calling thread's message queue

  if (!HtmlHelp (

                 NULL,

                 NULL,

                 HH_PRETRANSLATEMESSAGE,

                 &msg))

    {

     TranslateMessage (&msg);

     DispatchMessage (&msg);

    }

 }

Return value

  • True, if message is translated.
  • False, if command fails.

Comments

  • The MSG structure contains message information from a thread's message queue.
  • Before calling this command, you must first set the global property HH_GPROPID_SINGLETHREAD to VARIANT_TRUE by calling the HH_INITIALIZE command.

See also

HH_INITIALIZE
HH_UNINITIALIZE

link to overview topic About commands


HH_SET_WIN_TYPE command

Creates a new help window or modifies an existing help window at run time.

pszFile dwData

Specifies the name of the window type that you want to create or modify and the name of the compiled help (.chm) file in which the window type is defined.

The window type name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file in which it is defined.

 Points to an HH_WINTYPE structure.

Example

HH_WINTYPE WinType ;

...

HtmlHelp(

          GetDesktopWindow(),

          "..\\help.chm>mainwin",

          HH_SET_WIN_TYPE,

          (DWORD) &WinType) ;

Return value

  • On success, the handle (hwnd) of the help window.
  • On success, NULL, if the help window has not yet been created.
  • On failure, NULL, if the specified window type has not been defined.

Comments

  • Using the window type specified in pszFile to display multiple compiled help files is permitted, but not recommended.
  • Always specify the name of the compiled help file in which the window type is defined when calling an API command. If the window type is not defined in a help file, then specify NULL.
  • If a NULL is passed to HH_SET_WIN_TYPE, the name of the window type is placed into an array and is treated as a global window type. A global window type is a window type that is not specific to a particular compiled help file. Only use global window types if you require backward compatibility for existing applications.

See also

HH_GET_WIN_TYPE


HH_SYNC command

Locates and selects the contents entry for the help topic that is open in the Topic pane of the HTML Help Viewer.

pszFile dwData

Specifies the name of the window type that you want to sync and the name of the compiled help (.chm) file in which the window type is defined.

The window type name must begin with a greater-than (>) character and must be preceded by the name of the compiled help file in which it is defined.

 Specifies a pointer to a topic within a compiled help file. This value is the topic file to which the contents will synchronize.

Example

HtmlHelp(

         hwndCaller,

         "..\\MyHelpFile.chm>wintype",

         HH_SYNC,

         "MyHelpFile.chm::/html\MyTopic.htm") ;

Comments

  • This command requires that you specify a window type.
  • Calling this command is equivalent to clicking the Locate button on the toolbar of the Help Viewer.


HH_TP_HELP_CONTEXTMENU command

Opens a pop-up context menu. Generally used in response to the Windows WM_CONTEXTMENU message. For example, this message is sent when a user right-clicks a dialog box control.

hwndCaller pszFile dwData
Specifies the window handle of the dialog box control for which you want pop-up help to appear. This is typically the control that has focus. Specifies the compiled help (.chm) file, and the text file that contains the pop-up help topics.

By default, the text file is named Cshelp.txt. If Cshelp.txt is located in the root of the compiled help file, then you only need to specify the help file name. If not, you must also specify the relative path.

 Specifies an array of DWORDs containing pairs of dialog box control IDs and help topic IDs. The array must be terminated by zero, as in the following example:

DWORD ids[3] ;

      ids[0] = ControlId ;

      ids[1] = HelpId ;

      ids[2] = 0 ;

Example

HtmlHelp(

         hwndCTRL,

         "c:\\myHelp.chm::/popups\cshelp.txt",

         HH_TP_HELP_CONTEXTMENU,

         (DWORD) ids) ;

Comments

  • The text (.txt) file that contains the pop-up help topics must be included in the [TEXT POPUPS] section of your project (.hhp) file.
  • HH_TP_HELP_CONTEXTMENU does not display the What's This? menu. It does the exact same thing as HH_TP_HELP_WM_HELP.
  • HH_TP_HELP_CONTEXTMENU is very similar to the WinHelp HELP_CONTEXTMENU uCommand parameter.

See also

HH_DISPLAY_TEXT_POPUP
HH_TP_HELP_WM_HELP

link to overview topic About commands


HH_TP_HELP_WM_HELP command

Opens a pop-up help topic. Generally used in response to the Windows WM_HELP message. For example, this message is sent when a user presses F1.

hwndCaller pszFile dwData
Specifies the window handle of the dialog box control for which you want pop-up help to appear. This is typically the control that has focus. Specifies the compiled help (.chm) file, and the text file that contains the pop-up help topics.

By default, the text file is named Cshelp.txt. If Cshelp.txt is located in the root of the compiled help file, then you only need to specify the help file name. If not, you must also specify the relative path.

 Specifies an array of DWORDs containing pairs of dialog box control IDs and help topic IDs. The array must be terminated by 0, as in the following example:

DWORD ids[3] ;

      ids[0] = ControlId ;

      ids[1] = HelpId ;

      ids[2] = 0 ;

Example

HtmlHelp(

         hwndCTRL,

         "c:\\myHelp.chm::/popups\cshelp.txt",

         HH_TP_HELP_WM_HELP,

         (DWORD) ids) ;

Comments

  • The text file that contains the pop-up help topics must be included in the [TEXT POPUPS] section of your project (.hhp) file.
  • HH_TP_HELP_WM_HELP is very similar to the WinHelp HELP_WM_HELP uCommand parameter.

See Also

HH_DISPLAY_TEXT_POPUP
HH_TP_HELP_CONTEXTMENU

link to overview topic About commands


HH_UNINITIALIZE command

This command is called to properly shut down HTML Help. This function should be the last help command the application calls. HH_UNINITIALIZE should not be called during DLL process detach, but during the normal application shutdown process.

pszFile | dwData
Must be NULL. | Specifies a cookie. This is the cookie returned by HH_INITIALIZE.

Example

HtmlHelp(

         NULL,

         NULL,

         HH_UNINITIALIZE,

         (DWORD)dwCookie) ; // Pass in cookie.

Comments

  • Call HH_INITIALIZE before calling any other command and call HH_UNINITIALIZE only when your application ends. You should call these commands once during the life of your application.
  • Do not call HH_UNINITIALIZE before or at process detach.

See also

HH_INITIALIZE


About structures

The HTML Help API provides several objects that you work with using data structures.

When working with a structure, it is recommended that you use a Win32 function such as ZeroMemory, memcpy, or memset to clear out the address space of a structure that has been declared. This ensures that you start with a known quantity before making any modifications. For example, the following code fragment uses memset to make a copy of an HH_WINTYPE structure:

HH_WINTYPE hhWinType;                   //Create new wintype.

           HH_WINTYPE *phhWinType;      //Create a pointer to this wintype.

           memset(phhWinType,           //Requires "memory.h" header be included in the calling application.

                  0,

                  sizeof(HH_WINTYPE));

           HtmlHelp(hwnd,

                    "c:\\help\\MyHelpFile.chm>main",

                    HH_GET_WIN_TYPE,

                    (DWORD)&phhWinType);

           hhWinType = *phhWinType;    //Create a copy so we don't write directly.

Note

  • The Win32 functions such as ZeroMemory,memcpy, or memset do not make a deep copy of the structure. Developer-written copy constructors perform proper deep copies for OOP/C++ classes and objects.

Structures quick reference

Category Structure

Window types
  • HH_POPUP

  • HH_WINTYPE

ALink name/KLink keyword lookups
  • HH_AKLINK

Notification messages
  • HHN_NOTIFY
  • HHNTRACK

Full-text search
  • HH_FTS_QUERY

Error tracking
  • HH_LAST_ERROR


HH_AKLINK structure

Use this structure to specify one or more ALink names or KLink keywords that you want to search for.

If the lookup yields no matching topics, HtmlHelp() checks the values of the following HH_AKLINK members to determine what alternative action to take:

  • fIndexOnFail. If fIndexOnFail is TRUE, the Index tab is selected in the help window specified in pszWindow, and the keyword specified in pszKeyword is selected in the entry field.
  • pszURL. If fIndexOnFail is FALSE, the topic file specified in pszURL appears in the help window specified in pszWindow.
  • pszMsgText and pszMsgTitle. If fIndexOnFail is FALSE and pszURL is NULL, a message box appears using the text and caption specified in pszMsgText and pszMsgTitle.

Used by

  • HH_ALINK_LOOKUP
  • HH_KEYWORD_LOOKUP

HH_AKLINK structure syntax

typedef struct tagHH_AKLINK

{

     int      cbStruct;

     BOOL     fReserved;

     LPCTSTR  pszKeywords;

     LPCTSTR  pszUrl;

     LPCTSTR  pszMsgText;

     LPCTSTR  pszMsgTitle;

     LPCTSTR  pszWindow;

     BOOL     fIndexOnFail;

} HH_AKLINK;

Member | Description
cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to the HTML Help API.
fReserved | This parameter must be set to FALSE.
pszKeywords | Specifies one or more ALink names or KLink keywords to look up. Multiple entries are delimited by a semicolon.
pszUrl | Specifies the topic file to navigate to if the lookup fails. pszURL refers to a valid topic within the specified compiled help (.chm) file and does not support Internet protocols that point to an HTML file.
pszMsgText | Specifies the text to display in a message box if the lookup fails and fIndexOnFail is FALSE and pszURL is NULL.
pszMsgTitle | Specifies the caption of the message box in which the pszMsgText parameter appears.
pszWindow Specifies the name of the window type in which to display one of the following:
  • The selected topic, if the lookup yields one or more matching topics.
  • The topic specified in pszURL, if the lookup fails and a topic is specified in pszURL.
  • The Index tab, if the lookup fails and fIndexOnFail is specified as TRUE.
fIndexOnFail | Specifies whether to display the keyword in the Index tab of the HTML Help Viewer if the lookup fails. The value of pszWindow specifies the Help Viewer.

Comments

  • ALink name and KLink keyword lookups are case sensitive, and multiple keywords are delimited by a semicolon.
  • If the lookup yields one or more matching topics, the topic titles appear in the Topics Found dialog box.


HH_FTS_QUERY structure

Use this structure for full-text search.

Used by

  • HH_DISPLAY_SEARCH

HH_FTS_QUERY structure syntax

typedef struct tagHH_FTS_QUERY

{

     int      cbStruct;

     BOOL     fUniCodeStrings;

     LPCTSTR  pszSearchQuery;

     LONG     iProximity;

     BOOL     fStemmedSearch;

     BOOL     fTitleOnly;

     BOOL     fExecute;

     LPCTSTR  pszWindow;

} HH_FTS_QUERY;

Member | Description
cbStruct | Specifies the size of the structure.
fUniCodeStrings | TRUE if all strings are Unicode.
pszSearchQuery | String containing the search query.
iProximity | Word proximity.
fStemmedSearch | TRUE for StemmedSearch only.
fTitleOnly | TRUE for Title search only.
fExecute | TRUE to initiate the search.
pszWindow | Window to display in.


HH_LAST_ERROR structure

This structure returns the last HtmlHelp() error code and description.

Used by

  • HH_GET_LAST_ERROR

HH_LAST_ERROR structure syntax

typedef struct tagHH_LAST_ERROR

{

     int      cbStruct ;

     HRESULT  hr ;

     BSTR     description ;

} HH_LAST_ERROR ;

Member | Description
cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp().
hr | Specifies the last error code.
description | Specifies a Unicode string containing a description of the error.


HH_POPUP structure

Use this structure to specify or modify the attributes of a pop-up window.

Used by

  • HH_DISPLAY_TEXT_POPUP

HH_POPUP structure syntax

typedef struct tagHH_POPUP

{

     int         cbStruct;

     HINSTANCE   hinst;

     UINT        idString;

     LPCTStr     pszText;

     POINT       pt;

     COLORREF    clrForeground;

     COLORREF    clrBackground;

     RECT        rcMargins;

     LPCTStr     pszFont;

} HH_POPUP;

Member | Description
cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp().
hinst | Instance handle of the program or DLL to retrieve the string resource from. Ignored if idString is zero, or if idString specifies a file name.
idString | Specifies zero, a resource ID, or a topic number in a text file.
pszText | Specifies the text to display if idString is zero.
pt | Specifies (in pixels) where the top center of the pop-up window should be located.
clrForeground | Specifies the RGB value to use for the foreground color of the pop-up window. To use the system color for the window text, specify -1.
clrBackground | Specifies the RGB value to use for the background color of the pop-up window. To use the system color for the window background, specify -1.
rcMargins | Specifies (in pixels) the margins to use on the left, top, right, and bottom sides of the pop-up window. The default for all rectangle members is -1.
pszFont | Specifies the font attributes to use for the text in the pop-up window. Use the following format to specify font family, point size, character set, and font format: facename[, point size[, charset[ BOLD ITALIC UNDERLINE]]] To omit an attribute, enter a comma. For example, to specify bold, 10-pt, MS Sans Serif font, pszFont would be: MS Sans Serif, 10, , BOLD


HH_WINTYPE structure

Use this structure to specify or modify the attributes of a window type.

Window types can be defined by an author in a project (.hhp) file, or they can be defined programmatically using the HTML Help API.

When a HH_WINTYPE structure is passed to HtmlHelp() using the HH_SET_WIN_TYPE command, the HTML Help API makes a private copy of the contents of the structure. The help developer is therefore responsible for freeing memory used by the HH_WINTYPE structure or character arrays within it. The help developer can free memory after calling HH_SET_WIN_TYPE.

Used by

  • HH_SET_WIN_TYPE
  • HH_GET_WIN_TYPE

HH_WINTYPE structure syntax

typedef struct tagHH_WINTYPE

{

     int           cbStruct;

     BOOL          fUniCodeStrings;

     LPCTSTR       pszType;

     DWORD         fsValidMembers;

     DWORD         fsWinProperties;

     LPCTSTR       pszCaption;

     DWORD         dwStyles;

     DWORD         dwExStyles;

     RECT          rcWindowPos;

     int           nShowState;

     HWND          hwndHelp;

     HWND          hwndCaller;

     HWND          hwndToolBar;

     HWND          hwndNavigation;

     HWND          hwndHTML;

     int           iNavWidth;

     RECT          rcHTML;

     LPCTSTR       pszToc;

     LPCTSTR       pszIndex;

     LPCTSTR       pszFile;

     LPCTSTR       pszHome;

     DWORD         fsToolBarFlags;

     BOOL          fNotExpanded;

     int           curNavType;

     int           idNotify;

     LPCTSTR       pszJump1;

     LPCTSTR       pszJump2;

     LPCTSTR       pszUrlJump1;

     LPCTSTR       pszUrlJump2;

} HH_WINTYPE;

Member | Description
cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to HtmlHelp().
fUniCodeStrings | Specifies whether the strings used in this structure are UNICODE.
pszType | A null-terminated string that specifies the name of the window type.
fsValidMembers | Specifies which members in the structure are valid.
fsWinProperties | Specifies the properties of the window, such as whether it is the standard HTML Help Viewer or whether it includes a Search tab.
pszCaption | A null-terminated string that specifies the caption to display in the title bar of the window.
dwStyles | Specifies the styles used to create the window. These styles can be ignored, combined with extended styles, or used exclusively depending on the value of the fsValidMembers and fsWinProperties parameters.
dwExStyles | Specifies the extended styles used to create the window. These styles can be ignored, combined with default styles, or used exclusively depending on the value of the fsValidMembers and fsWinProperties parameters.
rcWindowPos | Specifies the coordinates of the window in pixels. The values are read in the following order: rcWindowPos = {left, top, right, bottom};
nShowState | Specifies the initial display state of the window. Valid values are the same as those for the Win32 API ShowWindow function.
hwndHelp | Specifies the handle of the window if the window has been created.
hwndCaller | Specifies the window that will receive HTML Help notification messages. Notification messages are sent via Windows WM_NOTIFY messages.
idNotify | Specifies a non-zero ID for enabling HTML Help notification messages. This ID is passed as the wParam value of Windows WM_NOTIFY messages.

Members specific to the Help Viewer

Member | Description
hwndToolBar | Specifies the handle of the toolbar.
hwndNavigation | Specifies the handle of the Navigation pane.
hwndHTML | Specifies the handle of the Topic pane, which hosts Shdocvw.dll.
iNavWidth | Specifies the width of the Navigation pane when the Help Viewer is expanded.
rcHTML | Specifies the coordinates of the Topic pane.
pszToc | Specifies the contents (.hhc) file to display in the Navigation pane.
pszIndex | Specifies the index (.hhk) file to display in the Navigation pane.
pszFile | Specifies the default HTML file to display in the Topic pane.
pszHome | Specifies the file or URL to display in the Topic pane when the Home button is clicked.
fsToolBarFlags | Specifies which buttons to include on the toolbar.
fNotExpanded | Specifies that the Help Viewer open with the Navigation pane closed.
curNavType | Specifies the default tab to display on the Navigation pane.
pszJump1 | Specifies the text to display underneath the Jump1 button.
pszJump2 | Specifies the text to display underneath the Jump2 button.
pszUrlJump1 | Specifies the URL to jump to when the Jump1 button is clicked.
pszUrlJump2 | Specifies the URL to jump to when the Jump2 button is clicked.

See Also

link to overview topic About structures


HHN_NOTIFY structure

Use this structure to return the file name of the topic that has been navigated to, or to return the window type name of the help window that has been created.

Used by

  • HHN_NAVCOMPLETE
  • HHN_WINDOW_CREATE

HHN_NOTIFY structure syntax

typedef struct tagHHN_NOTIFY

{

     NMHDR  hdr;

     PCSTR  pszUrl;

} HHN_NOTIFY;

Member | Description
hdr | Standard WM_NOTIFY header.
pszUrl | A multi-byte, zero-terminated string that specifies the topic navigated to, or the name of the help window being created.


HHNTRACK structure

This structure returns the file name of the current topic and a constant that specfies the user action that is about to occur, such as hiding the Navigation pane by clicking the Hide button on the toolbar.

Used by

  • HHN_TRACK

HHNTRACK structure syntax

typedef struct tagHHNTRACK

{

     NMHDR       hdr;

     PCSTR       pszCurUrl;

     int         idAction;

     HH_WINTYPE* phhWinType;

} HHNTRACK;

Member | Description
hdr | Standard WM_NOTIFY header.
pszCurUrl | A multi-byte, zero-terminated string that specifies the current topic (before the action is taken).
idAction | Specifies the action the user is about to take. This is an HHACT_ constant.
phhWinType | A pointer to the current HH_WINTYPE structure.


About notification messages

HTML Help notification messages are sent from a help window to the window that you specify in an HtmlHelp() call. Use notification messages to track a user's activities in a help window. For example, if you want to invoke an action when a user clicks the Refresh button on the toolbar, you could use the HHN_TRACK message.

Notification messages occur for the following events:

  • When a user clicks a button on the toolbar or clicks a tab on the Navigation pane of the HTML Help Viewer, an HHN_TRACK message is sent that identifies the button or tab that was clicked.
  • When a user navigates to a topic, an HHN_NAVCOMPLETE message is sent that identifies the topic navigated to.
  • When a help window is created, an HHN_WINDOW_CREATE message is sent that identifies the window being created.

To enable notification message tracking

HTML Help sends notification messages from help windows that have the following HH_WINTYPE property settings:

  • The value of hwndCaller must be non zero.
  • The value of idNotify must be non zero.
  • A value must be specified for HHWIN_PARAM_PROPERTIES in the fsValidProperties member.
  • A value must be specified for HHWIN_PROP_TRACKING in the fsWinProperties member.

To specify the window that will receive notification messages

Notification messages are sent to the window specified in the hwndCaller parameter of the HtmlHelp() call.

HTML Help notification messages are sent via Windows WM_NOTIFY messages.

Note

  • Notification messages are not sent if the value of hwndCaller is the desktop.

Notification messages quick reference

  • HHN_NAVCOMPLETE
  • HHN_TRACK
  • HHN_WINDOW_CREATE


HHN_NAVCOMPLETE message

Sent when the user successfully navigates to a topic in a compiled help (.chm) file.

Notification code | lParam
HHN_NAVCOMPLETE | A pointer to an HHN_NOTIFY structure.

Comments

  • Make sure that the help window definition includes the settings for notification messages. Otherwise, HTML Help will not send notification messages.


HHN_TRACK message

Sent when a user clicks a button on the toolbar or a tab in the Navigation pane of the HTML Help Viewer. The message is sent before the action is taken.

Notification code | lParam
HHN_TRACK | A pointer to an HHNTRACK structure.

Comments

  • Make sure that the help window definition includes the settings for notification messages. Otherwise, HTML Help will not send notification messages.
  • If the button click results in navigation to a different topic, an HHN_NAVCOMPLETE message is also sent.


HHN_WINDOW_CREATE message

Sent right before a help window is created.

Notification code | lParam
HHN_WINDOW_CREATE | A pointer to an HHN_NOTIFY structure.

Comments

  • Make sure that the help window definition includes the settings for notification messages. Otherwise, HTML Help will not send notification messages.


About the HTML Help API reference

The HTML Help API reference provides information about how to hook up help to a Windows program.

The reference provides the following sections:

  • An Overview section that describes the functionality that the HTML Help API provides. It explains how to call the HTML Help API, its return values, and how to access it from your code. This section also discusses window types and how to define them.
  • A Reference section that provides comprehensive reference information for all supported items in the HTML Help API. These items include commands, data structures, and notification messages.


curNavType parameter

The curNavType member is used to specify which tab in the Navigation pane of the HTML Help Viewer should have focus.

This member can be one of the following values:

Value | Description
HHWIN_NAVTYPE_FAVORITES | Displays the Favorites tab.
HHWIN_NAVTYPE_INDEX | Displays the Index tab.
HHWIN_NAVTYPE_SEARCH | Displays the Search tab.
HHWIN_NAVTYPE_TOC | Displays the Contents tab.


fsToolBarFlags parameter

The fsToolBarFlags member is used to specify which buttons to include on the Toolbar pane of a three-pane Help Viewer.

This member can be a combination of one or more of the following values:

Value | Description
HHWIN_BROWSE_BCK | Previous topic button
HHWIN_BROWSE_FWD | Next topic button
HHWIN_BUTTON_BACK | Back button
HHWIN_BUTTON_CONTENTS | Contents button
HHWIN_BUTTON_EXPAND | Hide/Show button (Hides or shows the Navigation pane.)
HHWIN_BUTTON_FAVORITES | Favorites button
HHWIN_BUTTON_FORWARD | Forward button
HHWIN_BUTTON_HOME | Home button (Navigates to the HTML file specified for the window in pszHome.)
HHWIN_BUTTON_INDEX | Index button
HHWIN_BUTTON_JUMP1 | [Jump1] button
HHWIN_BUTTON_JUMP2 | [Jump2] button
HHWIN_BUTTON_OPTIONS | Options button
HHWIN_BUTTON_PRINT | Print button
HHWIN_BUTTON_REFRESH | Refresh button
HHWIN_BUTTON_SEARCH | Search button
HHWIN_BUTTON_STOP | Stop button
HHWIN_BUTTON_SYNC | Locate button
HHWIN_BUTTON_ZOOM | Zoom button


fsValidMembers parameter

The fsValidMembers member is used when modifying an existing window type, and determines which of the other members should be updated. This parameter can be a combination of one or more of the following values:

Value | Description
HHWIN_PARAM_CUR_TAB | The curNavType member is valid.
HHWIN_PARAM_EXPANSION | The fNotExpanded member is valid.
HHWIN_PARAM_EXSTYLES | The dwExStyles member is valid.
HHWIN_PARAM_NAV_WIDTH | The iNavWidth member is valid.
HHWIN_PARAM_PROPERTIES | The fsWinProperties member is valid.
HHWIN_PARAM_STYLES | The dwStyles member is valid.
HHWIN_PARAM_RECT | The rcWindowPos member is valid.
HHWIN_PARAM_SHOWSTATE | The nShowState member is valid.
HHWIN_PARAM_TB_FLAGS | The fsToolBarFlags member is valid.


fsWinProperties parameter

The fsWinProperties member is used to define various properties for a help window, and is also used to control how the window is created.

This member can be a combination of one or more of the following values:

Value | Description
HHWIN_PROP_AUTO_SYNC | Locates and selects the contents or index entry (depending on whether the Contents or Index tab is selected in the Navigation pane) for the help topic that appears in the Help Viewer. If the topic cannot be located in the Navigation pane, no action is taken.
HHWIN_PROP_CHANGE_TITLE | Changes the title bar of the Help Viewer to match the title of the topic that appears in the Topic pane.
HHWIN_PROP_NAV_ONLY_WIN | Specifies that the window only contain a Navigation pane and toolbar. No topics can appear in this Help Viewer.
HHWIN_PROP_NODEF_EXSTYLES | Specifies that the window use no default extended styles when it is created. If used in combination with the HHWIN_PROP_ONTOP flag, the HHWIN_PROP_ONTOP flag is ignored.
HHWIN_PROP_NODEF_STYLES | Specifies that the window not use default styles when it is created. If this flag is not specified, the window is created with the following default styles: WS_THICKFRAME | WS_OVERLAPPED | WS_VISIBLE
HHWIN_PROP_NOTB_TEXT | Specifies that the buttons on the toolbar of the Help Viewer not contain text below the icon.
HHWIN_PROP_NOTITLEBAR | Creates a window without a title bar.
HHWIN_PROP_NO_TOOLBAR | Creates a window without a toolbar.
HHWIN_PROP_ONTOP | Creates a window that stays on top of all windows on the desktop rather than staying on top of only the calling window.
HHWIN_PROP_POST_QUIT | Specifies that when the window is closed, a WM_QUIT message is posted to the calling program's message queue. This will normally cause the calling program to terminate.
HHWIN_PROP_TAB_ADVSEARCH | Creates a window whose Navigation pane includes a full-text Search tab. If HHWIN_PROP_TAB_SEARCH is not specified as a value for fsWinProperties, no Search tab will appear, whether or not the compiled help (.chm) file includes full-text search information.
HHWIN_PROP_TAB_FAVORITES | Creates a window whose Navigation pane includes a Favorites tab.
HHWIN_PROP_TAB_SEARCH | Creates a window whose Navigation pane includes a Search tab.
HHWIN_PROP_TRACKING | Enables HTML Help notification messages to be sent to the window specified in hwndCaller.
HHWIN_PROP_TRI_PANE | Creates the HTML Help Viewer (with a Topic pane, Navigation pane, and toolbar). Once a window has been created, this flag cannot be used to modify the existing window.
HHWIN_PROP_USER_POS | If the user resizes or repositions the help window, this size/position will be used when the compiled help file is opened again. Without this setting, the window always appears in the same size/position.


tabpos parameter

The tabpos member is used to specify where the tabs are to be placed on the Navigation pane of the HTML Help Viewer.

This member can be one of the following values:

Value | Description
HHWIN_NAVTAB_BOTTOM | Places the tabs at the bottom.
HHWIN_NAVTAB_LEFT | Places the tabs at the left.
HHWIN_NAVTAB_TOP | Places the tabs at the top.


idAction parameter

The idAction member can be one of the following values:

Value | Description
HHACT_BACK | The user clicked the Back button.
HHACT_CONTRACT | The user clicked the Hide button.
HHACT_EXPAND | The user clicked the Show button.
HHACT_FORWARD | The user clicked the Forward button.
HHACT_HOME | The user clicked the Home button.
HHACT_JUMP1 | The user clicked the Jump1 button.
HHACT_JUMP2 | The user clicked the Jump2 button.
HHACT_OPTIONS | The user clicked the Options button.
HHACT_PRINT | The user clicked the Print button.
HHACT_REFRESH | The user clicked the Refresh button.
HHACT_STOP | The user clicked the Stop button.
HHACT_SYNC | The user clicked the Locate button.
HHACT_TAB_CONTENTS | The user clicked the Contents tab.
HHACT_TAB_FAVORITES | The user clicked the Favorites tab.
HHACT_TAB_INDEX | The user clicked the Index tab.
HHACT_TAB_SEARCH | The user clicked the Search tab.
HHACT_ZOOM | The user clicked the Zoom button.