Adding Support for Help

Adding support for Help to your Visual Basic application is really quite simple. All you need to do is set one property, HelpFile (and, of course, write and compile a Help file), to display Help when the user presses the F1 key or requests Help from a menu. An additional property, HelpContextID, can be set to provide a contextual Help topic for any user interface element in your application. The process of hooking up Help is essentially the same for both WinHelp and HTML Help.

The HelpFile Property

The HelpFile property of the App object is used to specify the file name of the Help file for your application. It requires a valid WinHelp (.hlp) or HTML Help (.chm) file. If the file doesn't exist, an error will occur.

To set the HelpFile property

  1. Select Project Properties from the Project menu to open the Project Properties dialog box.

  2. In the Help File Name field of the General tab, enter the path and file name for your application's Help file (.hlp or .chm).

You can also set the HelpFile programmatically. The following code would specify an HTML Help file that resides in the same directory as the application's executable file:

Private Sub Form_Load()
   App.HelpFile = App.Path & "\foo.chm"
End Sub

The ErrObject object also has a HelpFile property, allowing you to specify a different Help file for error messages. For example, if you have several applications that share the same error messages, you can put Help for the error messages in a single Help file that can be called by the Err.Helpfile property in each application.

The HelpContextID Property

The HelpContextID property is used to link a user interface element (such as a control, form, or menu) to a related topic in a Help file. The HelpContextID property must be a Long that matches the Context ID of a topic in a WinHelp (.hlp) or HTML Help (.chm) file.

For example, you might enter 10000 in the HelpContextID property of a TextBox. When the user selects the TextBox and presses F1, Visual Basic searches for a topic with a Context ID of 10000 in the Help file specified in the application's HelpFile property. If it's found, a Help window will open and display the topic; if not, an error will occur and the Help file's default topic will be displayed.

You should use a unique HelpContextID to match each Help topic in your Help file. In some cases, you may want to assign the same HelpContextID for several objects if the objects share a common Help topic.

You don't necessarily have to enter a HelpContextID for every control on a form. If the user presses F1 on a control with a HelpContextID of 0 (the default), Visual Basic will search for a valid HelpContextID for the control's container.

To assign a HelpContextID for a control or form

  1. Select the control or form for which you want to enter a HelpContextID.

  2. Double-click HelpContextID in the Properties window and enter a valid Long integer.

    Keep track of the value that you enter so that you can use the same value for the context ID of the associated Help topic.

    Note   For the CommonDialog control and possibly for some other controls, the name of this property is HelpContext instead of HelpContextID.

To assign a HelpContextID for a menu

  1. Select Menu Editor from the Tools menu.

  2. Choose the menu item for which you want to enter a HelpContextID.

  3. Enter a valid Long in the Select the HelpContextID box.

    Keep track of the value that you enter so that you can use the same value for the context ID of the associated Help topic.

The HelpContextID can also be entered programmatically as follows:

Private Sub Form_Load()
   Command1.HelpContextID = 12345
   MenuHelp.HelpContextID = 23456
   Err.HelpContext = 34567
End Sub

Tip   If you have more than a few Help topics, it may help to establish a numbering scheme before you start entering HelpContextID's. Assign a different range of numbers for each form or major element in your application, for example, 1000 – 1999 for the first form, 2000 – 2999 for the second, and so forth.