Hour 29


During this hour you will learn

Building a Help Subsystem

This lesson explains how to help your users. By the time you finish this lesson, you'll know how to add a help system to your applications so that your users can read online documentation to help them better understand your application. The online help system that you can use with Visual Basic is nice because it mimics the online help found in virtually all other Windows programs. Therefore, your users won't have a startup learning curve ahead of them when learning how to use your application's online help system.

In addition to the standard online help, this lesson teaches you how to add help in other ways. You've already seen how to add ToolTips to toolbars (in Hour 23, "Enhancing Your Program"), but this lesson explains how to add ToolTip help to all your application's controls. You can also add the all-important What's This help to your application forms.

FAST TRACK
Do you want to forego learning about creating a help system and go straight to an application's design? Check out Hour 33, "Developing and Designing Forms".

Topic 1: Online Help

Although writing an online help system might be a daunting task, you can borrow the Windows help system for your applications. All you really have to do is write the text that becomes the help text and then use the Windows help system to display that help text at the right time and place. Your users won't have a learning curve because they already know how to use the Windows help system.

Don't wait until your application is completely finished before designing the online help system. The best time to write the help text is when you design and create the application. At design time, you have a better working knowledge of the application than at any subsequent time, and you'll be better equipped to write the kind of help your users need.

Overview

This topic section explains how to build and link the help topic file to your application. Not only must you write the help topic file, but you must also build a help project that you then compile into a help system that links to the application. The text that goes in your help topic file must be in the special RTF (Rich Text Format) format, which the application can use to embed hypertext jumps from topic to topic when appropriate.

You must have access to a word processor or text editor that creates RTF files. Microsoft Word is perhaps the most popular word processor used for help files.

Preparing for the Topic File

When you use Word to create the help file, you should turn on the hidden formatting codes. Although most people write documents without the codes showing, the hypertext jumps require hidden text, which you need to be able to see even though that text will be hidden from all eyes but yours at the word processor keyboard. Click the Show/Hide button (the paragraph symbol) on Word's toolbar to display hidden codes.

Creating Hypertext Jumps

Most of your help file will consist of regular text that describes the help topics. Regular help text requires no special formatting, but you can vary the font size and style as much as you want to. The hypertext jumps require some special formatting, however, so that the help system can recognize hypertext jump keywords and the help system will know where the linked topics reside.

The more you cross-link your help file topics with hypertext jumps, the more useful your help system will be to your users. When you add hypertext jumps, you keep users from having to use a menu to select every topic that might benefit them; rather than use a menu, they can jump directly to the topic they want to read.

The requirements for creating hypertext jumps are as follows:

Symbol Description

Describing the help file is much more involved than showing you an example. Therefore, the Example section appears next, to illustrate the different ways you can set up the hypertext jump and the jump target.

If you use the K footnote symbol to designate a topic search, add as many search topics as you can. As you'll see in the example, K footnotes often contain multiple entries separated by a semicolon. The following footnote entry tells the help system that the help topic should appear in four entries in the help index:

KChange Options;Menu commands;Change;Changing text

Example

This example begins to build a help system for the sample program that comes with Visual Basic called MDI Notepad. The application uses MDI forms to manage a tiny multi-windowed text editor. Although the text editor is fairly complete and extends past the Windows Notepad editor (because MDI Notepad supports multiple windows), the MDI Notepad application supports no online help.

This example uses Microsoft Word to create the help file. You might need to use a different word processor depending on the contents of your system.

Figure 29.1 shows a sample opening help screen in Word for the MDI Notepad application. Remember that the double-underlined phrases are the hypertext jump phrases that will appear in green on the user's help system. All hidden text is turned on, so the dotted underline text represents the hidden text that holds the context strings.

FIG. 29.1

MDI Notepad's opening help text screen contains hypertext jumps.

