One easy way to use Help with a .NET application is by adding the HelpProvider control. This "invisible" control shows up in the component tray (Figure 14-5).
Figure 14-5: The HelpProvider
The HelpProvider uses a basic HelpNamespace property that sets the help source. This could be a path to an ordinary .hlp file, an HTML Help .chm file, or even a URL. To bind a control to this HelpProvider, you simply need to set the extended ShowHelp property to true. In other words, when you add a HelpProvider to a form, every control acquires a special property in the designer (with a name like ShowHelp on HelpProvider). Set this to true, and the help file is automatically launched if the user presses the F1 key while this control has focus.
You can also connect or disconnect help manually in code, using the HelpProvider.SetShowHelp() method. Just pass the control that you want to use as an argument.
private void HelpTest_Load(object sender, System.EventArgs e)
{
// This turns on F1 help support for cmdAdd.
hlp.SetShowHelp(cmdAdd, true);
// This disables it.
hlp.SetShowHelp(cmdAdd, false);
}
There really isn't any difference between using the SetShowHelp() method and the extended ShowHelp property provided by the designer.With providers, Visual Studio .NET simply translates your selections into the appropriate method calls, and adds the code to the form code. So when you set the ShowHelp property, you are still in fact using the SetShowHelp() method.You can also set the HelpKeyword and HelpNavigator properties in conjunction to configure which topic is shown when the Help is invoked. Table 14-1 outlines all the possible options you have with the HelpNavigator enumeration. Note that while all these choices are supported by HTML Help, the support in WinHelp and WinHelp 95 is notoriously poor.
Table 14-1: Values for the HelpNavigator Enumeration
HelpNavigatorDescription
TableOfContentsShows the table of contents for the Help file. This is the most common option if you aren't linking to a specific topic.
IndexShows the index for the Help file, if it exists.
KeywordIndexShows the index, and automatically highlights the first topic that matches the HelpKeyword property. For example, if HelpKeyword is "format" for this control, the most similar entry is highlighted in the index list.
FindShows the search page for the Help file, which allows the user to perform unguided text searches. This feature tends to provide poorer (and slower) results than the index or table of contents, and is thus avoided if possible.
TopicThe most useful option for context-sensitive help. If you choose this option, you can set the topic identifier as a HelpKeyword. For example, you could use the topic URL in an HTML Help file (like about). When the Help is launched, this topic is browsed to and displayed automatically.
For example, the following two lines of code define a context-sensitive link that binds a control to a specific topic in an HTML Help file.
// Specify a topic link. hlp.SetHelpNavigator(ctrl, HelpNavigator.Topic); // Identify the topic. hlp.SetHelpKeyword(ctrl, "Welcomel");
Note that the topic name is "Welcomel." In this case, the example is using a .chm file, and the original HTML Help project included the topic in a source file named Welcomel. Once the .chm file is created, this file no longer exists separately. Instead, like all topics, it is combined into the compiled help file. However, the file name can still be used as a help keyword to select the topic. Your other option (and your only option with the older WinHelp format) is to use context integers, which are numbers that uniquely identify each topic.
Alternatively, you don't need to use a Help file at all. Instead, you can display a pop-up window with a short message (formerly referred to as "What's This Help"). To do so, make sure that you do not set the HelpProvider.HelpNamespace property, which always takes precedence. Then, either set the HelpString on the HelpProvider property at design-time, or use the SetHelpString method, as shown here:
hlp.SetHelpString(cmdAdd, "Choose another item from the catalog."); hlp.SetHelpString(cmdDelete, "Delete the selected item from your order.");
The resulting pop-up message is shown in Figure 14-6.
Figure 14-6: What's This Help
What's This Help was at one point considered a great new approach for creating help, because it doesn't force the user to look in another window. Instead, it integrates help directly in the interface.What's This Help never really caught on, for a number of reasons, including the fact that it only allows the display of limited, unformatted information (for example, you can't bold command names), and it forces the user to understand the rather complicated model of changing focus to the correct control, and then pressing F1.Note that when you set use the SetHelpString() or SetHelpKeyword() methods, you automatically enable help for the control. That means that you don't need to call the SetShowHelp() method, unless you want to explicitly disable help for the control.
Control-by-control context-sensitivity is usually too much for an application. It's rare that a Help file is created with separate topics for every control in a window, and even if it were, most users simply press F1 as soon as they encounter a confusing setting. In other words, they don't explicitly tab to the setting they want to find out about to give it focus before invoking Help. For that reason, the control that is launching Help is quite possibly not the control the user is seeking information about.
One easy way around this is to define an individual context-sensitive help topic for every form. For a settings dialog, this topic should contain a list of every option. Nicely designed Help might even use dynamic HTML to make this list collapsible (see, for example, Figure 14-7).
Figure 14-7: Collapsible help for one window
The only subtlety to understand with form-based Help is that when you enable Help for the form, you also enable Help for every control it contains. If the user presses F1 while the focus is on a control that is specifically configured with different Help settings, these settings take precedence. If, however, the current control has ShowHelp set to false, the request will be forwarded to the containing form, which launches its own Help. This process works analogously with all container controls, and it allows you to define Help that's as specific as you need, while still being able to fall back on a generic form-wide topic for controls that aren't specifically configured.
The online samples for this chapter include a HelpTest project that shows a simple project with three windows. Each of three windows uses a different granularity of help: form-based, frame-based, and control-based.You can run this application with the included Help file to get a better understanding of the options you have for linking context-sensitive help to an application.