Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

Using HTML Help with Visual C++

HTML Help doesn't use HTML source files directly. Rather, the files are compiled into files with the .CHM extension. This is because HTML Help requires information that isn't part of a typical HTML document. An HTML Help file also includes the topic and index information that is expected by Windows users.

HTML Help requires Internet Explorer 3.01 or later. If you use Internet Explorer 4.0 or later, you can take advantage of many of the IE 4.0 features, such as DHTML and cascading style sheets.

On the negative side, using HTML Help requires more work on the developer's part than using WinHelp. MFC AppWizard easily adds WinHelp to your MFC project with a simple click of a check box. HTML Help requires you to make a few extra steps.

Creating an HTML Help Project

You may find it fairly simple to create an HTML Help project when compared to a WinHelp project. If nothing else, it's certainly less expensive for an amateur programmer. There's no need to purchase Microsoft Word to edit your source files for one thing. And although you may want to purchase RoboHelp or another third-party tool to help create your HTML Help project, the tools supplied by Microsoft are quite serviceable.

Before beginning an HTML Help project, you must install the latest version of the HTML Help Workshop. This tool is included in the MSDN Library included with Visual C++. Search for the topic titled, "Microsoft HTML Help Download." This MSDN Library topic contains information about installing HTML Help workshop on your computer.

When HTML Help Workshop is installed, an HTML Help Workshop folder is placed in your Programs group. Clicking on the HTML Help Workshop icon launches HTML Help Workshop, as shown in Figure 33.14.

33fig14.jpg

Figure 33.14 HTML Help Workshop,

Creating an HTML Help file consists of the following steps:

  1. Create an HTML Help project.
  2. Create one or more HTML help topics, using HTML Help Workshop or any other HTML editor.
  3. Create an index file for your help topics.
  4. Create an alias file to map your application's help constants to the relevant help topics.
  5. Create a table of contents.
  6. Use HTML Help Workshop to compile the content into a Compiled Help Module (CHM) file.

Using HTML Help Workshop to Create a Project

HTML Help Workshop includes a wizard that is used to create a new help project. Simply select File, New from the menu, and select Project from the dialog box. You will be presented with the wizard shown in Figure 33.15.

33fig15.gif

Figure 33.15 The HTML Help Workshop Project Wizard.

The wizard can be used to create an HTML help project from an existing WinHelp project, or to create new HTML help projects from scratch.

Creating Topic Pages

Each help topic in an HTML Help project is a separate HTML page. You can use any tool capable of creating an HTML page to create your topics—anything from basic tools such as Notepad, to more expensive tools like RoboHelp. The editor included with HTML Help Workshop is very much like Notepad—it requires you to have some basic knowledge of HTML, although it does automatically generate the HTML skeleton for your document automatically.

Create an Index File for Help Topics

The index for an HTML Help file is one of two ways that a user navigates through help topics. (The other method is the Table of Contents.) An index is an HTML file with an HHK extension, and is easily created using HTML Help Workshop.

To open an index file for an open project, click on the Index tab in HTML Help Workshop. If no index file is associated with the help project, the dialog box shown in Figure 33.16 will be displayed.

33fig16.gif

Figure 33.16 This dialog box displays when no index file is associated with your help project.

The dialog box shown in Figure 33.16 prompts you to select from two options:

The form view used to create an index is shown in Figure 33.17. In Figure 33.17, several index entries have been added to the index file.

33fig17.gif

Figure 33.17 The index dialog box used from HTML Help Workshop.

The form shown in Figure 33.17 includes a toolbar that enables you to perform common operations on the index file:

To add a new keyword to the index, click the Insert A Keyword icon. The Index Entry dialog box will be displayed, as shown in Figure 33.18.

33fig18.gif

Figure 33.18 The Index Entry dialog box is used to add new index keywords.

A new keyword is added by typing the keyword name into the keyword edit control. You must then click the Add button to select an HTML help topic file. The Add button may be used to associate multiple help topics with a single key word.

Another way to access the index file is to select File, New from the HTML Help Workshop menu. A new, untitled index file will be opened for you to edit.

