Professionally programmed applications provide online help. Whether your Visual Basic application is intended for general deployment to a wide variety of users or is a specialized corporate application to be used within a limited enterprise, you owe it to your users to provide detailed and understandable online documentation. Also, the documentation should be as context sensitive as possible so that when users press the F1 key, they arrive at the exact topic in the help documentation that addresses the particular need at hand.
Learning to create useful, appropriate online help is a profession in itself. There's more to creating good help documentation than learning the mechanics of making help files. A good help system allows users to find the information they need, when they need it. That information should be clear, concise, and instructive.
Use this chapter's sample projectThis chapter is simply an overview. For a more detailed description of the process of creating help files, take the time to read the Help Workshop's online documentation and study the sample Composer.hpj project provided for this chapter. You can find this project at http://www.mcp.com/info. When you locate this Web site, you'll be asked to enter an ISBN; enter 078971633x and then click the Search button to go to the Book Info page for Using Visual Basic 6.
The Microsoft Help Workshop 4.0 is a set of tools, separate from Visual Basic, that you use to create help files for applications that run under 32-bit Windows systems. The Help Workshop is shipped on the same CD-ROM on which you received your copy of Visual Basic 6.0, in the directory \Tools\Hcw. You invoke Setup.exe to install the Help Workshop on your computer.
You use the tools in the Help Workshop to make a set of help files for your application. Generally, the help files that you make for your application's online help documentation are a contents file (.cnt--see Figure 24.1) and associated help files (.hlp--see Figure 24.2).
FIGURE 24.1 Content files (.cnt) list the topics of your applicationís help documentation in a hierarchy.
FIGURE 24.2 A help file (.hlp) contains various topics' text and hypertext.
A content file is similar to a global table of contents for your help documentation. Users click a topic description on the Contents page to find a specific topic within a help file. For example, when users choose Claude Debussy in Figure 24.1, they're presented with the help topic for Claude Debussy, as shown in Figure 24.2.
You create your help data by using any word processor that supports footnotes and the Rich Text Format (.rtf). Then you "compile" the RTF files and the help project file (.hpj) with the Help compiler to create the help file (.hlp--see Figure 24.3). Table 24.1 shows the different data and executable files used within this process. You make the contents file within the Help Workshop environment (see Figure 24.4).
FIGURE 24.3 You create the help project file (.hpj) and the help document's content file (.cnt) in the Help Workshop. You make help data in any word processor that supports Rich Text Format (.rtf).
| File | Name | Description |
| Hcw.exe | Help Workshop | Online documentation workspace |
| Hcrtf.exe | Help Compiler | Transforms an .rtf file into an .hlp file |
| Shed.exe | Hotspot Editor | Creates hypertext jump regions on bitmaps |
| Dbhe.exe | Dialog Box Help Editor |
Makes context-sensitive help dialogs |
| Hcw.hlp | The help file for the Help Workshop | |
| Shed.hlp | The help file for the Hotspot Editor | |
| Dbhe.hlp | The help file for the Dialog Box Help Editor | |
| MyProject.hpj | Help project file | Project-specific data created by the Help Workshop |
| *.rtf | Rich text format files | RTF files that will be transformed into an .hlp file |
| MyProject.hlp | Help file | The help file made from the .rtf file |
| MyProject.cnt | Contents file | The contents file associated with given online help |
| MyProject.log | Log file | The file that lists compilation errors |
FIGURE 24.4 You set the topic hierarchy of a content file within the Help Workshop environment.
Third-party toolsThird-party tools, such as RoboHelp, also are available to automate the creation of content and help files. These tools work just as well as, if not better than, the Help Workshop.
You can have help documentation that references more than one distinct help file through a content file (see Figure 24.5). This sort of configuration is useful if you have a large program with many categories of help topics. Breaking up help files into numerous smaller ones makes the development process easier to distribute among many documentation developers. Also, smaller help files load faster, making the overall performance of your program better.
FIGURE 24.5 You can have your content file reference more than one help file.
You make a help file by using a special footnote markup language in Rich Text Format. The RTF file is constructed in three sections: the jump text, the topic text, and the footnote tags (see Figure 24.6).
FIGURE 24.6 You use footnote tags to set up the hypertext jump structure of a help file.
The heart of the help document structure is the topic, a section of Rich Text bounded with a page break. The first line of the section is footnoted with at least the special footnote character #. You enter the topic ID of the topic section next to this character in the footnote area of the RTF file. (A topic ID is a location address of the given topic within the RTF file.) You also use the characters $ and k as footnote characters at the beginning of each topic section. The $ character represents a tag for subject. The k character is used to denote index keywords that will show up when you look at the Index page in the Help Topics dialog, as shown in Figure 24.7. Words entered in the subject footnote appear in the History window of the help documentation.
FIGURE 24.7 A help document has a variety of windows.
The sections interact by the use of strikethrough text to indicate that the characters of that text are hypertext. You place text formatted as hidden after the strikethrough text. The text formatted as hidden is the jump-to address that will be referenced by the strikethrough text. The contents of the jump-to address is formally known as the Topic ID. When you run the RTF file through the Help Workshop's Help Compiler, the strikethrough text is transformed into hypertext. When users click the hypertext, the Help runtime engine (WinHelp.exe) looks to the text that was formatted as Hidden and placed after the strikethrough characters for the address of where to jump. Then, after the engine knows the address, it looks in the footnote section for the location of that address within the help file. The engine then goes to the topic at that address and displays the information (see Figure 24.8).
FIGURE 24.8 Make sure that no space appears between the strikethrough text and the hidden text for the topic ID. If there is, you can't make a jump, and you'll receive an error.
Make a simple RTF help file
Moe Larry Curly
Moe is a bossy stooge.
Larry has funny hair.
Curly is roly-poly.
FIGURE 24.9 Use the # character within an RTF document's footnote to apply a Topic ID to a topic.
Compiling an RTF file into an .hlp file
FIGURE 24.10 You can make either a help file (.hlp) or a content file (.cnt) with the Help Workshop.
FIGURE 24.11 The content for a help file is an RTF file, which the Help Workshop compiles an HLP file.
HTML helpIn addition to the Help Workshop, Microsoft is beginning to support a newer technology called HTML Help. HTML Help uses documents written in HTML and viewed through Internet Explorer to implement the features seen in the Help Workshop. The help system for VB6 is written in HTML Help. HTML Help ships in the Windows NT 4.0 Service Pack 3, available on MSDN. As of this writing, however, the Help Workshop is still the authoring environment that ships with VB6. Be advised, however, that HTML help is destined to be the help authoring environment of the very near future.
The mechanics of the markup language are difficult to understand at first pass. The purpose of this discussion is to give you a sense of how the help files work. You should read the detailed set of online help files that comes with the Help Workshop. You also can download the example files for this chapter from http://www.mcp.com/info.
The Help Workshop is an extensive development environment. You can add custom bitmaps to your files and associate certain topics with certain custom windows. It even has a complete built-in macro language that allows you to make conditional decisions and use functionality from other programs. If you want, you can access the WinHelp API, a powerful tool with many levels of complexity that will take you a while to master.
FIGURE 24.12 You can view help files from within the Help Workshop.
After you make your help documentation, you need to integrate it in your program. You associate a help file to your program at design time from the Project Properties dialog.
Associate a help file to a program
5. Click the Open button in the Help File dialog to add the filename to the Project Properties dialog.
FIGURE 24.13 You can associate a help file with a project at design time from the Project Properties dialog.
You can associate a help file to an application at runtime by using the HelpFile property of the App object:
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
Private Sub Form_Load()
App.HelpFile = "Composer.hlp"
End Sub
When you associate a help file to an application with the Project Properties dialog, if you put the help file in the same directory as the application, you can truncate the drive and directory path from the filename. This eliminates a possible runtime error.
After a help file is associated with an application, if you press F1 when your application has the focus, the associated help file will always appear.
Context-sensitive help means that your application can call up a specific topic in a help file based on the area from which your program is making the call for help. For example, if you are in a message box that has a Help button, clicking the button displays a help file specific to the message box (see Figure 24.14).
You make your application and your application's help context- sensitive by assigning a topic ID's numeric value to the HelpContextID property of a given control or object. As you learned earlier, the topic ID is the string that identifies the location of a given topic within the structure of a help file. Generally, topic IDs follow a naming convention that begins with the characters IDH_, which loosely stands for "identification for help file." You follow the underscore character with some additional naming logic. (In the sample file, Composer.rtf, French composers start with the characters FR followed by serialization numbers, and German composers follow the underscore with the characters GR, which are also serialized--GR01, GR02, and GR03. The composer prefix naming convention is programmer defined.) After the help file is tagged with topic IDs, you assign a number that corresponds to a topic ID's string.
FIGURE 24.14 Applications with context-sensitive help are much easier to use.
You assign the topic ID a number in the Map dialog of the Help Workshop (see Figure 24.15). After the topic IDs are assigned a unique number, you compile the help project file. The number assigned to the topic ID is the value that you'll assign to the HelpContextID property in your Visual Basic application.
The Composer.vbp project illustrates assigning a value to the HelpContextID property. The project is a control array of five OptionButtons. The HelpContextID property of each OptionButton is assigned a unique value that corresponds to a related topic ID within the help file Composer.hlp (see Figure 24.16). When users select a specific OptionButton and then press F1, the help file Composer.hlp automatically opens to the topic related to the OptionButton (see Figure 24.17).
FIGURE 24.15 You access the Map dialog by clicking the Map button of the Help Workshop window.
FIGURE 24.16 The value for HelpContextID is created when you make the help file in the Help Workshop.
In addition to using the HelpContextID property to make your program react in a context-sensitive manner when users press F1, you can also make message boxes display context-sensitive Help buttons. Listing 24.1 shows you how to take advantage of the last two arguments of the MsgBox() function, HelpFile and HelpContextID, which assign a help file and topic to the message box. Notice that the HelpFile argument is assigned the value of the App object's HelpFile property (line 20). The HelpContextID of the given OptionButton is assigned to the HelpContextID argument of the MsgBox() function on line 21. Assigning the specific HelpContextID of the OptionButton to the HelpContextID argument of the MsgBox() function displays the exact topic for that OptionButton when users click the Help button. Figure 24.10 shows the listed code in action.
FIGURE 24.17 When users select the OptionButton and press F1, the appropriate topic appears in the help window.
01 Private Sub cmdAdd_Click()
02 Dim i%
03 Dim Result%
04 Dim Msg$
05 `Make a message for the Message Box
06 Msg$ = "Strike the Help Button for more help"
07
08 `Traverse all the OptionButtons in the control array
09 `to find the one that is true. (Count is a property
10 `of the control array collection that reports the
11 `number of items in the control array.)
12 For i% = 0 To optComposer.Count - 1
13 If optComposer(i).Value = True Then
14 lblComposer.Caption = optComposer(i%).Caption
15
16 `Display a Message Box with a Help button. Also
17 `assign a Help file and Help topic to the
18 `Message Box
19 Result% = MsgBox(Msg$, vbMsgBoxHelpButton, _ "Help Demo", App.HelpFile, _ optComposer(i).HelpContextID)
20 End If
21 Next i%
22 End Sub
Usable error reportingA message box that reports an error should convey three points of information: what the error is, what probably caused the error, and what users can do to correct the error.
A good prompting scheme not only notifies users that an error has occurred or a decision must be made, but also provides details about what the issue is and suggestions on how to resolve it. By assigning a help file and HelpContextID to a message box, you greatly increase the amount of information that you provide to users at key decision points or when they need to address errors.
You can never offer your users too much help. A good, easy-to-use and easy-to-understand help system will distinguish your program for the better. If you are so inclined, study other programs' help documentation. Many companies devote a great deal of resources to making quality help systems, and taking advantage of their efforts will help you in your own endeavors.
© Copyright, Macmillan Computer Publishing. All rights reserved.
){kind=link}
){kind=link}
){kind=link}
){kind=link}