Advanced Visual Basic Techniques
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471188816
Publication Date: 06/01/97

If all goes well, the compiler will create a compiled help file with the same name as the project file and a .HLP extension. The file can be opened and tested by double-clicking on it in Windows Explorer or by using the Open command in the File menu of any help application.

Help compilation often does not go smoothly. If all of the context strings used by hypertext links in the topic file are not properly defined by the appropriate footnotes, the compiler will produce error messages. Ensuring that all hypertext links are consistently defined can be quite confusing and debugging a large help project can be very difficult. The process is easier if the help files are built incrementally. Starting with small files, gradually adding to them and testing frequently can prevent a tangle of hypertext links from becoming too complicated to debug.

Eventually, even this process becomes cumbersome. When the number of help topics becomes extremely large, compiling the entire project may take hours. In that case, incrementally adding to the project will take a very long time.

The process can be improved by placing the help topics in several files and including them all in the help project file’s [FILES] section. Then, after a particular file has been thoroughly tested, it can be commented out by placing a semi-colon in front of its INCLUDE statement. The help compiler will not load any commented files, so the build will be faster. Of course, if hypertext links in the remaining files lead to topics in a file that has been commented out, the compiler will generate warning messages.

Using a Help File in Visual Basic

Once the help file is compiled, presenting help in Visual Basic is fairly simple using a common dialog control. The application starts by setting the control’s HelpFile property to the name of the compiled help file. If the application does not specify a complete path, the system will look for the file in the application’s default directory.

When the program is ready to present help, it should set the dialog’s HelpCommand property to indicate the operation the help system should perform. Table 2.4 lists some of this property’s more important values.

Note that newer versions of the help compiler do not support cdlHelpContents and cdlHelpIndex. An application should use the “help finder” constant. Unfortunately, this constant is not defined by Visual Basic 5.0. An application can define an appropriate constant using the following code:

Public Const HelpFinder = 11

Finally, after the application has set the dialog’s HelpCommand property, it should use the dialog’s ShowHelp method to present the help to the user. For example, when the user selects the Contents command from the Help menu in ExpenseReporter, the application uses the following code to present the help file’s contents page.

Private Sub mnuHelpContents_Click()
    FileDialog.HelpCommand = cdlHelpContents
    FileDialog.ShowHelp
End Sub

ExpenseReporter uses the following code when the user selects the About This Screen command. The help context value 2 is defined in the MAP section of the help file’s .HPJ file.

Private Sub mnuHelpScreen_Click()
    ExpenseForm.FileDialog.HelpCommand = cdlHelpContext
    ExpenseForm.FileDialog.HelpContext = 2
    FileDialog.ShowHelp
End Sub

Providing Context-Sensitive Help

Visual Basic provides support for context-sensitive help in two styles: Windows 3.x style and Windows 95 style. A Visual Basic application indicates which style to use by setting a form’s WhatsThisHelp property. If this property is true, the program uses the Windows 95 “what’s this” style help. If WhatsThisHelp is false, the program uses Windows 3.x style help.

Before using either style of help, the application must be associated with a help file. In the Visual Basic 4 development environment, this is done using the Options command in the Tools menu. On the Project tab, the Help File field should be filled in to indicate the location of the help file.

In the Visual Basic 5 development environment, the corresponding dialog is accessed with the Properties command at the bottom of the Project menu. This dialog’s General tab contains a Help File Name field that should contain the name of the help file.

Windows 3.x Style Help

Windows 3.x style help presents help for a control when that control has the focus and the user presses F1. When this happens, Visual Basic automatically presents the help using the context number specified by the control’s HelpContextID property.

For example, in the Visual Basic design environment, the HelpContextID property for ExpenseReporter’s NameText was set to 101. The [MAP] section of the program’s help project file associates this context number with the context string CTX_NAME.

 [MAP]
    :
CTX_NAME       101

If the user clicks on the name field to give it focus and then presses F1, Visual Basic presents the help topic with the context string CTX_NAME.

When Visual Basic presents Windows 3.x style help, a separate help window appears displaying the selected topic. The help window runs as a separate application with a life of its own. The user can click on the main application to resume working there, and the help screen will keep running. If the user later invokes help for another field or uses a Help menu command, the system uses that same window to display the new help. Figure 2.7 shows ExpenseReporter with Windows 3.x style context-sensitive help.

Windows 95 Style Help

Windows 95 style presents help for a control when the mouse is over that control and the user presses F1. Note that the field does not need to have the input focus. The mouse merely needs to be above the field. This allows the user to obtain help for objects such as label controls that cannot accept the input focus. The user simply points the mouse at the control and presses F1.

As is the case with Windows 3.x style help, Visual Basic automatically presents the help using the context number specified by the control’s WhatsThisHelpID property.