CHHCtrl

The source code for CHHCtrl and CItsFile is provided as is. No warranty of any form is implied. You may use and modify the code as you see fit, including redistributing any products derived from the code.

What is CHHCtrl?

CHHCtrl is an MFC class designed for placing an embedded help window inside of a dialog, property sheet, or window. The CHHCtrl class hosts shdocvw directly rather then using the HtmlHelp API. With CHHCtrl, you get access to all IWebBrowser methods, along with the following additional support for HTML Help CHM files:

Mapped IDs -- this allows you to use numeric values that your help author can alias into the HTML file he/she chooses. Using mapped ids means the author can change what file is displayed without having to recompile your project.
CHM file searching -- this uses the same algorithm as HTML Help for locating your CHM file so you don't need to give a path to the CHM file.

Like the HtmlHelp API, CHHCtrl lets you specify a toolbar with the following differences:

You can choose to display or not display text labels.
You can add any custom buttons you want.
The Home button will appear before the Back button (more appropriate for embedded help windows)

Incorporating CHHCtrl into your project.

The first thing you need to do is merge the resource files into your project. This includes merging two bitmaps and a string resource. You can either merge these in by hand into your existing resource file, or you can #include chhctrl.rc2.

After merging or including the resources, you need to add hhctrl.cpp and cits.cpp to your project. The cits.cpp file is used to read the map section out of a CHM file. The hhctrl.cpp file is where the hosting is handled.

If your project isn't ole enabled, you need to add AfxOleInit to the InitInstance function of your application.

Adding an embedded help window to a dialog.

In your dialog template, create a static text control. Set the placement and size to be where you want the embedded help window to be, including the toolbar if you are going to use one. If you use a sunken style then it will be easier to visually see where the embedded help window will appear. In the header file for your dialog, #include "hhctrl.h". To the dialog class, add the member "CHHCtrl m_hhctrl". In either DoDataExchange() or OnInitDialog(), add the following code:

m_hhctrl.ReplaceControl(this, static text id, buttons (if any), home url if HHCTRL_BTN_HOME is used);

This will replace the static control with the embedded help window. Next, you need to tell it what CHM file to use. For example:

m_hhctrl.SetChmFile("myfile.chm");

Note that if your chm file is in the same directory as your application, or is registered, or is in the windows\help directory, then you don't need a path to it.

Now whenever you want to jump to an HTML file, or mapped id, use the NavigateCHM method of CHHCtrl.

If you used the toolbar, then you need to add and OnCommand() method to your class (or edit an existing one). Within this method, call m_hhctrl.OnCommand(wParam). This will enable CHHCtrl to process clicking of the toolbar buttons.

CHHCtrl methods

Besides the methods for accessing IWebBrowser, the following methods can be called:

LPCTSTR GetChmFile() -- returns a pointer to the current CHM file. This is a fully qualified path.
bool SetChmFile(LPCTSTR pszChm) -- specifies the CHM file to use for calls to NavigateCHM. Returns false if the CHM file cannot be found.
bool FindChmFile(LPCTSTR pszFile, LPTSTR pszDst) -- finds the specified CHM file and copies it to the destination buffer. That buffer should be MAX_PATH in size. Returns false if the CHM file cannot be found.
void SetHomeFile(LPCTSTR pszUrl) -- changes the URL to jump to when the Home button is clicked.
void MoveWindow(CRect* prc, BOOL fRepaint) -- call this to change the position and size of the embedded help window.
HRESULT NavigateChm(LPCTSTR URL, LPCTSTR lpszTargetFrameName = NULL) -- navigates to an HTML file within the previous set CHM file. For example, if your CHM file was called "myfile.chm" you could specify "html/myfile.htm" which is equivalent to "ms-its:c:\windows\help\myfile.chm::/html/myfile.htm".
HRESULT NavigateChm(UINT mapID, LPCTSTR lpszTargetFrameName = NULL) -- same as above, only you specify a mapped id number. For more detailed information about mapped ids, look at the "mapping topic IDS" keyword in the HTML Help Index that comes with HTML Help Workshop.

Additional notes

If you aren't using Visual Studio 6, then you need the updated header files from the Internet Explorer Client SDK.

The class CItsFile is a wrapper around the IStorage interface used to read CHM and ITS files. It's used by CHHCtrl to read the map section out of a CHM file, but you can also use it to read HTML files, graphics, or any file that you want. Look at the NavigateCHM(UINT mapID, ...) method in hhctrl.cpp for an example of how to read a file from within a CHM file.

The HTML Help ActiveX control will have the same limitations in your embedded window as it would in a web page. That means associative links and training card commands will not work. KeyWorks is currently working on an extension to the CHHCtrl class that will provide scripting capability that will provide the functionality of most of these commands without having to load an ActiveX control to do it.