Windows Programming/Compiled HTML Help

In most programs, the menu will have a popup item called "Help". In the help menu, there is frequently an option for "Contents" or "Index" or "Topics". When you click on these options, it brings up a help box.

These help boxes are known as "Compiled HTML Help Modules", or .chm files. These help files can be compiled from HTML source code using the Microsoft HTML Help Workshop, available as a free download from Microsoft.

Making HTML Help Modules

HTML help modules can be compiled from source files containing a mixture of HTML, DHTML, CSS and JavaScript. This is the same exact HTML that is used in writing web pages, so people with web experience will have a leg up creating HTML help modules. HTML, CSS and JavaScript are languages that are very well suited for graphical applications, but the functionality is far less than C or VB. The Help Workshop contains a number of different options, as to whether you want to include an index window, if you want to allow searching and indexing, if you want to have a Table of Contents, et cetera. A default page may be chosen to be displayed when the Help Module is first loaded. Pages in a help module may use hyper links to link to other pages in the module, other files on the computer, or even resources from the internet.

HTML Help API

The HTML Help Workshop comes with a header file ("htmlhelp.h") and a library file ("htmlhelp.lib") that must be utilized in your project to be able to call HTML help modules from your program. Windows.h must be included before the Htmlhelp.h file, or the compiler will spew out errors. Htmlhelp.h defines a single function, HtmlHelp that can be called from inside your program:

HWND WINAPI HtmlHelp(HWND hwndCaller, LPCTSTR pszFile, UINT uCommand, WORD_PTR dwData);

This function returns a handle to the html help window, and your program can interact with this window at a relatively high level, if you want it to. The first parameter is the handle to the calling (parent) window. If you set this parameter, the help window will be a child of your window, and can communicate with it. If you set this to NULL, the help window will essentially be autonomous. The "pszFile" parameter is the filename of the target help module. The "uCommand" may contain a number of different commands, some of which are very complicated and involved. The simplest (and most common) is the HH_DISPLAY_TOPIC command, which displays help like normal, and allows the user to view and interact with the help module. The "dwData" may optionally contain additional data, depending on the command used.

If we want to open a help module, located at c:/help/myhelp.chm, we can use the following command:

hwndHelp = HtmlHelp(hwndParent, 
                    "C:\help\myhelp.chm", 
                    HH_DISPLAY_TOPIC, 
                    NULL);

Now, let's say that we want to open a specific page inside our help module. Let's say that our module contains a page called "example.htm". We can open the help directly to that page, by changing the destination string a little bit:

hwndHelp = HtmlHelp(hwndParent, 
                    "C:\help\myhelp.chm::example.htm", 
                    HH_DISPLAY_TOPIC, 
                    NULL);

And further more, we can force the page to be displayed in a particular window of our help viewer, if we have created more then one window for it. Let's say we have created a window called "SideWin" in our html help module. We can load our page (example.htm) into SideWin using the following syntax:

hwndHelp = HtmlHelp(hwndParent, 
                    "C:\help\myhelp.chm||example.chm>SideWin", 
                    HH_DISPLAY_TOPIC, 
                    NULL);

For more advanced options, and a discussion of some of the other commands, you should check out the related material at MSDN.

Creating an HTML Help Module

The HTML help workshop has 5 buttons across the top, In order, from left to right, they are:

New

create a new HTML file for editing

Open

open an existing HTML file for editing

Compile

Compile the current project into a help module

View

view the current help project

Help

Opens a help viewer window

If you click on the "New" button (or alternately select "File>New" from the menu bar), you will be prompted to select what type of new thing you want to create. To start, you should create a new project.

Selecting to create a new project will open up a wizard, that will walk you through the steps of creating a new project.

HTML Help Files

There are 3 different file types that may be included in an HTML Help project: HTML source files (.HTM) Table of Contents files (.HHC) and Index Files (.HHK). Once you have created a new project, you may edit and add all of these types of files to your project. Each HTML help module may only have one .HHC and one .HHK file.

The Project Sidebar

When you start a new project, and complete the wizard, you will see a sidebar, on the left-hand-side of the help workshop window, that will allow you to edit the project options, the table of contents, and the index.

Decompiling

On Windows, a CHM file can be extracted to plain HTML with the command:

hh.exe -decompile extracted filename.chm 

This will decompress all files embedded in filename.chm to folder extracted.

You can also use HTML Help Workshop to decompile CHM files. File -> Decompile...

7-Zip will open .chm files as archives allowing access to all content.

On Windows, select the topmost Topic, right-click and select Print. On the popup dialog, select "Print this heading and all subtopics.", click OK. Before selecting a printer, look in %HOMEPATH%\Local Settings\Temp for a file named ~hh*.htm. This is the concatenated HTML. The image reference will refer to the .chm file at the time of the print.

On Linux systems which use apt as a packaging tool, a CHM file is extracted to plain HTML with extract_chmLib (first command is for a Debian based OS):

 $ sudo apt-get install libchm-bin
 $ extract_chmLib tero.chm tero/