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.