Creating a Table of Contents

Like the index, the table of contents is one of the primary ways that users navigate through online help. The table of contents source file is an HTML file with an .HHC extension, and is easily created using HTML Help Workshop.

To open a table of contents file for an open pro ject, click on the Contents tab in HTML Help Workshop. If no table of contents file is associated with the help project, the dialog box shown in Figure 33.19 will be displayed.

33fig19.gif

Figure 33.19 This dialog box displays when no table of contents file is associated with your help project.

The dialog box shown in Figure 33.19 prompts you to select from two options:

The form view used to create a table of contents is nearly identical to the dialog box used to create an index shown earlier, and is shown in Figure 33.20.

33fig20.gif

Figure 33.20 The table of contents dialog box used from HTML Help Workshop.

The toolbar included with the form shown in Figure 33.20 enables you to perform common operations on the table of contents file. This toolbar differs from the toolbar used in the index dialog box in two ways:

To add a new entry to the table of contents, click the Insert A Heading or Insert A Page icons. The Table of Contents Entry dialog box will be displayed, as shown in Figure 33.21.

33fig21.gif

Figure 33.21 The Table of Contents Entry dialog box is used to add new entries to the table of contents.

A new entry is added to the table of contents by typing the keyword name into the Entry Title edit control. You must then click the Add button to select an HTML help topic file.

Another way to access the table of contents file is to select File, New from the HTML Help Workshop menu. A new, untitled table of contents file will be opened for you to edit.

Compiling an HTML Help Project

To compile your help project, select File, Compile from the HTML Help Compiler menu, or click the Compile toolbar icon. The dialog box shown in Figure 33.22 will be displayed.

33fig22.gif

Figure 33.22 The Index dialog box used from HTML Help Workshop.

The dialog box shown in Figure 33.22 lets you specify three options:

To compile the project, click the Compile button. At this point, you have a fully compiled HTML help file. The next section discusses the steps required to integrate the help file into a Visual C++ project.

Integrating HTML into a Visual C++ Project

In order to use HTML Help, you must make a few minor changes to your Visual C++ project and compiler settings, as well as a few changes to your HTML help project These changes make it possible for you to call the HTML Help functions exposed by the operating system.

Modifications Required in the HTML Help Project

The first step in integrating HTML help with a Visual C++ project is to add ALIAS and MAP sections to the HTML help project file. These two sections serve a similar purpose as the MAP and ALIAS sections used in WinHelp project files.

The ALIAS section is used to establish a relationship between symbolic constants and HTML help files. An example of an ALIAS section is shown here:

[ALIAS]
IDH_LATTE       =    html\latte.htm
IDH_MOCHA       =    html\mocha.htm
IDH_ESPRESSO    =    html\espresso.htm
IDH_DECAF       =    html\decaf.htm

Each entry in the ALIAS section associates an HTML help topic file with a symbol that's defined in the MAP section. Any symbols found in the ALIAS section must have a corresponding entry in the ALIAS section. A typical ALIAS section is shown below:

[MAP]
#define IDH_LATTE       101
#define IDH_MOCHA       102
#define IDH_ESPRESSO    103
#define IDH_DECAF       104

Alternatively, you can include a header file that defines the values for the HTML help symbols:

 [MAP]
#include "coffee.h"

Unfortunately, HTML Help Workshop doesn't provide any way to add ALIAS and MAP sections. You must open the help project file using Notepad or another editor, and add the sections manually.

Modifications Required in the Visual C++ Project

In order to use the HTML help API, you must perform the following steps:

These steps make it possible for you to use the HTMLHelp function, which is typically called like this:

HtmlHelp(m_hWnd, "htest.chm", HH_HELP_CONTEXT, IDH_TELETUBBY_PO);

The HTMLHelp function has four parameters:

You can use HTML Help in addition to any support your application currently has for WinHelp. If you want to replace WinHelp entirely, you can override CWinApp::WinHelp function in your CWinApp-derived class, and call HtmlHelp instead of WinHelp.

Share ThisShare This

Informit Network