6.19 Use Context-Sensitive Help

Problem

You want to display a specific help file topic depending on the currently selected control.

Solution

Use the System.Windows.Forms.HelpProvider component, and set the HelpKeyword and HelpNavigator extender properties for each control.

Discussion

.NET provides support for context-sensitive help through the HelpProvider class. The HelpProvider class is a special extender control. You add it to the component tray of a form, and it extends all the controls on the form with a few additional properties, including HelpNavigator and HelpKeyword . For example, Figure 6.12 shows a form that has two controls and a HelpProvider named helpProvider1 . The ListBox control, which is currently selected, has several help-specific properties that are provided through HelpProvider .

Figure 6.12: The HelpProvider extender properties.

To use context-sensitive help with HelpProvider , you simply need to follow these three steps:

1. Set the HelpProvider.HelpNamespace property with the name of the help file. (For example, an HTML Help file might be named myhelp.chm.)

2. For every control that requires context-sensitive help, set the HelpNavigator extender property to HelpNavigator.Topic .

3. For every control that requires context-sensitive help, set the HelpKeyword extender property with the name of the topic that should be linked to this control. (The topic names are help-file specific and can be configured in your help authoring tools.)

If the user presses the F1 key while a control has focus, the help file will be launched automatically and the linked topic will be displayed in the help window. If the user presses F1 while positioned on a control that doesn't have a linked help topic, the help settings for the containing control will be used (for example, a group box or a panel). If there are no containing controls or the containing control doesn't have any help settings, the form's help settings will be used. If the form's help settings are also lacking, HelpProvider will attempt to launch whatever help file is defined at the project level. You can also use the HelpProvider methods to set or modify context-sensitive help mapping at run time.