Lesson 4: Implementing Help in Your Application

Lesson 4: Implementing Help in Your Application

Too often, the importance of proper program documentation is overlooked. Providing help in your application allows users to learn it more quickly, thereby increasing productivity and saving money. In this lesson, you will learn how to display help in your applications.

After this lesson, you will be able to

• Describe how to use the Help class to display help

• Explain how to use the HelpProvider component

Estimated lesson time: 20 minutes

For complex or difficult applications, you will want to provide built-in help. You can provide help in the form of HTML files that contain a set of linked help topics or as Compressed HTML (CHM) files that you create with Microsoft HTML Help Workshop. Both of these approaches allow you to display dynamically linked help topics that you can show to your users.

The Help Class

Your application can display HTM or CHM files to users by using the Help class. The Help class encapsulates the HTML Help 1 engine and provides static methods that allow you to display your help files. The two methods exposed by the Help class are ShowHelp and ShowHelpIndex.

The ShowHelp method is used to display a help file for a particular control. This method requires the control that is the parent of the HelpDialog dialog box to be displayed as well as the help file URL. The URL can be a file URL (C:\myHelp.htm) or an HTTP URL (http://myserver.com/myHelp.htm). Because the ShowHelp method is Shared (static), you do not need to create an instance of the Help class to use it. In fact, the Help class cannot be instantiated. The following code example shows how to display help with the ShowHelp method:

Visual Basic .NET

Help.ShowHelp(MyForm, "C:\myHelpFile.htm")

Visual C#

Help.ShowHelp(MyForm, @"C:\myHelpFile.htm");

You can also specify a HelpNavigator parameter. This is a parameter that specifies which elements of the help file to display. You can set this parameter to TableOfContents, Find, Index, or Topic. You can also specify a keyword to search for, as shown in the following example:

Visual Basic .NET

Help.ShowHelp(MyForm, "C:\myHelpFile.htm", "HelpMenu")

Visual C#

Help.ShowHelp(MyForm, @"C:\myHelpFile.htm", "HelpMenu");

The Help class also exposes the ShowHelpIndex method, which is used to display the index of a specified help file. The call to ShowHelpIndex is made the same way as the call to ShowHelp.

Visual Basic .NET

Help.ShowHelpIndex(MyForm, "C:\myHelpFile.htm")

Visual C#

Help.ShowHelpIndex(MyForm, @"C:\myHelpFile.htm");

You can call the method exposed by the Help class in response to a variety of user interface events. For example, many applications include a Help menu item or allow you to right-click a control and choose help for that control from a shortcut menu. You should design your application to provide help where it is most logical and easiest for the user to access.

The HelpProvider Component

The HelpProvider component allows you to provide help for the controls on your user interface. The HelpProvider is an extender provider; thus, it coordinates and maintains properties for each control as it is added to the form. You can specify a HelpString for each control on your form. This string is displayed when the control has the focus and F1 is pressed. You can also specify a HelpNameSpace that specifies the URL for the help file associated with the HelpProvider.

The HelpProvider component provides three properties to each control on the form:

• HelpString

• HelpKeyWord

• HelpNavigator

You can set these properties in the Properties window of each control at design time or in code, as follows:

Visual Basic .NET

myHelpProvider.SetHelpString(Button1, _  "This Button initiates the self-destruct sequence")

Visual C#

myHelpProvider.SetHelpString(Button1,  "This Button initiates the self-destruct sequence");

If the HelpNameSpace property is not set, the HelpString is displayed and the other two properties are ignored. If the HelpNameSpace property is set to a help file, however, it displays the help file specified using the parameters supplied by the HelpNavigator property and the HelpKeyword property. The HelpNavigator property can be set to any of the following values:

• TableOfContents.

  Displays the table of contents page.

• Find.

  Displays the search page.

• Index.

  Displays the index.

• Topic.

  Displays a help topic.

• AssociatedIndex.

  Displays the index for a specified topic.

• KeywordIndex.

  Displays a keyword search result.

If the HelpNameSpace property is set, the HelpString no longer displays when F1 is pressed, although it can be accessed in other ways. You can retrieve the HelpString associated with a particular control by calling the HelpProvider and then calling the HelpProvider.GetHelpString method, as shown in the following example:

Visual Basic .NET

myHelpProvider.GetHelpString(Button1)

Visual C#

myHelpProvider.GetHelpString(Button1);

Lesson Summary

• The Help class provides static methods that allow you to display help for your application. You should call the Help.ShowHelp method to display help and design your application in such a way that users can easily access help when they need it.

• The HelpProvider component allows you to display either a HelpString or a help topic when the F1 key is pressed. You can set individual HelpString, HelpKeyWord, and HelpNavigator properties for each control on your form. If the HelpNameSpace is not set, the HelpString will be displayed in a pop-up dialog box. If the HelpNameSpace is specified, the appropriate help file will be displayed instead.