Visual Studio provides two primary methods of integrating online help into desktop applications. The first uses the HelpProvider control, found in the Components section of the Visual Studio Toolbox. The second uses the Help.ShowHelp method of the Windows forms package. Both methods let you display specific pages or portions of a compiled HTML Help file.
The HelpProvider control can be added to a form to enable access to online help. It provides two primary online help experiences: (1) standard access to compiled HTML Help files; and (2) popup help. Both methods put the focus on individual controls of a form, and on the specific help features to be tied to each control.
Accessing HTML Help Files
To use the HelpProvider control with compiled HTML Help files, set the control's HelpNamespace property to the location of a valid help file. Then adjust the properties of other controls on the form to refer to specific features within the help file. The HelpProvider control impacts other controls by adding several additional properties to each. Figure 23-7 shows the four additional properties (HelpKeyword, HelpNavigator, HelpString, and ShowHelp) automatically added to a Button control.
Figure 23-7. Adding help support to individual controls
The HelpNavigator property added to each control defines what features of the help file to access when the user presses the F1 key while that control has the focus. To access a specific page within the help file (such as welcome.htm), set the target control's HelpNavigator property to "Topic" and set the related HelpKeyword property to the file name of the page ("welcome.htm").
The HelpNavigator property for a control can be set to access non-page sections of the online help file as well. The value "TableOfContents" displays the file's contents outline; "Index" jumps to the keyword index. There are a few other choices as well.
Showing Popup Help
The HelpProvider control also enables "popup" help on individual controls. This help variation causes a small tool tip window to appear just above a control, displaying a short message that provides usage information for that control, as shown in Figure 23-8.
Figure 23-8. Popup help on a button control
Popup help works when you enable the "Popup Button" in the form's title bar. To set popup help for a control, follow these steps.
The user displays popup help by first clicking on the question-mark "help" button in the form's title bar, and then clicking on a control.
The System.Windows.Forms.Help.ShowHelp method displays specific portions of a compiled HTML Help file based on the arguments passed to the method. It's quite similar to the file-based help portion of the HelpProvider control, but in method form. To display a specific page within a help file, use this syntax.
Windows.Forms.Help.ShowHelp(Me, "Simple.chm", _ HelpNavigator.Topic, "moreinfo.htm")
The first argument is a reference to the form calling the method.
A common way of using this method is to monitor the form for the F1 key, and call ShowHelp from the form's KeyDown event handler.
Private Sub Form1_KeyDown(ByVal sender As Object, _ ByVal e As System.Windows.Forms.KeyEventArgs) _ Handles Me.KeyDown ' ----- Call online help. If (e.KeyCode = Keys.F1) Then Windows.Forms.Help.ShowHelp(Me, "Simple.chm", _ HelpNavigator.Topic, "moreinfo.htm") End If End Sub
You must set the form's KeyPreview property to True to trigger the form-level KeyDown event. Otherwise, all keys go to the active control and bypass the form-level events.
The ShowHelp method offers a lot more control over the user's online help experience because you (and not the HelpProvider control) determine exactly when to access the help file.