Figure 29.1 shows six jump-phrase context strings: MDI_DEF, CREATE_FILES, EDIT_TEXT, SEARCH_TEXT, CHANGE_OPTIONS, and MANAGE_WINDOWS. Therefore, at least six more Word pages must appear below the opening help screen. You connect these pages to their original hypertext jump links with one or more of the special footnote symbols. The first jump, MDI_DEF, will be a pop-up definition box for the term MDI.

The entire help file needs a help context ID value so that the underlying application can reference this opening help screen when needed. Figure 29.2 shows two footnotes created for the opening help text. To add a footnote, you would move the text cursor before the first character in the title, choose Footnote from the Insert menu, and type # for the custom symbol that indicates the hypertext jump page location. Repeat these steps to enter the $ footnote for the hypertext jump link's title. The two footnote symbols appear to the left of the opening text as well as next to their respective footnote text in the bottom window. The application can use the help context ID to reference this help screen, and the help engine's search tools can display the title that appears next to the $ footnote symbol.

FIG. 29.2

The entire opening help window now appears when its context ID or title is called for.

Don't use the K footnote symbol for the opening help window. Remember that K is reserved for those times when you want a pop-up help box to appear if users click an underlined help topic. Also, you'll use a K footnote along with # and $ so that every topic appears on the help dialog box's Index list of topics.

In the next few paragraphs, you'll learn that the RTF document contains a different kind of help context ID than Visual Basic wants to use. As a result, you'll have to map the RTF file's textual context ID values to numeric values before an application can use context-sensitive help.

The remaining help hypertext jumps now need corresponding help pages and footnotes to connect the pages to the opening screen. The first help topic to create is the pop-up definition for MDI. The page below the opening help screen must contain the following information:

Figure 29.3's footnote completes the connection between this page and the opening page's MDI location by adding a help context ID to the definition. Also, the K footnote symbol indicates that the connected page is a pop-up definition and not a hypertext jump.

FIG. 29.3

The definition will now pop up thanks to the K footnote symbol.

This lesson's help file typically uses the same help context ID (in uppercase) as the topic title that the context ID links to, but these values don't have to be the same.

Finally, Figure 29.4 shows the first part of the remaining help hypertext jump topics. The # footnote connects the opening page's hyperjump topics to the subsequent jump pages.

FIG. 29.4

Subsequent jump pages are now linked to the opening help page.

Any of these subtopics can contain additional links to additional pages (and to each other) as well as pop-up help definitions.

As soon as you finish your RTF help file, you must save the document. Be sure to select the Rich Text Format file type when saving the file. Now you must create the help project file by using yet another file type, the ASCII text file type. Word can save ASCII text files, and you can even use the MDI Notepad sample application to create this file. The following project file was used for the help file described here:

[OPTIONS]

contents=HID_CONTENTS

title=MDI Notepad Help

[FILES]

MDINote.rtf

The [OPTIONS] section describes the opening help page context ID and the title bar text. The [FILES] section describes the help file being compiled (you might need to specify a path name if the file resides in a special location). Enter the name of the RTF help file you created and saved earlier. You can set other help project file options from within the help compiler.

Save the project file under any file name (the name of the application file is perhaps the best project file name). Use the .HPJ extension, however.

You need to install the help compiler from your Visual Basic installation CD-ROM because the help compiler doesn't install with the normal Visual Basic installation. At this writing, you must install the help system by following these steps:

  1. Insert the Visual Basic Installation CD-ROM in your CD-ROM drive.
  2. Select the Start menu's Run option.
  3. Execute the Setup.exe program, \Tools\HCW, located in VB's CD-ROM folder. Follow the instructions, and the Setup program installs your help compiler on the Start menu's Microsoft Help Workspace option.

Start the Microsoft Help Workshop program and load your help project file when you want to compile the project. After you click the Compile toolbar button and accept all the default values, the compilation will begin. Read the warnings and errors that the compiler might display after the compilation finishes. Often, warnings occur that won't affect your help system, but you should attempt to eliminate all warnings completely to perfect your help file under all conditions. If errors exist, the compiler will be unable to compile the file.

