During this hour you will learn
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". |
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.
![]()
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.
![]()
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.
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![]()
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.
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.
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.
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.
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:
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.
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:
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.
The opening help window looks good and provides ample help for the program.
The Index values generated from the K entries provide an index of topics that users can search.
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.
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 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.
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.![]()
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:
If you fail to add context-sensitive help to all controls, Visual Basic displays the help file's Contents page (the opening help page).
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.
![]()
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.)
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.
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.
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.![]()
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.
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:
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:
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.