How to provide context-sensitive help or online help in a Windows application by using Visual Basic (821777)


The information in this article applies to:

  • Microsoft Visual Studio 2005 Standard Edition
  • Microsoft Visual Studio 2005 Professional Edition
  • Microsoft Visual Studio .NET (2003), Professional Edition
  • Microsoft Visual Studio .NET (2003), Enterprise Architect Edition
  • Microsoft Visual Studio .NET (2003), Enterprise Developer Edition
  • Microsoft Visual Studio .NET (2003), Academic Edition
  • Microsoft Visual Studio .NET (2002), Professional Edition
  • Microsoft Visual Studio .NET (2002), Enterprise Architect Edition
  • Microsoft Visual Studio .NET (2002), Enterprise Developer Edition
  • Microsoft Visual Studio .NET (2002), Academic Edition
  • Microsoft Visual Basic 2005
  • Microsoft Visual Basic .NET (2003)
  • Microsoft Visual Basic .NET (2002)

SUMMARY

This step-by-step article describes how to provide online help pages and context-sensitive help for the controls in a Microsoft Windows application. The example uses the HelpProvider class and the Help class to provide help for the controls in the application.

Requirements

The following list outlines the recommended hardware, software, network infrastructure, and service packs that you need:
  • Microsoft Visual Studio 2005 or Microsoft Visual Studio .NET
  • Internet Connectivity
This article assumes that you are familiar with the following topics:
  • Microsoft Visual Basic 2005 or Microsoft Visual Basic .NET programming

About the HelpProvider class

The HelpProvider class provides context-sensitive help or online help pages for controls. Each instance of HelpProvider maintains a collection of references to the controls that are associated with the instance. To provide online help pages for the control, set the HelpNamespace property of HelpProvider, and then associate a Help file with the HelpProvider object.

You can specify the type of help that the application provides for the control by calling the SetHelpNavigator method, and by providing a HelpNavigator value for the specified control. Help and HelpProvider use the HelpNavigator enumeration to provide access to specified elements of the Help file. The members of HelpNavigator are the following:
  • AssociateIndex
  • Find
  • Index
  • KeywordIndex
  • TableOfContents
  • Topic
You provide the keyword or topic for the Help file by calling the SetHelpKeyword method. You use the SetHelpString method of HelpProvider to associate a specific Help string with a control. The string that you associate with a control by using the SetHelpString method appears in a pop-up window when you press F1 while the control has focus.

When HelpNamespace is not set, use SetHelpString to provide the help text. When you set both HelpNamespace and the Help string, the help that is based on the HelpNamespace takes precedence.

About the Help class

The Help class provides help to an application by calling the static ShowHelp method and the static ShowHelpIndex method. The ShowHelp method displays the contents of a Help file. The ShowHelpIndex method displays the index of the specified Help file. You can use the Help object to display Help files such as Compiled Help Module (.chm) files or HTML files that are in the HTML Help format.

Use the HelpProvider class to provide online help for controls

The following example describes how to use the HelpProvider class to display context-sensitive Help file content for a form that contains controls.

Set the HelpNamespace property of the HelpProvider class to an HTML file or to a .chm file. To do this, follow these steps:
  1. Start Microsoft Visual Studio 2005 or Microsoft Visual Studio .NET.
  2. On the File menu, point to New, and then click Project.
  3. Under Project Types, click Visual Basic Projects. Under Templates, click Windows Application, and then click OK. By default, a form that is named Form1 is created.

    Note In Visual Studio 2005, click Visual Basic under Project Types.
  4. Add a HelpProvider component to the Form1 form.
  5. Right-click HelpProvider1, and then click Properties.
  6. In the Properties dialog box, set the HelpNamespace property to http://msdn.microsoft.com/library/en-us/vbcon/html/vbconbuttoncontroloverview.asp.
  7. Add a Button control to the Form1 form. Button1 is created.
  8. In the Properties dialog box of Button1, set ShowHelp on HelpProvider1 to True.
  9. Set the Text property of Button1 to Submit.

Use the HelpProvider class to provide context-sensitive help for controls

