There is a new and exciting change in the Windows Help landscape — the move to HTML-based Help files. This change, initiated by Microsoft, makes possible a wide range of new and better help systems. In this article, I'll give you a basic introduction to this HTML-based Help, and provide you with some sample code. The code is based on Microsoft's Visual C++ v5.0, with a Windows 95-based PC as the target platform. If you're using some other C/C++ tool, don't worry: the fundamentals are the same. The mechanics of implementing the new Help standard are very easy, perhaps easier than the old WinHelp method.
Figure 1 shows a sample HTML Help file opened to a topic. Notice that it consists of two panes: a navigation pane on the left, and the actual topic pane on the right. This arrangement allows users to expand/collapse topics at will, and to always know where they are in the file. Compiled HTML Help files can be recognized by the extension .chm. They are built using a free toolkit available from Microsoft.
Benefits and Drawbacks
The primary benefit of this new system is that it is truly "write once, use everywhere." Once you build an HTML Help file, which is actually a compiled program, you can mount it on disk, on the Internet, or on an intranet. The same application can be launched from these platforms without any need for modification or intervention on your part.
Another benefit of HTML Help is simplicity. Previous flavors of WinHelp used RTF (Rich Text Format) files, identified by their .rtf extension. RTF files could be cantankerous, with their many curly brace delimiters, etc. It is much easier to edit an HTML file than an RTF file. Furthermore, Microsoft has announced that it will continue to support RTF-based Help files, and the HTML Help compiler/development kit even allows you to port existing RTF-based systems to the new standard. The Help files built using HTML are much more robust than RTF-based files. You can easily drop in nice little goodies like multimedia Java applets that add spit and polish to even the most prosaic help file.
Finally, one of the biggest benefits afforded by this system is the way it augments information searches. You can designate topics as members of a given type; this is similar to the concept of a set in mathematics. As an example, you can tag topics as being conceptual, tutorial, procedural, or any other category you care to imagine. Suppose you're writing a Help file for two closely related, but slightly different, products. By using these topic tags, you could write one Help file for both products. When the user sought help for one of the products, only those topics would appear. Partitioning in this manner makes for a much easier maintenance cycle too.
There are a few minor drawbacks to HTML Help, depending on your perspective. First, you must have Microsoft's Internet Explorer web browser installed on the target platform. Microsoft is developing a run-time product for non-IE users which will eliminate this requirement. This product is scheduled for release later this year. Second, every topic requires its own HTML file, which can make project maintenance somewhat of a pain. Third, the new standard supports popup windows (which aren't as elegant as those in the old WinHelp system) and they are somewhat difficult to implement. Last, the help author must know at least the basics of HTML, which I would guess most developers know already. If you don't, don't worry, HTML is easy to learn.
The HTMLHelp API
Opening an HTML Help file from inside a Windows program requires making a call to a new API called HTMLHelp. This API comes with the development toolkit, and is prototyped as follows:
HWND HtmlHelp(HWND hwndCaller, LPCSTR pszFile, UINT uCommand, DWORD dwData);
To use this API, you'll need to include the file htmlhelp.h with your project, and link with hhctrl.lib. Both of these come with the toolkit — I suggest you copy them into your \include and \lib directories so they can be found by the compiler.
Now for a closer look at the API. The hwndCaller parameter is the handle of the window making the call. When the Help window exits, the focus returns to this window unless it's the desktop window. In this case, the focus is set by the operating system. Also, if any messages are returned by the Help window, they go to this window. The pszFile parameter is the name of your compiled Help file. It could also be a URL, or a window definition (which must be preceded by the ">" character, just like with secondary windows in the old WinHelp system). This parameter can be NULL if the command being used (i.e., the uCommand parameter) does not need a file or URL. The uCommand parameter specifies the action to be performed. Valid values are:
HH_DISPLAY_TOPIC HH_HELP_CONTEXT HH_DISPLAY_TEXT_POPUP HH_SET_WIN_TYPE HH_GET_WIN_TYPE HH_GET_WIN_HANDLE HH_TP_HELP_CONTEXTMENU HH_TP_HELP_WM_HELP
You'll probably use the first two the most often when calling HTML Help from an application. The last parameter, dwData, specifies any additional data needed, and depends on the value of the uCommand. This is all documented in the toolkit's Help file, so I won't discuss it here.
Now I'd like to give you an example of how to use the HTMLHelp API. Suppose you want to open your HTML Help file to a certain topic when the user starts your application. If you're using MFC, your project's InitInstance method should include something like the following just prior to the return statement:
HWND hwndCaller =
AfxGetApp()->m_pMainWnd->
GetSafeHwnd(); // handle to your
// app window
// start HTML Help
HtmlHelp(hwndCaller, "myhelp.chm",
HH_HELP_CONTEXT, IDH_MAIN_TOPIC);
In this example, the Help file myhelp.chm is opened to a topic identified by the context string IDH_MAIN_TOPIC. (Note that this call opens only the topic portion of the Help file. It is possible to have both the topic and navigation panes appear, but you must first create a new window type, then use > to pipe information to that window.) Normally, opening a .chm file causes both the navigation and the topic panes to be displayed.
Using the Toolkit
The HTML Help compiler/toolkit is available free from Microsoft. You can download it from:
http://www.microsoft.com/workshop/author/htmlhelp/
Figure 2 shows the toolkit with a project open. A project file has the extension .hhp. In addition, an HTML Help project consists of the following items:
1. A contents file, extension .hhc.
2. Topic files, extension .htm or .html.
3. An index file, extension .hhk.
Note the tab labeled Help in the left-hand pane of the toolkit. The toolkit comes with a very rich help file itself — even a quick reference for HTML tags. It also has some useful information on planning and designing your Help system.
Overall, the kit is extremely easy to use. I was able to build a simple HTML Help file right out of the box without reading the documentation. Building a project is simply a matter of creating topic files in HTML format, adding them to your project, and compiling. The toolkit contains everything you'll need to build HTML Help files — image editors, a simple HTML editor, the compiler, etc.
I'll now outline the steps of creating a basic HTML Help file.
Creating a Project
The toolkit GUI provides practically everything you need to create an HTML Help project. Since detailed instructions on which buttons to push, etc. will be meaningful only after you have the toolkit, I've provided this information as a text file on the CUJ web and ftp sites (see p. 3 for downloading details.) The following is a rough overview of what is involved in creating a project.
Prior to starting the toolkit, you should create a directory to contain your project — this example builds a project called "Demo," so you'd want to create a Demo directory. When you start the HTML Help toolkit, you'll get a popup window that asks you what type of new file you wish to create. The choices are:
Project Text HTML File Table of Contents Index
Project will be the first option you select. This starts up a wizard that takes you through the steps of either converting an existing WinHelp project to HTML, or a new HTML Help file. You'll want to select the latter option. You'll then be guided to provide a project name and location (the folder you created earlier).
The next window you'll see gives you the chance to add any existing components that you might have created to the project (e.g., the table of contents, index, etc.). Leave all these checkboxes blank. After completing this window you'll have successfully completed your first HTML Help project.
The next thing you'll want to do is create a TOC (table of contents). This table will go in the left pane (i.e., the navigational pane) of the Help window when it opens. The TOC is simply a tree view control that expands and contracts as you click the expand/collapse boxes next to the icons. Creating the TOC is done under the Contents tab.
After you create and save your TOC, the buttons on the left side of the toolkit will change to those shown in Figure 3. These let you add the headings, topics, adjust the level of indentation, etc. You insert a heading by clicking on the file folder icon; a dialog box will appear as shown in Figure 4. Note that you could assign a topic to this (or any) heading by clicking the Add button and specifying an HTML topic file. Next, a default topic file must be created that will be displayed when your Help file is opened, or if the user clicks the top-level heading. You'll need to create a new default HTML file and tell the toolkit where to find it.
The next step is to add subordinate headings, or topic pages, under the heading. You can either create a new HTML topic file first or after creating the page. To create a new topic file you can select New | HTML file. The text editor will open in the right hand pane of the toolkit with the basic HTML tags already built for you. After adding some text and saving the file as an .html file, the GUI enables you to create an associated topics page. The left-hand pane of the toolkit will show your top-level topic and one subordinate topic.
If you like, you can add more topics and/or headings by repeating these steps. But at this point, you will have enough done to build and view the project. The next step is to compile the help file. (You may be prompted to save your project first, which you should have done.) After compiling the file, the toolkit provides a View compiled file icon (i.e., the eyeglasses icon) that enables you to view the compiled help file. It will appear something like Figure 2. That's all there is to it.
Summary
The new HTML Help standard is going to make a big splash once the word gets out about its capabilities. New releases of the toolkit are in the works: there should be a true WYSIWYG HTML editor in the next version; the runtime kit will open up web access for Netscape and other non-IE browsers. I've barely scratched the surface of what you can do with this new product, so I suggest you download the toolkit and start experimenting.
Keith Bugg is a software engineer for Q Systems, Inc., a consulting firm in Oak Ridge, Tennessee. He's been working with Visual C++ since version 1, and is currently finishing up a book on debugging to be published by R&D Books. He welcomes your comments at [email protected].