Next Step

After you compile the help system, you can run it to test your help entries. You won't learn how to connect the system to the application until the next topic section, but you can follow these steps to test the help file:

  1. Start the Windows Explorer.
  2. Locate the help file's folder. You'll see the help file in the list of files with a help icon.
  3. Right-click the help file and choose Open. The Windows online help system begins, and you can check out your help file.

Figure 29.5 shows the help window that appears with the help system described in this topic section. The first window (which you can return to by clicking the Contents button at any time) displays the opening help page. The Index page, shown in Figure 29.6, shows a complete listing of all K footnote values that cross-reference help topics.

FIG. 29.5

The opening help window looks good and provides ample help for the program.

FIG. 29.6

The Index values generated from the K entries provide an index of topics that users can search.

Topic 2: Hooking Up the Help File

After you generate the help file, you need to connect the application to the file. The help context IDs associate the various help topics to controls and parts of the application. Also remember to add a Help menu option so that users can request help at any time on any subject in the help file.

Overview

The number of help connections varies dramatically from application to application. You can use the depth of the help file as well as the complexity of the application to predict how much help users will need. The rest of this topic section explains some of the ways you can connect the help file to the application. (Visual Basic supports a number of help file connections, but this topic section describes the most common connections.)

The Project Dialog Box

The Project Properties dialog box (see Figure 29.7) is the primary link between your project and the help file. The Project Properties dialog box ensures that the help file connects to the user's F1 keypress.

FIG. 29.7

Connect the help file to your project.

You don't need to worry about changing the text box labeled Project Help Context ID. Any help context ID you enter there determines the help that appears when you click this application's Help toolbar button from within the Object Browser.

VB's Help Context ID

Unfortunately, you've taken care of the easiest part of the help system connection: the F1 key that generates the complete help window. If you want to add context-sensitive help to your application so that users can press F1 to see help when a control has the focus or during a menu selection, you must complete a few more steps.

You must trigger the execution of the Windows help engine. You must also tell the help engine exactly which help window page to display when users select context-sensitive help. Starting the help engine requires a special Windows API (for Applications Program Interface) function call from a standard module in your project. You then must edit the help file's project file again and map numeric context IDs to your textual context IDs. Here are the basic steps you'll see detailed in the next example:

  1. Add a standard code module to the application.
  2. Declare the API function. You must declare all API functions inside the application just as you declare variable names. The API function declaration is a long declaration because it must tell your application exactly where the function comes from, how to call it, and what to expect in return. Although the declaration code to start the Windows help engine is messy, you use the identical code in any Visual Basic program that requires context-sensitive help. The declaration will let you use a Help menu to trigger certain help page displays.
  3. Edit the help project file and map the textual context IDs to numeric context IDs.
  4. Recompile the help file.
  5. Select every form and control and menu item in the project to which you want to add context-sensitive help. Change that object's HelpContextID to the numeric ID that matches the help page that you want displayed when the user presses F1 and the object has the focus.
  6. Add code to the Help menu options to trigger appropriate help pages.

If you fail to add context-sensitive help to all controls, Visual Basic displays the help file's Contents page (the opening help page).

Example

When you want to add context-sensitive help, you must right-click the application's Project window and add a new module file. The file contains only the following API function declaration in the following code (you must type it exactly as it appears):

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

The statement is one continuous statement, and the underscores connect the lines so that Visual Basic views the five lines as a single line of code. The statement allows you to hook up a Help menu system that can display various pages of the help system later.

You now must re-edit the project file and map the textual context IDs to numeric ones. To do so, you'll add a [MAP] section to the project file. Given the MDINote.rtf help file and associated project file described in the last topic section, the following code provides such an edit of the project file.

[OPTIONS]

contents=HID_CONTENTS

