Login | Register   
RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Incorporating Help into Your Windows Applications : Page 3

How much effort do you put into ensuring that your users get all the help they need? You probably strive to design a user-friendly user interface, but do you provide any avenue for your users to get help when they are stuck?

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.





HelpKeyword on HelpProvider1



HelpNavigator on HelpProvider1



HelpKeyword on HelpProvider1



HelpNavigator on HelpProvider1


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.




The Help file opens to the index entry for the first letter of a specified topic. 



The Help file opens to the search page. 



The Help file opens to the index. 



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. 



The Help file opens to the table of contents. 



The Help file opens to a specified topic, if the topic exists. 



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.

Wei-Meng Lee is a Microsoft MVP and founder of Developer Learning Solutions, a technology company specializing in hands-on training on the latest Microsoft technologies. He is an established developer and trainer specializing in .NET and wireless technologies. Wei-Meng speaks regularly at international conferences and has authored and coauthored numerous books on .NET, XML, and wireless technologies. He writes extensively on topics ranging from .NET to Mac OS X. He is also the author of the .NET Compact Framework Pocket Guide, ASP.NET 2.0: A Developer's Notebook (both from O'Reilly Media, Inc.), and Programming Sudoku (Apress). Here is Wei-Meng's blog.
Comment and Contribute






(Maximum characters: 1200). You have 1200 characters left.