6.5. Adding Help to a Form

 < Day Day Up > 

The majority of software users do not read documentation, except as a last resort. Users expect a program to be intuitive and provide context-sensitive documentation where it is needed. In addition to the Help option on the main menu bar, a polished program should provide assistance down to the individual controls on the form.

.NET offers multiple ways to configure an integrated help system:

  • Easy-to-use ToolTips that are displayed when the mouse moves over a control. These are specified as a control property provided by the ToolTip component.

  • The HelpProvider component is an "extender" that adds properties to existing controls. These properties enable the control to reference Microsoft HTML Help (.chm ) files.

  • A custom event handler can be written to implement code that explicitly handles the Control.HelpRequested event that is fired by pressing the F1 key or using a Help button.


This component adds mouseover capabilities to controls. If using VS.NET, you simply select the ToolTip control from the tool box and add it to your form. The effect of this is to add a string property (ToolTip on toolTip1) to each control, whose value is displayed when the mouse hovers over the control.

Of more interest is using ToolTips within a program to dynamically provide annotation for objects on a screen. Maps, which can be created dynamically in response to user requests, offer a prime example. They typically contain points of interest implemented as labels or picture boxes. As an example, consider the display in Figure 6-15, which shows a constellation and labels for its most important stars. When a user passes the cursor over the label, tool tip text describing the star is shown.

Figure 6-15. ToolTip information is displayed when mouse passes over name

Listing 6-7 shows a portion of the code that creates the form displayed in the figure. The form's BackGroundImage property is set to the image representing the constellation. Labels are placed on top of this that correspond to the position of three stars (code for only one star is shown). The Tag property of each label is set to the description of the star, and a ToolTip associates this information with the label using the SetToolTip method.

Listing 6-7. Using ToolTips to Annotate an Image
 public class StarMap:Form {    public StarMap()     {       this.Text = "Star Search";       this.Width=400;       this.Height=220;       // Place image of constellation on form       this.BackgroundImage= new Bitmap(@"c:\dracoblack.gif");       // Add name of star on Label        Label star1 = new Label();       Star1.Location = new Point(285,115);       Star1.Size = new Size(60,16);       star1.Text = "Thuban";       star1.Tag  = "   Alpha Draconis\n> Magnitude: 3.67\n>"+                    " 310 Light Years";       star1.Font = new Font(star.Font, star.Font.Style |                              FontStyle.Bold);       this.Controls.Add(star1);        ToolTip toolTip1 = new ToolTip();       toolTip1.AutoPopDelay= 1500;  // Tool tip displays                                      // for 1.5 secs.       // Tool tip text comes from Tag property of Label       toolTip1.SetToolTip(star1, star1.Tag.ToString());       // Add labels for other stars Etamin and Gianfar here ...    } } 

Core Note

To dynamically change a control's tool tip value, you must get an instance of the control's ToolTip, execute its RemoveAll method, and then use SetToolTip to reset the value of the tool tip string.

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.

Figure 6-16. The Help button

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.

Help is not enabled on a control that has ShowHelp set to false. If it is set to true, but the other properties are not set, the file referenced in HelpNameSpace is displayed. A popular Help configuration is to set only the HelpString value so that the Help button brings up a short specific message and F1 brings up an HTML page.

     < Day Day Up > 

    Core C# and  .NET
    Core C# and .NET
    ISBN: 131472275
    EAN: N/A
    Year: 2005
    Pages: 219

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net