6.5. Adding Help to a Form

Responding to F1 and the Help Button

Many users regard the F1 key as a de facto way to invoke help. .NET provides built-in F1 support by causing a Control.HelpRequested event to fire when the user presses the F1 key. This event also fires when a user clicks the context-sensitive Help button at the top of a form and then clicks on a control using the Help cursor. See Figure 6-16.

The Help button is displayed by setting these form properties:

• Set MinimizeBox and MaxmizeBox to false .

• Set HelpButton to true .

A recommended approach is to create one event handler routine and have each control invoke it. As an example, the following code defines delegates for two text boxes that notify the ShowHelp method when the HelpRequested event occurs. This method uses either a Tag property associated with each control or the control's name to specify help germane to that control.

this.date.HelpRequested  += new HelpEventHandler(ShowHelp);

this.ssn.HelpRequested   += new HelpEventHandler(ShowHelp);

this.ssn.Tag   = "Enter as: nnn-nn-nnnn";

this.date.Tag  = "Enter as: mm/dd/yyyy";



private void ShowHelp(object sender, HelpEventArgs e)

{

   Control reqControl = (Control)sender;

   // Technique 1: Use tag associated with control

   MessageBox.Show(reqControl.Tag.ToString());

   // Technique 2: Link to specific text within a CHM file

   string anchor = "#"+reqControl.Name;

   // ShowHelp invokes a compiled Help file

   Help.

ShowHelp

(reqControl,@"c:\ctest.chm",HelpNavigator.Topic,

                 "customers.htm"+anchor);

   e.Handled = true;  // Always set this

}

The event handler receives two arguments: the familiar sender that identifies the control that has focus when the event occurs and HelpEventArgs , which has Handled and MousePos as its only two properties. Handled is set to indicate the event has been handled. MousePos is a Point type that specifies the location of the cursor on the form.

The method provides context-sensitive help by identifying the active control and using this knowledge to select the Help text to be displayed. In this example, the first technique displays the tag property of a control as the Help message. The second—and more interesting technique—uses Help.ShowHelp to display a section of an HTML file that uses the control's name as an anchor tag. Specifically, it looks inside ctest.chm for the customers.htm page. Then, it searches that page for a named anchor tag such as <a name=ssn> . If found, it displays the HTML at that location.

ShowHelp is the most useful method of the Help class. It includes several overloads to show compiled Help files ( .chm ) or HTML files in an HTML Help format.

// URL may be .chm file or html file

public static void ShowHelp(Control parent, string url);



// HelpNavigator defines the type of .chm file to be displayed

public static void ShowHelp(Control parent, string url, 

                            HelpNavigator navigator);



// Displays contents of Help file for a specified keyword

public static void ShowHelp(Control parent, string url,

                            string keyword);



// param is used with HelpNavigator.Topic to refine selection

public static void ShowHelp(Control parent, string url,

                            HelpNavigator navigator, object param);

The HelpNavigator enumeration specifies which part of a .chm file is displayed. It's values include TableofContents , Find , Index , and Topic . If you are unfamiliar with them, compiled Help files package multiple HTML files along with an optional table of contents and keyword indexes. The downloadable Microsoft HTML Help Workshop is the easiest way to learn how to use and create these files.

The HelpProvider Component

This component is a wrapper that is used primarily with Visual Studio.NET. Its main value is that it eliminates the need to explicitly handle the HelpRequested event. It is an extender that adds several properties to each control. These properties essentially correspond to the parameters in the ShowHelp method, which it calls underneath.

Add the HelpProvider to a form by selecting it from the tool box. Then, set its HelpNameSpace property to the name of the HTML or .chm file that the underlying ShowHelp method should reference (this corresponds to the URL parameter).

Each control on the form adds four extended properties:

1. ShowHelp . Set to true to make activate Help feature.

2. HelpNavigator . Takes the HelpNavigator enumeration value.

3. HelpKeyword . Corresponds to the param or keyword parameter in ShowHelp .

4. HelpString . This contains a message that is displayed when the Help button is used to click a control.