| Feature | Description |
| HHCTRL Version | Adds a button to the HTML page. When clicked, a small message box appears with the version number of the HTML Help ActiveX control. |
| Index | Displays an index file, which is an HTML file with the suffix .hhk. |
| Related Topics | Adds a button to the HTML page. When clicked, a popup menu or window appears with a list of related topics. |
| Shortcut | Adds a shortcut button to the HTML page. When clicked, the button launches a program. |
| Splash Screen | Allows you to specify a bitmap to be displayed when a given document (generally the title page) is displayed. The image stays on the screen for the specified length of time. |
| Table of Contents | Displays a table of contents file, which is an HTML sitemap file with the suffix .hhc. |
| WinHelp Topic | Adds a button to the HTML page. When clicked, the old WinHelp 4.0 engine is invoked and you can bring up help topics in a popup window or frame. |
| Close Window | Adds a button to the HTML page to close the help window. |
Figure 7 HtmlHelp API Commands
| Command | Description |
| HH_DISPLAY_TOPIC | Creates a window containing only a topic pane displaying HTML text. The HTML content is laid out using an MSHTML embedded control. |
| HH_HELP_FINDER | Same as HH_DISPLAY_TOPIC. |
| HH_DISPLAY_TOC | Not supported in version 1.0. |
| HH_DISPLAY_INDEX | Not supported in version 1.0. |
| HH_DISPLAY_SEARCH | Not supported in version 1.0. |
| HH_SET_WIN_TYPE | Sets the parameters for the window created by the HtmlHelp function. Can be used to create a new window or to modify an existing one. You refer to existing windows using their Type Name, which is the string you indicate in the pszType field of the HH_WINTYPE structure when you create the window. |
| HH_GET_WIN_TYPE | Returns the parameters for a given window, specified by Type Name, using the pszType field of the HH_WINTYPE structure. |
| HH_GET_WIN_HANDLE | Returns the handle for a given window, specified by Type Name, using the pszType field of the HH_WINTYPE structure. |
| HH_GET_INFO_TYPES | Not supported in version 1.0. |
| HH_SET_INFO_TYPES | Not supported in version 1.0. |
| HH_SYNC | Syncs the TOC with the topic displayed in the topic pane. If that topic is not found in the TOC, no errors occur and the TOC is left unchanged. There are two ways to make the topic change: by selecting items using the TOC and by clicking links in the topic pane. Using the latter approach, the TOC becomes out of sync with the topic pane. |
| HH_ADD_NAV_UI | Not supported in version 1.0. |
| HH_ADD_BUTTON | Not supported in version 1.0. |
| HH_GETBROWSER_APP | Not supported in version 1.0. |
| HH_KEYWORD_LOOKUP | Not supported in version 1.0. |
| HH_DISPLAY_TEXT_POPUP | Shows text in a simple popup window. The unformatted text is displayed in a single, selectable font. Text can be provided in a String resource or as a null-terminated char array. Displaying text from a file is not supported in version 1.0. |
| HH_HELP_CONTEXT | Displays a help topic in a window. The topic is contained in a compiled HTML (.chm) file. The topic is referenced by the alias assigned to it in the HTML Help project file. |
| HH_TP_HELP_CONTEXTMENU | Displays a text popup window showing the contents of an HTML file. |
| HH_TP_HELP_WM_HELP | Similar to HH_TP_HELP_CONTEXT. |
Figure 9 The HH_WINTYPE Structure
| Field | Description |
| int cbStruct | The size of the structure. |
| BOOL fUniCodeStrings; | TRUE if you pass strings to/from the HtmlHelp function in Unicode. |
| LPCTSTR pszType; | The name of the window type you are creating. Every window is given a name so you can easily refer to it in various HtmlHelp commands. |
| DWORD fsValidMembers; | A bit field of flags, indicating which of the remaining fields of the structure have been set. |
| DWORD fsWinProperties; | Contains various flags regarding the window. This field is only valid if the HHWIN_PARAM_PROPERTIES flag is present in fsValidMembers. |
| LPCTSTR pszCaption; | This is the string displayed on the caption bar of the window. |
| DWORD dwStyles; | By default, HtmlHelp creates windows with the style WS_THICKFRAME | WS_OVERLAPPED | WS_VISIBLE. You can add styles to the default by specifying additional style flags here. If you want to have complete control over the style, you can use the flag HHWIN_PROP_NODEF_STYLES in fsWinProperties. This will force HtmlHelp to use only the style bits you supply, ignoring the default ones. If you are happy with the default style, leave this field NULL. |
| DWORD dwExStyles; | Similar to dwStyles, except applied to the extended style bits. By default, HtmlHelp uses the extended style WS_EX_WINDOWEDGE | WS_EX_LEFT | WS_EX_LTRREADING | WS_EX_RIGHTSCROLLBAR | WS_EX_APPWINDOW. The flag HHWIN_PROP_NODEF_EXSTYLES in fsWinProperties can be used to prevent the default extended styles from being added to the ones you specify. If you are happy with the default style, leave this field NULL. |
| RECT rcWindowPos; | By default, the tri-pane window is displayed near the upper-right corner of the screen. By adding the HHWIN_PARAM_RECT flag to fsValidMembers, you can supply a custom location and size for the window in the rcWindowPos field. |
| int nShowState; | By default, the help window is created visible and in the restored (non-maximized) state. You can also make the window appear maximized or minimized by supplying a value in this field. Accepted values are SW_HIDE, SW_MAXIMIZE, SW_MINIMIZE, SW_RESTORE, and the other values accepted by the ShowWindow API function. If you supply a value in nShowState, make sure you set the HHWIN_PARAM_SHOWSTATE flag in fsValidMembers. |
| HWND hwndHelp; | This field is filled on return by certain HtmlHelp commands, such as HH_SET_WIN_TYPE, indicating the handle of the tri-pane window. |
| HWND hwndCaller; | You must set this field with the handle of the window controlling the help window. The controlling window can receive notification messages from the help window when the user clicks toolbar buttons or changes topics. |
| HH_INFOTYPE* paInfoTypes; | This field allows you to specify an array of ITs for the TOC. Version 1.0 of the HtmlHelp API doesn't support this field. |
| HWND hwndToolBar; | This field returns the handle of the toolbar pane. |
| HWND hwndNavigation; | This field returns the handle of the navigation pane containing the HHCTRL ActiveX navigation control. |
| HWND hwndHTML; | This field returns the handle of the topic pane, which appears in the lower-right portion of the tri-pane window. |
| int iNavWidth; | Use this field to override the default width of the navigator pane containing the TOC. The value is in pixels. If you specify a value, make sure you also set the HHWIN_PARAM_NAV_WIDTH flag in fsValidMembers. The HTML Help documentation incorrectly states that HHWIN_PARAM_NAV_WIDTH affects the rcNavigation member, a defunct remnant from early stages in HTML Help development. |
| RECT rcHTML; | This field returns the bounding rectangle of the topic pane displayed in the lower-right of the tri-pane window. The rectangle is in client coordinates of the tri-pane window. |
| LPCTSTR pszToc; | This is the location of the .hhc sitemap file containing your TOC. You normally create .hhc files using a tool like HHW. The location may be in the local file system or at a remote Web site. For local files, use a URL of the type file://c:/MyHelpSystem/MyTOC.hhc. The navigation pane can contain a TOC, an index, and a Search tab. If you specify more than one item, the navigation pane is created with tabs for each control. If you only specify one item, that item is displayed without using tabs. If you don't want a TOC, set the pszToc field to a blank string or a NULL. |
| LPCTSTR pszIndex; | Similar to the pszToc field, except that index files are contained in .hhk files such as file://c:/MyHelpSystem/MyIndex.hhk. |
| LPCTSTR pszFile; | This is the URL for the initial topic to display. |
| LPCTSTR pszHome; | The URL of the topic to display when the Home button on the help toolbar is clicked. |
| DWORD fsToolBarFlags; | By default, HtmlHelp creates a toolbar with the following buttons: Expand, Back, Print, and Options. The Expand button allows the user to expand or collapse the window, thus showing or hiding the navigator pane. The Options button causes a menu to drop down, displaying the options Back, Forward, Home, Stop, Refresh, and Print. You can change the default toolbar by supplying bit flags in the fsToolBarFlags field. If you use fsToolBarFlags, make sure you set the HHWIN_PARAM_TB_FLAGS flag in fsValidMembers. |
| BOOL fNotExpanded; | Refers to the appearance of the tri-pane window. Expanded means the left navigation pane is visible. Not expanded means the window is shrunk to the size of the topic pane. By default, the tri-pane window is displayed expanded. When using the fNotExpanded field, be sure to set the HHWIN_PARAM_EXPANSION field of fsValidMembers. Whether the tri-pane is displayed expanded or not, the user has the option of toggling the state using the Expand button, which is displayed by default on the toolbar. |
| int curNavType; | Not supported in version 1.0. |
| int tabpos; | Indicates the location of the tabs in the navigation pane. Tabs are used to organize the navigation controls when multiple controls are used. Allowed values are HHWIN_NAVTAB_TOP, HHWIN_NAVTAB_LEFT, and HHWIN_NAVTAB_BOTTOM. To set the tab position, be sure to set the HHWIN_PARAM_TABPOS flag in fsValidMembers. |
| int idNotify; | By supplying a value in this field, you are telling the help window that you want notification messages back. Use NULL if you don't need notifications. |
| BYTE tabOrder[HH_MAX_TABS + 1]; | Specifies the order in which tabs appear in the navigation pane. |
| int cHistory; | Not supported in version 1.0. |
| LPCTSTR pszJump1; | Indicates the caption to display on the Jump1 optional toolbar button. Use NULL if you don't use Jump1 buttons. |
| LPCTSTR pszJump2; | Indicates the caption to display on the Jump2 optional toolbar button. Use NULL if you don't use Jump2 buttons. |
| LPCTSTR pszUrlJump1; | Indicates the URL to jump to when the Jump1 optional toolbar button is clicked. Use NULL if you don't use Jump1 buttons. |
| LPCTSTR pszUrlJump2; | Indicates the URL to jump to when the Jump2 optional toolbar button is clicked. Use NULL if you don't use Jump2 buttons. |
| RECT rcMinSize; | Not supported in version 1.0. |
Figure 10 A Tri-pane Window
#include "htmlhelp.h"
// …
// handles of the various windows created
HWND hwndHelp; // the tri-pane window main frame
HWND hwndToolBar; // top pane
HWND hwndNavigation; // bottom left pane
HWND hwndHTML; // bottom right pane
LPCTSTR windowTypeName = "MyWindow";
LPCTSTR windowCaption = "YourTravels Inc.";
HH_WINTYPE winType = {
sizeof(HH_WINTYPE), // cbStruct
FALSE, // fUniCodeStrings
windowTypeName, // pszType
HHWIN_PARAM_PROPERTIES | // fsValidMembers
HHWIN_PARAM_TABPOS |
HHWIN_PARAM_TB_FLAGS,
HHWIN_PROP_TRI_PANE, // fsWinProperties
windowCaption, // pszCaption
NULL, // dwStyles
NULL, // dwExStyles
{0}, // rcWindowPos
0, // nShowState
hwndHelp, // hwndHelp
m_hWnd, // hwndCaller
NULL, // paInfoTypes
hwndToolBar, // hwndToolBar
hwndNavigation, // hwndNavigation
hwndHTML, // hwndHTML
0, // iNavWidth
{0}, // rcHTML
"file://c:/MyTopics/TableOfContents.hhc", // pszToc
"file://c:/MyTopics/Index.hhk", // pszIndex
"file://c:/MyTopics/Default.htm", // pszFile
"file://c:/MyTopics/Default.htm", // pszHome
HHWIN_BUTTON_EXPAND | // fsToolBarFlags
HHWIN_BUTTON_BACK |
HHWIN_BUTTON_FORWARD |
HHWIN_BUTTON_STOP |
HHWIN_BUTTON_REFRESH |
HHWIN_BUTTON_HOME |
HHWIN_BUTTON_JUMP1 |
HHWIN_BUTTON_JUMP2 |
HHWIN_BUTTON_OPTIONS,
0, // fNotExpanded
0, // curNavType -- not supported in Version 1
HHWIN_NAVTAB_TOP, // tabpos
0, // idNotify
{0}, // tabOrder [HH_MAX_TABS + 1]
0, // cHistory -- not supported in Version 1
"France", // pszJump1
"Italy", // pszJump2
"file://c:/MyTopics/France.htm", // pszUrlJump1
"file://c:/MyTopics/Italy.htm", // pszUrlJump2
{0} // rcMinSize -- not supported in Version 1
};
HWND wnd = HtmlHelp(m_hWnd, NULL, HH_SET_WIN_TYPE, (DWORD) &winType);
wnd = HtmlHelp(m_hWnd, "file://C:/MyTopics/TravelPackages.htm>MyWindow",
HH_DISPLAY_TOPIC, NULL);
Figure 12 HH_WINTYPE Structure Members
| Field to Change | Flag to Set in fsValidMembers |
| fsWinProperties | HHWIN_PARAM_PROPERTIES |
| dwStyles | HHWIN_PARAM_STYLES |
| dwExStyles | HHWIN_PARAM_EXSTYLES |
| rcWindowPos | HHWIN_PARAM_RECT |
| iNavWidth | HHWIN_PARAM_NAV_WIDTH |
| nShowState | HHWIN_PARAM_SHOWSTATE |
| paInfoTypes | HHWIN_PARAM_INFOTYPES |
| fsToolBarFlags | HHWIN_PARAM_TB_FLAGS |
| fNotExpanded | HHWIN_PARAM_EXPANSION |
| tabpos | HHWIN_PARAM_TABPOS |
| tabOrder | HHWIN_PARAM_TABORDER |
| cHistory | HHWIN_PARAM_HISTORY_COUNT |
| curNavType | HHWIN_PARAM_CUR_TAB |
Figure 13 fsWinProperties Member of the HH_WINTYPE Structure
| Flag | Description |
| HHWIN_PROP_ONTOP | Makes the help window stay on top of all other windows. |
| HHWIN_PROP_NOTITLEBAR | Removes the title bar from the help window. |
| HHWIN_PROP_NODEF_STYLES | Don't use default window style on help window. Use the style set in the dwStyles field of HH_WINTYPES. |
| HHWIN_PROP_NODEF_EXSTYLES | Don't use default extended window style on help window. Use the style set in the dwExStyles field of HH_WINTYPES. |
| HHWIN_PROP_TRI_PANE | Use a tri-pane window. The screen is divided into three panes. The top is for the browser toolbar. The bottom-left is the navigation pane containing the TOC control. The bottom-right pane is the content pane, displaying the selected help topic. |
| HHWIN_PROP_NOTB_TEXT | Don't display text on toolbar buttons. |
| HHWIN_PROP_POST_QUIT | Post a WM_QUIT message to the owner application when the help window is closed. |
| HHWIN_PROP_AUTO_SYNC | Automatically update the TOC when the user changes topics if the topic is in the TOC. |
| HHWIN_PROP_TRACKING | Send notification messages to the calling window. |
| HHWIN_PROP_TAB_SEARCH | Add a Search tab to the navigation pane. |
| HHWIN_PROP_TAB_HISTORY | Not supported in version 1.0. |
| HHWIN_PROP_TAB_FAVORITES | Not supported in version 1.0. |
| HHWIN_PROP_CHANGE_TITLE | Display the title of the selected topic in the caption bar of the help window. |
| HHWIN_PROP_NAV_ONLY_WIN | Display only the navigation and toolbar panes, not the topic pane. |
| HHWIN_PROP_NO_TOOLBAR | Don't show the toolbar pane. |
Figure 15 Handling Notifications
const int ID_MYHELPWINDOW = 100; // used in idNotify
// handles of the various windows created
HWND hwndHelp; // the tri-pane window main frame
HWND hwndToolBar; // top pane
HWND hwndNavigation; // bottom-left pane
HWND hwndHTML; // bottom-right pane
LPCTSTR windowTypeName = "MyWindow";
LPCTSTR windowCaption = "YourTravels Inc.";
const int ID_MYHELPWINDOW = 100; // used in idNotify
HH_WINTYPE winType = {
sizeof(HH_WINTYPE), // cbStruct
FALSE, // fUniCodeStrings
windowTypeName, // pszType
HHWIN_PARAM_PROPERTIES |
HHWIN_PARAM_TB_FLAGS, // fsValidMembers
HHWIN_PROP_TRI_PANE | // fsWinProperties
HHWIN_PROP_TRACKING,
windowCaption, // pszCaption
NULL, // dwStyles
NULL, // dwExStyles
{0}, // rcWindowPos
0, // nShowState
hwndHelp, // hwndHelp
m_hWnd, // hwndCaller
NULL, // paInfoTypes
// HHWIN_PROP_TRI_PANE stuff
hwndToolBar, // hwndToolBar
hwndNavigation, // hwndNavigation
hwndHTML, // hwndHTML
0, // iNavWidth
{0}, // rcHTML
"file://c:/MyTopics/TableOfContents.hhc", // pszToc
"file://c:/MyTopics/Index.hhk", // pszIndex
"file://c:/MyTopics/Default.htm", // pszFile
"file://c:/MyTopics/Default.htm", // pszHome
HHWIN_BUTTON_EXPAND | // fsToolBarFlags
HHWIN_BUTTON_BACK |
HHWIN_BUTTON_FORWARD |
HHWIN_BUTTON_STOP |
HHWIN_BUTTON_REFRESH |
HHWIN_BUTTON_HOME,
0, // fNotExpanded
0, // curNavType -- not supported in Version 1
HHWIN_NAVTAB_TOP, // tabpos
ID_MYHELPWINDOW, // idNotify
{0}, // tabOrder [HH_MAX_TABS + 1]
0, // cHistory -- not supported in Version 1
NULL, // pszJump1
NULL, // pszJump2
NULL", // pszUrlJump1
NULL, // pszUrlJump2
{0} // rcMinSize -- not supported in Version 1
};
// create the Helpwindow
void CHHTestDlg::OnButtonHtmlTest()
{
HWND wnd = HtmlHelp(m_hWnd, NULL, HH_SET_WIN_TYPE, (DWORD) &winType);
wnd = HtmlHelp(m_hWnd, "file://C:/MyTopics/TravelPackages.htm>MyWindow",
HH_DISPLAY_TOPIC, NULL);
}
// Handle notifications from the Help window
BOOL CHHTestDlg::OnNotify(WPARAM wParam, LPARAM lParam, LRESULT* pResult)
{
/* This message uses the following structures:
typedef struct tagHHN_NOTIFY
{
NMHDR hdr;
PCSTR pszUrl;
} HHN_NOTIFY;
typedef struct tagNMHDR {
HWND hwndFrom;
UINT idFrom;
UINT code;
} NMHDR;
typedef struct tagHHNTRACK
{
NMHDR hdr;
PCSTR pszCurUrl;
int idAction;
} HHNTRACK;
*/
if ( (wParam != ID_MYHELPWINDOW || !lParam) )
return CDialog::OnNotify(wParam, lParam, pResult);
NMHDR* header = (NMHDR*) lParam;
if (header->code == HHN_NAVCOMPLETE) {
HHN_NOTIFY* helpNotification = (HHN_NOTIFY*) lParam;
char msg [200];
sprintf(msg, "The user switched to page %s",
helpNotification->pszUrl);
MessageBox(msg);
}
// these notifications aren't supported in Version 1
// of HTML Help
else if (header->code == HHN_TRACK) {
HHNTRACK* trackHeader = (HHNTRACK*) lParam;
char msg [200];
sprintf(msg, "Button ID = %d, going to page %s",
trackHeader->idAction, trackHeader->pszCurUrl);
MessageBox(msg);
}
return CDialog::OnNotify(wParam, lParam, pResult);
}
Figure 17 Adding a Shortcut
<HTML>
<BODY BGCOLOR=#FFFFEF>
<B><FONT FACE="Arial" SIZE=0.8><P>To turn PC Card sound effects on or off</P></FONT></B>
<FONT FACE="Arial" SIZE=0.6>
<P>1 Click here
<OBJECT id=hhctrl type="application/x-oleobject"
classid="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
codebase="hhctrl.ocx#Version=4,71,1111,0"
width=100
height=100>
<PARAM name="Command" value="ShortCut">
<PARAM name="Button" value="Bitmap:SHORTCUT">
<PARAM name="Item1" value=",C:/MyTopics/TellUs.Exe,">
</OBJECT>
to display PCMCIA properties.</P>
<P>2 On the Global Settings tab, click the check box to turn sound effects on or off.</P>
</FONT>
<P><B>
<FONT FACE="Arial" SIZE=0.8>Tip</FONT></B><P>
<FONT FACE="Arial" SIZE=0.6>
<UL>
</B><LI>If the PC Card (PCMCIA) wizard appears when you click the button in
step 1, complete the wizard. After restarting your computer, double-click the
PC Card (PCMCIA) icon in the Control Panel, and then click the Global Settings
tab.</LI></UL></FONT>
</BODY>
</HTML>
Figure 18 WinHelp File Conversion
| File Description | WinHelp File Type | to HTML Help File Type |
| Project Files | .hpj | .hhp |
| Topic Files | .rtf | .htm |
| Image Files | .bmp and .wmf | .gif and .jpg |
| TOC Files | .cnt | .hhc |