title=MDI Notepad Help

[FILES]

MDINote.rtf

[MAP]

HID_CONTENTS 1

MDI_DEF 2

CREATE_FILES 3

EDIT_TEXT 4

SEARCH_TEXT 5

CHANGE_OPTIONS 6

MANAGE_WINDOWS 7

Make sure that no two context ID numbers are the same. The mapping can begin at 1, but many Visual Basic programmers reserve series of numbers to represent different kinds of help topics. For example, all command button help topics might range from 1000 to 1050. The numbers, therefore, don't have to be sequential. Recompile the project file to embed the new map information in the help file.

Your sleuthing now begins. You must locate every control and form to which you want to add context-sensitive help. For example, in the MDI Notepad application, you could display the frmFind form (the form that supports the Find menu option that locates data in the document) and change the Find command button's HelpContextID property to 5. If that were the only change you made, users would always see the standard opening help Contents screen when they run the application and press F1, except when the Find button has the focus; users would then see the help topic for the Search page. Of course, you would want to add additional context-sensitive help displays to other controls, including some forms, for your user's benefit.

As you add the context-sensitive help to controls, you'll likely find other areas of the application that need explanation. Therefore, you might add to your .RTF help file many times before you've provided ample help support to the application.

When you add help pages, try your best to locate every place in the application from which users might need specific help. Every time you add context-sensitive help, your users don't have to search through the help Index or Contents page that otherwise would appear.

Next Step

You haven't added a Help menu to the application yet. You must specifically call the windows help system to add the Help menu options. If you're following these examples and creating the help file for the sample MDI Notepad application, you can also add a Help menu item to the primary MDI Notepad form that contains these items: Contents and Index. Assuming that you use the standard menu-naming conventions (described in Hour 5, "Creating Menus for User Ease"), you should add the code in Listing 29.1 to connect those menu items to their appropriate help pages.

Listing 29.1 Mnuhelp.bas: Using WinHelp() to Display the Help System

Private Sub mnuHelpContents_Click()

  ' You can ignore the return value for now

  Dim varHelpRet As Variant

  varHelpRet = WinHelp(frmNotePad.hwnd, "MDINote.Hlp", cdlHelpContents, CLng(0))

End Sub

Private Sub mnuHelpIndex_Click ()

  ' You can ignore the return value for now

  Dim varHelpRet As Variant

  varHelpRet = WinHelp(frmNotePad.hwnd, "MDINote.Hlp", 11, CLng(0))

End Sub

Although this WinHelp() function call code is about as messy as the WinHelp() function's declaration code, you can copy and paste this exact code into your menu Click () event procedures as long as the second argument is the name of your help file (including a possible path, if needed) and the third argument contains either cdlHelpContents or 11 (unfortunately, Visual Basic doesn't provide a named literal for the help index's display), depending on the menu option. (These are named literals that Visual Basic supplies.)

Topic 3: Simple Help: ToolTips and What's This?

As you've seen, the big task of providing online help is creating the help file and project. ToolTips are simple to add to various objects (as you've seen for the toolbar in Hour 23, "Enhancing Your Programs"), and the special What's This help relies heavily on your help file. As long as you've created a detailed help file, adding eye-catching What's This help is simple.

Overview

You can add ToolTips to a control when you add the control to the form. The Properties window's ToolTips property value holds text that you can enter. When users rest the mouse pointer over any control with the ToolTips property, the ToolTip appears after a brief pause.

In addition to the ToolTips, you can provide What's This help to give users additional information for your applications. What's This lets users see the help text for any object that supports What's This. Figure 29.8 shows one of this lesson's help file pages that appears when users right-click the MDI Notepad's Find button. The What's This help is available whenever a form window contains the What's This question mark button. Users click the What's This button and moves the mouse cursor (now a question mark) over any object and clicks to see the help that you've set up for that object.

FIG. 29.8

The user can ask, "What's this?"

