About the HTML Help API function

HTML Help API

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) ;

Comments

When using the HTML Help API, set the stack size of the hosting executable to at least 100k. If the defined stack size is too small, then the thread created to run HTML Help will also be created with this stack size, and failure could result. Optionally, you can remove /STACK from the link command line, and remove any STACK setting in the executable's DEF file (default stack size is 1MB in this case). You can also you can set the stack size using the /Fnumber compiler command (the compiler will pass this to the linker as /STACK).


link to overview topic About the HTML Help API