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
[edit | edit source]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
[edit | edit source]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 than 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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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
[edit | edit source]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... [citation needed]
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/