 | ||
|
| ||
| ||
|
| ||
Microsoft Corporation
Updated: June 23, 1998
Contents
Overview
Syntax
Commands
HH_WINTYPE Structure
HH_POPUP Structure
Tri-Pane Windows
Notification Messages
HHNNAVCOMPLETE Structure
HHNTRACK Structure
The HtmlHelp application programming interface (API) makes it possible to display a Help window from a program. By using this function, the program has complete control over the type, style, and position of the Help window.
The functionality provided by the HtmlHelp API resides in the file named hhctrl.ocx. A program can call this functionality directly by linking to the hhctrl.lib file, or indirectly by linking to the htmlhelp.lib file. If the program links to hhctrl.lib, hhctrl.ocx and all DLLs required by HHCTRL will be loaded when the program starts. If the program links to htmlhelp.lib, no DLLs will be loaded until the program calls the HtmlHelp API.
The HtmlHelp API is modeled after the WinHelp API function to make it easy to convert existing programs to use HTML Help instead of WinHelp.
In its simplest form, the HtmlHelp API creates a child window, which in turn hosts shdocvw.dll and displays the HTML file you specify. The window is a child of whatever parent window you specify. It will automatically stay on top of that parent window, and close when the parent window is closed. You can also take complete control of the window creation process by defining the window styles, coordinates, captions, and display state. This means you can even embed shdocvw.dll in a non-OLE activated program.
HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData);
| Member | Description |
| hwndCaller | Specifies the handle of the window calling the HtmlHelp API. When the HTML Help window exits, the HtmlHelp() function will return focus to the hwndCaller parameter unless this parameter points to the desktop. In that case, the focus will be set by the operating system. In addition, if the HtmlHelp API call results in messages being sent from the HTML Help window, they will be sent to this window handle. |
| pszFile | Specifies an HTML file, a URL, a compiled HTML file, or a window definition (preceded with a ">" character). If the command being used does not require a file or URL, this value may be NULL. |
| uCommand | Specifies the action to perform. See the Commands section for details. |
| dwData | Specifies any data that may be required based on the value of the uCommand parameter. |
This is a basic call to the HTML Help API. Passing a standard window handle for the hwndCaller parameter will make the HTML Help window a child of your application.
HWND HtmlHelp(Window(), "c:\\dump\\myfile.chm", HH_DISPLAY_TOPIC, NULL);
Passing in GetDesktopWindow() for the hwndCaller parameter makes the HH window a child of the desktop, instead a child of your application.
HWND HtmlHelp(GetDesktopWindow(), "c:\\dump\\myfile.chm", HH_DISPLAY_TOPIC, NULL);
Keep in mind that HTML Help is still in the same process as your application, so when your application exits, the HTML Help window does also.
The uCommand parameter determines what action to take and what needs to be supplied for the pszFile and dwData parameters. The following table lists the commands, actions, and required parameters:
| Command | Description | pszFile | dwData |
| HH_DISPLAY_TOPIC | Displays an HTML file. If a window type is not specified, a default window type is used. If the window type or default window type is already being displayed, the HTML file will replace what is currently being displayed. | File, URL, or compiled HTML file. If the greater-than character (>) is used, it must be followed by the name of the window type in which to display the topic. | May be zero or a pointer to a file, URL, or compiled HTML file. This parameter may be a pointer to a filename within a compiled HTML file if the pszFile parameter points to that compiled HTML file. |
| HH_DISPLAY_TEXT_POPUP | Displays text from a string resource or a text string. | For version 1, this parameter must be NULL. | Points to an HH_POPUP structure. |
| HH_SET_WIN_TYPE | Creates a new window type, or modifies an existing window type. | Ignored. | Points to an HH_WINTYPE structure. |
| HH_GET_WIN_TYPE | Retrieves a pointer to the HH_WINTYPE structure associated with a window type. If the window type has not been specified, the return value is -1. If the window type has been specified, the return value is the handle of the window (NULL if the window hasn't been created). | Specifies the name of the window. The window name must begin with a ">" character, and may optionally be preceded by the name of the compiled HTML file. | Points to the address of a PHH_WINTYPE pointer that will be filled in before the HtmlHelp API returns. Do not modify any strings in the structure to which this points. |
| HH_GET_WIN_HANDLE | Retrieves the handle of the window associated with the specified window type. If the window type has not been created, the return value is NULL. | Ignored. | Points to the name of the window type. |
| HH_HELP_CONTEXT | Displays a particular topic in a compiled HTML file. If a window type is not specified, a default window type is used. If the window type or default window type is already being displayed, the HTML file will replace what is currently being displayed. | Specifies compiled HTML file. If the greater-than character (>) is used, it must be followed by the name of the window type in which to display the topic. | Specifies the topic number. This number must have been aliased in the HTML Help Project file to the actual HTML file to display. Negative numbers are not allowed. |
| HH_TP_HELP_CONTEXTMENU | Displays a text pop-up window. If used for context-sensitive help, the caller should be specifying both the .chm file and the .txt file that contains the context-sensitive help. | Specifies the compiled HTML file, and the text file within that file that contains the text pop-up. | Specifies an array of DWORDs containing pairs of dialog ids and help ids. |
| HH_TP_HELP_WM_HELP | Displays a text pop-up window. For this call, the hwnd parameter is the window handle of the control. If used for context-sensitive help, the caller should be specifying both the .chm file and the .txt file that contains the context-sensitive help. | Specifies the compiled HTML file, and the text file within that file that contains the text pop-up. | Specifies an array of DWORDs containing pairs of dialog ids and help ids. |
Window types can be defined by an author and stored in a compiled HTML file, or they may be defined by a program that uses the HtmlHelp API. Each window type should have a unique name. If a call to the HtmlHelp API is made specifying a window type that does not exist, a type will be created using the indicated type name, but with default properties.
When a HH_WINTYPE structure is passed to the HtmlHelp API using the HH_SET_WIN_TYPE command, the HtmlHelp API makes a private copy of all its contents. The help developer is therefore responsible for freeing memory used by their HH_WINTYPE structure or character arrays within it. The help developer can free this memory at any time after calling HH_SET_WIN_TYPE:
Back to top
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;
HH_INFOTYPE* apInfoTypes;
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 tabpos;
int idNotify;
BYTE tabOrder[HH_MAX_TABS + 1];
int cHistory;
LPCTSTR pszJump1;
LPCTSTR pszJump2;
LPCTSTR pszUrlJump1;
LPCTSTR pszUrlJump2;
RECT rcMinSize;
} HH_WINTYPE;
| Member | Description |
| cbStruct | Specifies the size of the structure. This value must always be filled in before passing the structure to the HtmlHelp API. |
| fUniCodeStrings | Specifies whether the strings used in this structure are UNICODE. |
| pszType | Specifies a null-terminated string containing the name of the window type. |
| fsValidMembers | Specifies which members in the structure are valid. See below for additional information about this member, and a list of values that can be used. |
| fsWinProperties | Specifies the properties of the window. Note: In order for the window type to display a search tab, HHWIN_PROP_TAB_SEARCH must be specified. See below for additional information about this member, and a list of values that can be used. |
| pszCaption | Specifies a null-terminated string that contains 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 default styles, or used exclusively depending on the value of fsValidMembers and fsWinProperties. |
| 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 fsValidMembers and fsWinProperties. |
| rcWindowPos | Specifies the coordinates of the window. When setting this value, any negative member will be ignored. For example, to change the position, but not the width and height, the left and top positions would be set and the right and bottom RECT members would be set to -1. Note: For the current version of HTML Help, negative values are invalid. Using negative numbers can cause unpredictable results. For now, please make sure to specify valid, positive values for all rcWindowPos coordinates. |
| nShowState | Specifies the initial display state of the window. |
| hwndHelp | Specifies the handle of the window if the window has been created. |
| hwndCaller | Specifies the window to send messages to. |
| papInfoTypes | This member is ignored in version 1 and must be set to NULL. |
| hwndToolBar | Specifies the handle of the window containing the toolbar in a tri-pane window. |
| hwndNavigation | Specifies the handle of the window containing the current navigation UI in a tri-pane window. |
| hwndHTML | Specifies the handle of the window that displays HTML files in a tri-pane window. This window is a host for Shdocvw.dll. |
| iNavWidth | Specifies the width of the navigation pane in a tri-pane window when the tri-pane window is expanded. |
| rcHTML | Specifies the coordinates of the HTML pane in a tri-pane window. |
| pszToc | In a tri-pane window, specifies the file or URL to use for the table of contents. |
| pszIndex | In a tri-pane window, specifies the file or URL to use for the index. |
| pszFile | In a tri-pane window, specifies the file or URL to display in the right pane. This file will be displayed if the user clicks the Home button on the toolbar. |
| pszHome | In a tri-pane window, specifies the file or URL to display in the right pane when the Home button is clicked. |
| fsToolBarFlags | In a tri-pane window, determines which buttons will be displayed in the toolbar pane. See the section below describing HHWIN_BUTTON constants. |
| fNotExpanded | In a tri-pane window, determines whether the navigational pane is to be shown when the window is first created. |
| curNavType | Specifies which navigational UI is displayed in the navigational pane of a tri-pane window. This member is ignored in version 1.x. |
| tabpos | Specifies where the tabs are to be placed in the navigational pane of a tri-pane window. The tabs can be set on the top, left, or bottom. |
| idNotify | Specifies the ID to use as the WPARAM member of WM_NOTIFY messages. |
| tabOrder | Specifies the order that tabs appear in the navigation pane of a tri-pane window. Set the HHWIN_PARAM_TABORDER flag if you use this member. The first 10 positions are reserved for default HTML Help tabs: contents, index, search, history, favorites, and reserved 1 through 5 (for future expansion). Each byte represents the numeric position, starting with zero. For example, to put the Index tab first and the Contents tab second, you would specify tabOrder[HH_TAB_CONTENTS] = 1, and tabOrder[HH_TAB_INDEX] = 0. This parameter is ignored in version 1.x. |
| cHistory | Specifies the number of History items to keep. This member is ignored in version 1. |
| 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. |
| rcMinSize | Specifies the minimize size the window may be resized to by the user. This member is ignored in Version 1. x. |
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:
| HHWIN_PARAM_PROPERTIES | The fsWinProperties member is valid. |
| HHWIN_PARAM_STYLES | The dwStyles member is valid. |
| HHWIN_PARAM_EXSTYLES | The dwExStyles member is valid. |
| HHWIN_PARAM_RECT | The rcWindowPos member is valid. |
| HHWIN_PARAM_NAV_WIDTH | The rcNavigation member is valid. |
| HHWIN_PARAM_SHOWSTATE | The nShowState member is valid. |
| HHWIN_PARAM_INFOTYPES | The apInfoTypes member is valid. |
| HHWIN_PARAM_TB_FLAGS | The fsToolBarFlags member is valid. |
| HHWIN_PARAM_EXPANSION | The fExpanded member is valid. |
| HHWIN_PARAM_TABPOS | The tabpos member is valid. |
| HHWIN_PARAM_TABORDER | The tabOrder member is valid. |
| HHWIN_PARAM_HISTORY_COUNT | The cHistory member is valid. |
| HHWIN_PARAM_CUR_TAB | The curNavType member is valid. |
The fsWinProperties member is used to define various properties for the 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:
| HHWIN_PROP_ONTOP | Specifies that the window is to be kept on top of every window on the desktop instead of just being on top of the caller's window. |
| HHWIN_PROP_NOTITLEBAR | Specifies that the window should not contain a title bar. |
| HHWIN_PROP_NODEF_STYLES | Specifies that no default styles should be used when creating the window. If this flag is not specified, a window will be created with the following default styles:
WS_THICKFRAME | WS_OVERLAPPED | WS_VISIBLE |
| HHWIN_PROP_NODEF_EXSTYLES | Specifies that no default extended styles should be used when creating the window. If this flag is used with the HHWIN_PROP_ONTOP flag, the HHWIN_PROP_ONTOP flag will be ignored. |
| HHWIN_PROP_TRI_PANE | Specifies that a tri-pane window is to be created. Once a window has already been created, this flag cannot be used to change the existing window. |
| HHWIN_PROP_NOTB_TEXT | Specifies that the toolbar of a tri-pane window should not contain text below the buttons. |
| HHWIN_PROP_POST_QUIT | Specifies that when the Help 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_AUTO_SYNC | Specifies that if the contents or index navigational pane is currently displayed, and then the user jumps to a different HTML file, the contents or index will scroll to the entry or keyword that points to the current URL. If the URL cannot be located in the current navigational pane, no action will be taken. |
| HHWIN_PROP_TRACKING | Specifies that tracking notification messages should be sent to the caller. |
| HHWIN_PROP_TAB_SEARCH | Specifies that a full-text Search tab is to be included as one of the navigation panes in a tri-pane window. Note: If HHWIN_PROP_TAB_SEARCH is not specified as a value for fsWinProperties, no Search tab will be displayed -- whether or not the .chm includes full text search information. |
| HHWIN_PROP_TAB_HISTORY | Specifies that a History tab is to be included as one of the navigation panes in a tri-pane window. This property is not supported in version 4.0 or HTML Help Workshop. |
| HHWIN_PROP_TAB_FAVORITES | Specifies that a Favorites tab is to be included as one of the navigation panes in a tri-pane window. This property is not supported in version 4.0 or HTML Help Workshop. |
| HHWIN_PROP_CHANGE_TITLE | Specifies that the title bar of the HTML Help window should reflect the title of any HTML file displayed in the HTML pane. |
| HHWIN_PROP_NAV_ONLY_WIN | Specifies that only a navigation and toolbar window should display -- no HTML files can be displayed in this window. |
| HHWIN_PROP_NO_TOOLBAR | Specifies that the window should be created without a toolbar. |
The fsToolBarFlags member is used to specify which buttons to display in the toolbar. This member can be a combination of one or more of the following values:
| HHWIN_BUTTON_EXPAND | Expand/Contract button (for the navigational pane) |
| HHWIN_BUTTON_BACK | Back button |
| HHWIN_BUTTON_FORWARD | Forward button |
| HHWIN_BUTTON_STOP | Stop button |
| HHWIN_BUTTON_REFRESH | Refresh button. |
| HHWIN_BUTTON_HOME | Home button (to the HTML file defined for the window) |
| HHWIN_BUTTON_JUMP1 | Jump1 button |
| HHWIN_BUTTON_JUMP2 | Jump2 button |
| HHWIN_BUTTON_OPTIONS | Options button |
The curNavType member is used to specify which navigational UI tab should be activated. This member can be one of the following values:
| HHWIN_NAVTYPE_TOC | Displays the Contents tab |
| HHWIN_NAVTYPE_INDEX | Displays the Index tab |
| HHWIN_NAVTAB_TOP | Places the tabs at the top |
| HHWIN_NAVTAB_LEFT | Places the tabs at the left |
| HHWIN_NAVTAB_BOTTOM | Places the tabs at the bottom |
The HH_POPUP structure is used when displaying a text-only pop-up window. Because of the speed in which they display, text-only pop-ups should be used when no formatting is needed. The text to display can reside in a resource file, in a text string, or in a text file.
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 the HtmlHelp API. |
| hinst | Instance handle of the program or .dll file to retrieve the string resource from. Ignored if idString is zero, or a filename was passed to the HtmlHelp API. |
| idString | Specifies either a resource ID or a topic number in a text file. |
| pszText | Specifies the text to display if idString is zero. |
| pt | Specifies where the top center of the pop-up should be located. |
| clrForeground | Specifies the RGB value to use for the foreground color. If this value is -1, the system color for window text will be used. |
| clrBackground | Specifies the RGB value to use for the background color. If this value is -1, the system color for window background will be used. |
| rcMargins | Specifies the margins to use on the left, top, right, and bottom sides of the pop-up. The default for all rectangle members is -1. |
| pszFont | Specifies an optional text string containing: facename[,point size[,charset[,color[, BOLD ITALIC UNDERLINE]]]]. This string specifies a font, its point size, its character set, its color, and various attributes. Options can be omitted by simply specifying the next comma. For example, to create a bold, 10-pt MS Sans Serif font, the parameter value would be: MS Sans Serif, 10, , , BOLD |
Note In version 1, pop-up text specified in this structure can only reside in a resource file or a text string. It is not possible to use a text file as you can with the HH_TP_HELP commands.
A tri-pane window consists of three panes (child windows) -- a toolbar pane at the top, a navigation pane on the left, and an HTML pane that hosts shdocvw.dll on the right. The navigation pane may be expanded or contracted by the user. Expansion always enlarges the window by a fixed amount --that amount is 250 pixels by default, but can be set by the author or programmer as part of the window type definition.
If more than one navigational UI is specified, a tabbed control will be used to switch between the navigational UI. By default, the tabs for this control will be on top -- but a window may be defined to have the tabs on the left or the bottom.
If you want to use an embedded window that takes advantage of the toolbar pane, but does not have a navigation pane, do not include the Expand/Collapse button. For example, the Help tab of the Project Editor in HTML Help Workshop (displayed when a project is loaded) uses a tri-pane window without the navigation pane.
If the idNotify member of the HH_WINTYPE structure is non-zero, WM_NOTIFY messages will be sent to the last caller of the HTML Help window.
| Notification | lParam | Description |
| HHN_NAVCOMPLETE | HHNNAVCOMPLETE* | Sent when the user successfully navigates to a URL. |
| HHN_TRACK | HHNTRACK* | Sent if the window has tracking properties and the user uses a toolbar button or switches navigational tabs. The message is sent before the action is taken. If the action changes to a different URL, a HHN_NAVCOMPLETE notification will be sent after this notification. |
typedef struct tagHHNNAVCOMPLETE {
NMHDR hdr;
PCSTR pszUrl;
} HHNNAVCOMPLETE;
| Member | Description |
| hdr | Standard WM_NOTIFY header. |
| pszUrl | Multi-byte, zero-terminated string specifying the URL that has been navigated to. |
typedef struct tagHHNTRACK
{
NMHDR hdr;
PCSTR pszCurUrl; // Multi-byte, null-terminated string
int idAction; // HHACT_ value
} HHNTRACK;
| Member | Description |
| hdr | Standard WM_NOTIFY header. |
| pszCurUrl | Multi-byte, zero-terminated string specifying the current URL before the action is taken. |
| idAction | Specifies the action the user is about to take. This is one of the HHACT_ constants described below. |
| Value | Description |
| HHACT_EXPAND | The user is about to expand the navigation pane. |
| HHACT_CONTRACT | The user is about to contract the navigation pane. |
| HHACT_BACK | The user clicked the Back button. |
| HHACT_FORWARD | The user clicked the Forward button. |
| HHACT_STOP | The user clicked the Stop button. |
| HHACT_REFRESH | The user clicked the Refresh button. |
| HHACT_HOME | The user clicked the Home button. |
| HHACT_SYNC | The user clicked the Syncbutton. |
| HHACT_OPTIONS | The user clicked the Options button. |
| HHACT_PRINT | The user clicked the Print button. |
| HHACT_TAB_CONTENTS | The user switched to the Contents tab. |
| HHACT_TAB_INDEX | The user switched to the Index tab. |
| HHACT_TAB_FIND | The user switched to the Find tab. |
| HHACT_TAB_HISTORY | The user switched to the History tab. |
| HHACT_TAB_FAVORITES | The user switched to the Favorites tab. |
Did you find this material useful? Gripes? Compliments? Suggestions for other articles? Write us!
© 1999 Microsoft Corporation. All rights reserved. Terms of use.