Incorporating Help into Your Windows Applications : Page 3

Displaying Microsoft Compiled HTML Help (.chm)
The third way to provide help for your users is to create a professional help application. You can do so using the Microsoft Compiled HTML Help. Microsoft Compiled HTML Help is a proprietary format for online help files, developed by Microsoft and first released in 1997 as a successor to the Microsoft WinHelp format. Microsoft Compiled HTML Help files have the extension .chm and is a standard way of providing help documentation for most Windows applications. Figure 5 shows an example of a help file (Microsoft Device Emulator).

Figure 5. The .chm File: Microsoft Compiled HTML Help files have the extension .chm.

Figure 6. Populating the Form: These controls populate your form.

There are many ways to create Microsoft Compiled HTML Help, including the HTML Help Workshop from Microsoft as well as some third party tools that greatly simplify the task. Hence this article will not be covering how to create help files. Instead, you'll see how to integrate a .chm help file into your Windows application.

Assume you have a form populated with the following controls (see also Figure 6):

Figure 7. Add a .chm File: This example uses the Help file for Microsoft Device Emulator for the project.

• Label
• Button
• CheckBox
• RichTextBox

And further assume that you have also added a .chm file into your project (see Figure 7). This example uses the Help file for Microsoft Device Emulator for the project.

Set the properties of the controls shown in Table 1.

Control	Property	Value
Button1	HelpKeyword on HelpProvider1	skins
Button1	HelpNavigator on HelpProvider1	Index
Button2	HelpKeyword on HelpProvider1	skins
Button2	HelpNavigator on HelpProvider1	KeywordIndex

Table 1.Setting the Properties for the Controls.

The HelpNavigator property determines the kind of help associated with a particular control. Table 2 shows the list of possible values. The HelpKeyword property indicates the keyword used in association with the HelpNavigator property.

Properties	Description
AssociateIndex	The Help file opens to the index entry for the first letter of a specified topic.
Find	The Help file opens to the search page.
Index	The Help file opens to the index.
KeywordIndex	The Help file opens to the topic with the specified index entry, if one exists; otherwise, the index entry closest to the specified keyword is displayed.
TableOfContents	The Help file opens to the table of contents.
Topic	The Help file opens to a specified topic, if the topic exists.
TopicId	The Help file opens to a topic indicated by a numeric topic identifier.

Table 2. Possible Values for the HelpNavigator Property.

Set the HelpNamespace property of the HelpProvider control to .\DeviceEmulator.chm (see Figure 8).

Figure 8. Pointing to the .chm File: Set the HelpNamespace property to point to the .chm file.

Figure 9. Searching: Searching using the Index page.

Notice Table 1 sets the help properties for Button1 and Button2 only. This means that when one of these Button controls has the focus, the user can press F1 to launch the .chm Help file.

Figure 9 shows that when the user selects the Button1 control and presses F1, the text "skins" will be used as a key for index search.

When the Button2 control is selected and the user presses F1, the Topics Found dialog opens (see Figure 10).

To manually open the help file, use the ShowHelp() method from the Help class. Code the View Help button as shown below:

    Private Sub btnViewHelp_Click( _
       ByVal sender As System.Object, _
       ByVal e As System.EventArgs) _
       Handles btnViewHelp.Click
        Help.ShowHelp(Me, "DeviceEmulator.chm", _
           HelpNavigator.TableOfContents)
    End Sub

This will display the Table of Contents page of the Help file (see Figure 11) when the button is clicked.

Figure 10. Display: Displaying the Topics Found dialog.

Figure 11. Display: Displaying help using the ShowHelp() method.

If you want to display the Index page, simply use the ShowHelpIndex() method:

        Help.ShowHelpIndex(Me, "DeviceEmulator.chm")

Setting the HelpKeyword and HelpNavigator properties is one way of associating help with the controls. Alternatively, you can also handle the HelpRequested event of a control, such as the following:

    Private Sub RichTextBox1_HelpRequested( _
       ByVal sender As System.Object, _
       ByVal hlpevent As System.Windows.Forms.HelpEventArgs) _
       Handles RichTextBox1.HelpRequested
        Help.ShowHelp(Me, "DeviceEmulator.chm", _
           HelpNavigator.Index, RichTextBox1.SelectedText)
    End Sub

Using this approach allows you to dynamically insert the text to search for in the help file.

The above code launches the DeviceEmulator.chm file and use the text stored in the RichTextBox control as the search key. Figure 12 shows an example when a user selects the sentence "Platform Builder" and then presses the F1 key.

Figure 12. The HelpRequested Event: When a user selects the sentence "Platform Builder" and then presses the F1 key.

Figure 13. Display: The balloon help when an action occurs.

Finally, when you want to display a little balloon help when the CheckBox control is checked, you can use the ShowPopup() method, like the following:

    Private Sub CheckBox1_CheckedChanged( _
       ByVal sender As System.Object, _
       ByVal e As System.EventArgs) _
       Handles CheckBox1.CheckedChanged
        Help.ShowPopup(Me, "Checkbox: " & CheckBox1.Checked, _
           Control.MousePosition)
    End Sub

Figure 13 shows the balloon help that is displayed every time the user checks/unchecks the CheckBox control.

The Extra Effort Pays Off
You've seen three ways to provide help for the users of your application. Remember that if you make your application easy to use, that will reduce your support cost in the long run. Hence, take the extra effort to implement the techniques introduced in this article.

Previous Page