Make your What's This help match the objects. Figure 29.8 uses the closest help page available for the Find button from the pages described in the previous topic sections. This lesson's example doesn't contain enough help pages to describe all the What's This needed for the MDI Notepad, but I wanted to use a page from the examples that you've seen.

ToolTips

To add ToolTips to any object, you only need to enter the Tooltext in the object's ToolTipText property. Visual Basic does the rest of the work. Look through the MDI Notepad application's controls to see that Microsoft added ToolTips to almost every control on every form. ToolTips are simple to add, and you should get in the habit of adding ToolTip text as you add controls to your applications' Form windows.

What's This Help

You must add a help page for every What's This help feature that you want to support. After you add the pages and connect them to the other help pages in the system through the custom footnotes described earlier in this lesson, you must map the pages to a numeric context ID. The What's This help engine uses those context ID numbers to determine the proper help box to display when users request the What's This help.

The secret to What's This help is twofold:

  1. Make sure that the form supports What's This help by setting the form's WhatsThisButton property to True and by setting the form's WhatsThisHelp property to True.
  2. Enter the help page's context ID in the object's WhatsThisHelpID property.

Example

The What's This help from the MDINotepad application (if you've followed the first two topic sections and created a help file with help pages that you can use) requires only that you perform these steps:

  1. Open the Project window and double-click the form named frmFind to display the Find dialog box's form.
  2. Assign True to the WhatsThisButton and WhatsThisHelp properties. When you subsequently display this form when the application executes, you'll see the What's This question mark button on the form.
  3. Repeat the assignment for the other two forms in the application.
  4. Look through the help project file's [MAP] section for context ID numbers and assign these context ID values to various menu options (use the Menu Editor) and form objects that might need the description. Although the help file is far from complete, several of the help pages work well for the objects, especially the menu bar items.

Summary

Several forms of help are available to Visual Basic developers. By using the Windows help engine, you can build a complete hypertext jump system with interconnected help pages and pop-up definitions. Your user can get context-sensitive, access-specific help pages by pressing F1. Although you must include a new module with a special API call to the system help engine, as soon as you include the API call, users receive help at the push of a button.

Adding context-sensitive help allows your users to locate the help they need. You can assign context-sensitive help to various objects so that specific help text appears when users select the object and press F1. The context-sensitive help feature keeps your users from having to search through the index every time they require help.

Two simple help features that you can add quickly are the ToolTips and What's This help elements. ToolTips are extremely simple and require only that you add the ToolTips text in the Properties window. Before you can assign What's This help, you must build a comprehensive help file and assign various numeric context IDs that you can assign to objects.

In the next hour's lesson, you'll learn more about ActiveX controls and how you can implement such controls in your Visual Basic applications.

Hour 29 Quiz

  1. What file format must you use to create an online help file?
  2. How can hypertext jumps improve a help system?
  3. Which custom footnote symbol creates pop-up help definitions for underlined help page text?
  4. What are some of the features of the help project file?
  5. After you compile a help file, how can you attach such a file to an application so that the help file appears when users press F1?
  6. How do you connect context-sensitive help to the help file topics?
  7. True or false: The context-sensitive help uses the textual context IDs in your help file.
  8. What's the difference between the What's This help and the ToolTips help?
  9. How can you add the What's This button on forms?
  10. True or false: You can offer What's This help for forms as well as for objects on the form. (Hint: Check the form's properties.)

Hour 29 Homework Exercises

  1. Create a help file that describes the basic steps for starting an automobile. Connect pages together with hypertext jumps and create pop-up definitions for various terms such as ignition. Create a help file with at least 10 help pages (including the opening contents page). You can test the help file by right-clicking the compiled help file in Windows Explorer and selecting Open.
  2. Add What's This help to every object in MDI Notepad. This task might seen tedious-and it is somewhat-but you'll quickly get the hang of What's This help, context IDs, and help pages.

© 1997, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.