The following example describes how to use the HelpProvider class to display help for the controls in a pop-up window. Use the SetHelpString method of the HelpProvider class to set the Help ToolTip text for the controls. When you click the Help button on the title bar of the Form1 form, and then click the control, the Help string appears.
  1. Add two TextBox controls to the Form1 form.
  2. Add the following sample code to the Form1_Load event handler.
    'Set the Help string for the TextBox control on the form.
HelpProvider1.SetHelpString(Me.TextBox1, "Enter your UserName")
HelpProvider1.SetHelpString(Me.TextBox2, "Enter your Password in this TextBox")
'Set the Help string for the Button control on the form.
HelpProvider1.SetHelpString(Me.Button1, "Click submit after you type your UserName and Password")
  3. Right-click Form1, and then click Properties.
  4. In the Properties dialog box, set HelpButton to True.
  5. Set MaximizeBox to False.
  6. Set MinimizeBox to False.

Use the SetHelpNavigator method to provide a specified type of help

The following example describes how to use the SetHelpNavigator method to retrieve the table of contents from the Notepad.chm Help file.
  1. Add a HelpProvider component to the Form1 form.
  2. Right-click HelpProvider2, and then click Properties.
  3. In the Properties dialog box, set the HelpNamespace property of HelpProvider2 to the path of the Notepad.chm file that is on your computer. For example, set the path to C:\WINDOWS\Help\Notepad.chm.
  4. Add a Button control to the Form1 form.
  5. In the Properties dialog box, set the Text property of Button2 to Save UserName in Notepad.
  6. Set the ShowHelp on HelpProvider2 property of Button2 to True.
  7. Add the following statement at the top of the code in the Form1 form.
    Imports System.IO
  8. Add the following sample code to the Button2_Click event handler.
    Dim path As String = "c:\temp\MyTest.txt"
Dim sw As StreamWriter
' This text is added to the file only one time.
If File.Exists(path) = False Then
      ' Create a file to write to.
      sw = File.CreateText(path)
      'Write the UserName and the password to the text file.
      sw.WriteLine(TextBox1.Text)
      sw.WriteLine(TextBox2.Text)
      sw.Flush()
      sw.Close()
End If
  9. Add the following sample code to the Form1_Load event handler.
    'Display the Table of Contents of the Help file when you press F1. 
HelpProvider2.SetHelpNavigator(Button2, HelpNavigator.TableOfContents)

Use the Help class to display an online Help file for a control

The following example describes how to use the ShowHelp method of the Help class to display the Help file for the ListBox control. If the control has focus, the Help file appears when you press F1.
  1. Add a ListBox control to the Form1 form.
  2. Right-click ListBox1, and then click Properties.
  3. In the Properties dialog box, click the Items property, and then click the ellipsis button (...).
  4. In the String Collection Editor dialog box, type the following strings:
    • Domain1
    • Domain2
    • Domain3
  5. Click OK.
  6. Add the following sample code to the ListBox1_KeyDown event handler.
     If e.KeyCode = Keys.F1 Then
       'Display the Help file for the ListBox control when you press F1.
       Help.ShowHelp(ListBox1, "http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbcon/html/vboriListBoxControlProgramming.asp")
End If

Verify that it works

  1. On the Build menu, click Build Solution.
  2. On the Debug menu, click Start.
  3. Click the Help (?) button on the toolbar of the Form1 form, and then click any of the following controls:
    • TextBox1
    • TextBox2
    • Submit
    The context-sensitive help for the control appears.
  4. When the Submit button has focus, press F1. The Help file for the Submit control appears.
  5. When the ListBox1 control has focus, press F1. The Help file for the ListBox1 control appears.
  6. When the Save UserName in Notepad button has focus, press F1. The Help file for Notepad appears.

REFERENCES

For more information, visit the following Microsoft Developer Network (MSDN) Web sites:

http://msdn.microsoft.com/library/en-us/vbcon/html/vborihelpproviderctltasks.asp

http://msdn.microsoft.com/library/en-us/cpref/html/frlrfSystemWindowsFormsHelpClassTopic.asp

Modification Type:MinorLast Reviewed:10/3/2006
Keywords:kbvs2005applies kbvs2005swept kbhelpfile kbhelp kbHOWTOmaster kbhowto kbControl kbCtrl kbForms kbWindowsForms KB821777 kbAudDeveloper
©2004 Microsoft Corporation. All rights reserved.