Visual Basic 6 Black Book
(Publisher: The Coriolis Group)
Author(s): Steven Holzner
ISBN: 1576102831
Publication Date: 08/01/98

Creating Help Files With The Microsoft Help Workshop

The Testing Department is calling again. Your new program, SuperDuperGraphics4U, is really fine, but no one seems to be able to use it. But, you say, it’s so intuitive and simple: just use Alt+F8 to draw a line, Ctlr+Shift+Esc to draw a circle, and…. Add a Help file, they say.

You can create Help files with the Microsoft Help Workshop, hcw.exe, which comes with Visual Basic, and appears in Figure 30.6. To see how the Help Workshop works, we’ll create a basic Help file for an application named “Helper” over the next few topics in this chapter.

Figure 30.6  The Microsoft Help Workshop.

---

TIP:  You can create more advanced Help files than the one we’ll create in this chapter, complete with tabs and clickable tree views of Help topics, by creating a Help contents file (extension .cnt) with the Help Workshop, setting up a hierarchy of Help topics and headers as you want.

---

To create the Help file, helper.hlp, for the helper application, we will create a Help project, helper.hpj, in the Help Workshop. This project keeps track of the files in our Help system, and in this example, we’ll just have one such file: helper.rtf, which will hold the data for our Help file. In that RTF file, we’ll set up the Help topics to display to the user, along with the hotspots in the Help file that will connect those topics.

After adding helper.rtf in the helper.prj file, you can compile that RTF file to create helper.hlp. And to open the helper.hlp Help file, you can use the Windows API function WinHelp as follows:

Private Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd _
    As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, ByVal _
    dwData As Long) As Long

To create a new Help project, select the New item in the Help Workshop’s File menu now, select the Help Project item in the New dialog box that opens, and click on OK. Using the Save As menu item in the Help Workshop, save the new Help project as helper.hpj. The new Help project appears in the Help Workshop in Figure 30.7.

Figure 30.7  Creating a Help project in the Microsoft Help Workshop.

Now that we’ve created a new Help project, we’ll add the actual Help text to that project, and we do that by creating an RTF file, as we’ll see in the next topic.

Creating A Help Project’s RTF File

The real work of creating a Help file takes place in the Help file’s RTF file. This rich text file holds not only the text for your Help files but also holds the commands used in your Help file.

For example, you use Help file RTF commands to create Help hotspots, which work like hyperlinks, and pop-up links, which work like tool tips. As we’ll see in the following topics, you use rich text format codes to support these and other Help features. For example, here are some rich text format codes and what they do as far as the Help workshop is concerned:

•  \footnote—Footnote; handles special topic commands

•  \page—Page break; ends the current topic

•  \strike—Strikethrough; indicates a hotspot

•  \ul—Underline; indicates a link to a pop-up topic

•  \uldb—Double underline; indicates a hotspot

•  \v—Hidden test; indicates the topic ID to jump to

We’ll see how these format codes are used in the following topics. In fact, we’ll build our Help file’s RTF file, helper.rtf, with Microsoft Word, and we won’t have to deal with these codes directly.

Using Microsoft Word, we create the file helper.rtf now (save the file in RTF format). Next, we add it to our Help project in the Help Workshop by clicking the Files button in the Help Workshop, clicking the Add button in the Topic Files dialog box that appears, selecting helper.rtf, and clicking on OK. This adds helper.rtf to our Help project, as you see in the Help Workshop in Figure 30.8.

Figure 30.8  Adding helper.rtf to the helper.hpj Help project.

In the following topics in this chapter, we’ll see how to create the text in the helper.rtf file to build our Help file. The actual RTF file we create is located in the helper folder on this book’s accompanying CD-ROM (note that the RTF codes in that listing will not be visible in Microsoft Word, which interprets and formats the text with those codes).

Entering Text In A Help File

The text in a Help file is divided into pages, and only one page is displayed at a time. To divide your text into pages in Microsoft Word, you enter a page break with the Insert[vbar]Break menu item or by pressing Ctrl+Enter. The first page in the RTF file is the first page displayed when your Help file is opened.

Let’s see an example. Here, we will make the first page of the helper.hlp file we’re creating a welcome page by entering this text directly into helper.rtf and following it with a page break:

Contents

Welcome to helper example application. This help file gives you help on the
menu items in helper.

Now this text will greet the user when the helper.hlp file is first opened, as shown in Figure 30.9.

Figure 30.9  The opening text in our Help file.

Actually, this text is not really enough by itself—we should allow users some way to jump to the Help pages they want to look at, and we’ll do that in the next topic.