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.