MS Help 2.x‎ > ‎

.NET Application Help

  • 24-June-2002 - Initial upload.
  • 5-Nov-2003 - Introduction added and extra further reading links.
  • 6-feb-2004 - Link to report on Associated links and how to fix them.

Introduction by Rob Chandler

MS Help 2.x help was designed for the VS .NET environment only (and now also used by Borland .NET online help). Applications you create with your .NET compiler (VB .NET and C#) ordinarily use HTML Help 1.x (chm files).

The first thing you may notice about .NET applications is they no longer support calling help using numeric Context IDs. Instead they typically uses a Context Keyword string, the Keyword/URL mapping information being stored in the "A" or "K" index of the CHM. There is nothing to stop you from still using numeric context IDs but they will need to be converted and stored as a keyword string. Alternatively keep "Context ID to URL" mapping information on the application side, in an INI file or hard coded in switch statement. I prefer an INI file as you can correct help mapping problems without recompiling the application or help (less evaluation required). Having said all that I'll pass you over to Michael Waltuch.

ALink support broken

C# and VB .NET documentation seems to suggest that accessing help via Associated Keywords is support, however we recently found this feature to be broken in VS 2003.


Working with HH 1.x Chm Files in .NET Applications

By Michael Waltuch from ESRI

This brief tutorial will show you some of the new user assistance features available in VB.NET and C#.


1. Introduction
 

This tutorial will show you how to:

  • create Tooltip strings
  • create What's This Help
  • use HelpProviders
  • create popup help for a control in a dialog based on a text string
  • create popup help for a dialog based on an .htm file not included in a .chm
  • display a specific topic in a .chm file with F1
  • display a topic in a .chm file by keyword
  • open any help file from an application so that it's set at the Contents tab, the Index tab, or the Search tab
  • display ErrorProvider strings in response to user actions

To follow the steps of the tutorial, you'll need Visual Studio .NET.

The tutorial will demonstrate how to accomplish these tasks using the Visual Studio .NET IDE user interface and will supplement this with brief code excerpts that show you how to accomplish these tasks using either Visual Basic .NET or C#.


2. Getting Started
 

  1. If you haven't already done so, download the H2Reg utility. This tutorial will use the H2Reg Help chm file that's included as part of the download.
  2. For all sections of this tutorial we'll use the same project so, in Visual Studio .NET, create a new Windows Application project, using either Visual Basic or C#.


3. Working with Tooltips
 

The Windows Forms ToolTip component displays text when the user points at controls. A ToolTip can be associated with any control.

  1. In the Toolbox, double-click the Button control. A new Button control will appear on the project's default form. You can reposition the Button control on the form.
  2. In the Toolbox, double-click a ToolTip component. The component will appear in the area below the form.
  3. Select the Button control on the Form and then press F4 to display the Button control's properties. Find the property named "ToolTip on toolTip1". Click in the text area to the right of the property name and enter the text, "Performs an action".
  4. Press F5 to Start. After the application compiles, you'll see the Form. Move the mouse so that it hovers over the button on the form. The ToolTip appears.

  5. Press Shift+F5 to Stop Debugging.
  6. You can use the same ToolTip component to serve as the source of tooltip functionality for all the controls on a form. Add another Button control to the form. Press F4 and then locate the property named "ToolTip on toolTip1". Note that its value has not been assigned for the Button control you just added. Click in the text area to the right of the property name and enter the text, "ToolTip for 2nd button".
  7. Press F5 to Start. Move the mouse over each button to see the tip you've assigned.
  8. Press Shift+F5 to Stop Debugging.

    9. If you're writing code...

    To set a ToolTip you've added to a project using code, do the following:

    [Visual Basic]
ToolTip1.SetToolTip(Button1, "Performs an action")
ToolTip1.SetToolTip(Button2, "ToolTip for 2nd button")

    [C#]
toolTip1.SetToolTip(button1, "Performs an action");
toolTip1.SetToolTip(button2, "ToolTip for 2nd button");


4. Creating What's This Help
 

To create What's This Help, take the following steps.

  1. In design mode, make the Form active and press F4 to display its properties. Find the property named "HelpButton" and toggle its value to True. Look at the form; nothing has seemingly changed!

    To make the HelpButton visible you must change the value of two other properties, in effect turning the form into a dialog.

  2. Find the MaximizeBox property and toggle its value to False. Do the same for the Minimize Box. 
    Look at the form now. You'll see that a HelpButton has been added.
  3. Now that you've got a HelpButton, let's add a control to the form. In the Toolbox, double-click a CheckBox control and then drag it from its default position to the middle of the form.
  4. Press F5 to Start. Click the HelpButton to enable What's This Help. The cursor changes. Now click on the CheckBox or one of the buttons. Nothing happens. We haven't specified a source for help. To do this, we'll add a HelpProvider component in the next section.

    5. If you're writing code...

    The following code excerpt displays a HelpButton for a form in its caption bar:

    [Visual Basic]
' Display a help button on the form.
form1.HelpButton = True   
' Define the border style of the form to a dialog box.
form1.FormBorderStyle = FormBorderStyle.FixedDialog
' Set the MaximizeBox to false to remove the maximize box.
form1.MaximizeBox = False
' Set the MinimizeBox to false to remove the minimize box.
form1.MinimizeBox = False

    [C#]
// Display a help button on the form.
form1.HelpButton = true;
// Define the border style of the form to a dialog box.
form1.FormBorderStyle = FormBorderStyle.FixedDialog;
// Set the MaximizeBox to false to remove the maximize box.
form1.MaximizeBox = false;
// Set the MinimizeBox to false to remove the minimize box.
form1.MinimizeBox = false;


5. Working with HelpProviders
 

The Windows Forms HelpProvider component is used to associate an HTML Help 1.x Help file, an HTMLHelp 2.0 help file, or a standalone .htm file with your Windows application. You can even specify an http:// address. Adding a HelpProvider component to your Windows Form allows the other controls on the form to expose the Help properties of the HelpProvider component. This enables you to provide help for the controls on your Windows Form. In addition to displaying topics in .chm files or .htm files, you can use the HelpProvider to display popup text.

To create popup help for a control using a text string

  1. In the Toolbox, double-click the HelpProvider component. A new component will appear in the area below the form.
  2. Click on the form and then set the focus to the CheckBox.
  3. Press F4 to display the CheckBox control's properties.
  4. Set the HelpString on HelpProvider1 property to "Enable a feature with this checkbox".
  5. Press F5 to Start. When the application displays the form, click the HelpButton and then click the checkbox. You'll see the popup topic.
  6. Press Shift+F5 to return to design mode.

    7. If you're writing code...

    To create popup help for a control from a text string using code, do the following:

    [Visual Basic]
HelpProvider1.SetHelpString(CheckBox1, "Enable a feature with this checkbox")

    [C#]
helpProvider1.SetHelpString (checkBox1, "Enable a feature with this checkbox");

To display help for a form or dialog using the contents of an .htm file

  1. In the area below the form, click on the HelpProvider component.
  2. Press F4 to display the HelpProvider component's properties.
  3. Set the HelpNamespace property to "http://helpware.net/FAR/help/hh_start.htm".
  4. Press F5 to Start. When the application displays the form, press F1. Your default browser will display the topic.
  5. Set focus back to Visual Studio, then press Shift+F5 to return to design mode.

To display a help topic in a .chm file as help for a control

  1. Click on the HelpProvider component in the area below the form.
  2. Press F4 to display the HelpProvider component's properties.
  3. Change the HelpNamespace property; click its browse button to locate the HH 1.x help file for the H2Reg utility, h2reg.chm. It should be in the H2Reg\h1help folder.
    The file name retrieved by this method identifies the file that provides Help support for all the controls for which this object provides Help. This file name can designate either a compiled Help file (.chm) or a raw HTML file.
  4. Click Button1 and then press F4 to display its properties.
  5. Set the HelpKeyword on HelpProvider1 property to "html/dynamichelp2.htm".
    The HelpKeyword property provides the key information to retrieve the help associated with the control from the Help file specified by HelpNamespace. The h2reg.chm structure is such that .htm files are stored in a folder named "html". The property reflects this structure.
  6. Set the HelpNavigator on HelpProvider1 property to "Topic".
    The HelpNavigator property is an enumeration that specifies the Help command to use when retrieving Help from the Help file for the specified contol.
  7. Press F5 to Start. When the application displays the form, click the HelpButton and then click Button1. The help topic, "About This Button" appears.
  8. Set focus back to Visual Studio, then press Shift+F5 to return to design mode.

    9. If you're writing code...

    To display a help topic in a .chm file as help for a control by writing code, do the following:

    [Visual Basic]
HelpProvider1.HelpNamespace = "C:/Program Files/H2Reg/h1help/h2reg.chm"
HelpProvider1.SetHelpNavigator(Button1, HelpNavigator.Topic)
HelpProvider1.SetHelpKeyword(Button1, "html/dynamichelp2.htm")

    [C#]
helpProvider1.HelpNamespace = "C:/Program Files/H2Reg/h1help/h2reg.chm";
helpProvider1.SetHelpNavigator(button1, HelpNavigator.Topic);
helpProvider1.SetHelpKeyword(button1, "html/dynamichelp2.htm");

To display a help topic in a .chm file by keyword

  1. Click Button2 and then press F4 to display its properties.
  2. Set the HelpKeyword on HelpProvider1 property to "H2Reg Support".
  3. Set the HelpNavigator on HelpProvider1 property to "KeywordIndex".
    This value for HelpNavigator directs HelpProvider to search for a topic containing a keyword that matches the value of the HelpKeyword property associated with the control.
  4. Press F5 to Start. When the application displays the form, click the HelpButton and then click Button2. The help topic, "Support" appears.
  5. Set focus back to Visual Studio, then press Shift+F5 to return to design mode.

    6. If you're writing code...

    To display a help topic in a .chm file by keyword using code, do the following:

    [Visual Basic]
HelpProvider1.HelpNamespace = "C:/Program Files/H2Reg/h1help/h2reg.chm"
HelpProvider1.SetHelpNavigator(Button2, HelpNavigator.KeywordIndex)
HelpProvider1.SetHelpKeyword(Button2, "H2Reg Support")

    [C#]
helpProvider1.HelpNamespace = "C:/Program Files/H2Reg/h1help/h2reg.chm";
helpProvider1.SetHelpNavigator(button2, HelpNavigator.KeywordIndex);
helpProvider1.SetHelpKeyword(button2, "H2Reg Support");

To open a help file set to the Contents, Index, or Search tab

  1. In the ToolBox double-click the MainMenu control.
  2. Click the first Type Here box and type "&Help".
  3. In the Type Here box directly below the first box, type "&Contents..."
  4. Add two more menu items beneath Contents menu item: "&Index..." and "&Search..."
  5. Double-click the Contents menu item and then add the following code to display the .chm file set to the Contents Tab:
    6. [Visual Basic]
Private Sub MenuItem2_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem2.Click
  Help.ShowHelp(Me, HelpProvider1.HelpNamespace)
End Sub

    [C#]
private void menuItem2_Click(object sender, System.EventArgs e)
{
  Help.ShowHelp(this, helpProvider1.HelpNamespace);
}
  6. To display the .chm file set to the Index tab, double-click the Index menu item and then add the following code:
    7. [Visual Basic]
Private Sub MenuItem3_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem3.Click
  Help.ShowHelpIndex(Me, HelpProvider1.HelpNamespace)
End Sub

    [C#]
private void menuItem3_Click(object sender, System.EventArgs e)
{
  Help.ShowHelpIndex(this, helpProvider1.HelpNamespace);
}
  7. To display the .chm file set to the Search tab, double-click the Search menu item and then add the following code:
    8. [Visual Basic]
Private Sub MenuItem4_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MenuItem4.Click
  Help.ShowHelp(Me, HelpProvider1.HelpNamespace, HelpNavigator.Find, "")
End Sub

    [C#]
private void menuItem4_Click(object sender, System.EventArgs e)
{
  Help.ShowHelp(this, helpProvider1.HelpNamespace, HelpNavigator.Find,"");
}
  8. Press F5 to Start. When the application displays the form, click the Help menu's items to see the results of your work.


6. Working with ErrorProviders
 

While not strictly in the realm of Help, ErrorProvider components are related to Help in that they afford the opportunity to give user assistance and control flow-of-control when the application detects an error or an inappropriate action.

  1. In the Toolbox double-click the ErrorProvider component. A new component will appear in the area below the form.
  2. In the Toolbox double-click the TextBox control. Resize and reposition it on the form.
  3. Press F4 to display the properties for the textbox.
  4. Set the Text property to a blank string.
  5. Set the Error on ErrorProvider1 property to "Please enter a numeric value".
  6. Press F5 to Start. When the application displays the form, hover the mouse over the ErrorProvider icon to the right of the textbox. You'll see the message.

    7. What we've done so far isn't really the intent of the ErrorProvider component. The same effect could be achieved with a ToolTip. Using an ErrorProvider component is approriate when validating data. The next step will demonstrate how to do this.

  7. Using the technique appropriate to the language you're using create an event handler for the TextBox on the form and add the following code to it: 
    [Visual Basic]
Private Sub TextBox1_Validating(ByVal Sender As Object, ByVal e As System.ComponentModel.CancelEventArgs) Handles TextBox1.Validating
  If Not IsNumeric(TextBox1.Text) Then
    ErrorProvider1.SetError(TextBox1, "Not a numeric value.")
  Else
    ' Clear the error.
     ErrorProvider1.SetError(TextBox1, "")
  End If
End Sub

    [C#]
private void textBox1_Validating(object sender, System.ComponentModel.CancelEventArgs e)
{
    try 
    {
      int x = Int32.Parse(textBox1.Text);
      errorProvider1.SetError(textBox1, "");
    }
    catch 
    {
      errorProvider1.SetError(textBox1, "Not an integer value.");
    }
}
  8. Press F5 to Start. When the application displays the form, hover the mouse over the ErrorProvider icon to the right of the textbox. You'll see the original message.
  9. Now type "HelpWare" in the TextBox and then press the Tab key to move focus to another control. You'll see the icon flash. Hover the mouse over the flashing icon to see the error message.
  10. Go back to the TextBox and enter "123". Press the Tab key to move focus to another control. The icon doesn't display.


6. Links. Further Reading.
 

This has been a quick tour of using HH 1.x help files with the .NET help-related components. The Visual Studio Help Collection goes into greater detail about the classes, controls, and components referred to here. You may want to refer to the following topics:

Rob Chandler adds: 
You can also display help (via the .NET Framework Class library) by invoking the Help.ShowHelp Method (System.Windows.Forms.Help object, a static class that encapsulates the HTML Help 1.x engine.). This is a higher level method for opening a CHM.

MS Web links


Home Page | Back to MS Help 2 Info Page

Comments