AppHelp Info

Help Systems in Windows Forms

One of the most important assistance you, as a developer of applications, can furnish your users with is a competent Help system. This is where they will turn when they become confused or disoriented. Providing a Help system in a Windows-based application is easily done by using the HelpProvider Component.

Different Types of Help

The Windows Forms HelpProvider component is used to associate an HTMLHelp 1.x Help file (either a .chm file, produced with the HTMLHelp Workshop, or an .htm file) with your Windows-based application. The HelpProvider component can be used to provide context-sensitive Help for controls on Windows Forms or specific controls. Additionally, the HelpProvider component can open a Help file to specific areas, such as the main page of a table of contents, an index, or a search function. For information on how to use the HelpProvider component to show pop-up Help on Windows Forms, see AppHelp Pop-Up. For information on using the ToolTip component to show control-specific Help, see Control Help Using ToolTips.

You can generate HTML Help 1.x files with the HTMLHelp Workshop or another Help Authoring Tool. For more information about HTML Help, see “HTMLHelp Workshop” or the other HTMLHelp topics on this website.

The following screenshot shows an example of the help window for the freeware program 7-Zip. Incidentally, this program can also be used to extract help files in CHM format.

Integrate simple application help

There is a System.Windows.Forms.Help object that is working together with the HelpProvider component to show CHM or HTML help files. You can use it in the forms "Help" menu. To provide Help to your application, call the ShowHelp und ShowHelpIndex methods. The Help object is a static class that encapsulates the HTMLHelp 1.x engine, it cannot be instantiated and its methods must be called directly.

In Visual Studio, drag a HelpProvider component from the Toolbox to your form. As a component it will sit in the tray at the bottom of the Windows Forms Designer.

The CHM help file for your project can be stored in a subdirectory and delivered with the application. To use it as application help, set the HelpNameSpace appropriately in FrmMain_Load.

Private Sub FrmMain_Load(sender As Object, e As EventArgs) Handles MyBase.Load
    '--- Set HelpNamespace to the CHM help file located in the /hlp subdirectory
    HelpProvider1.HelpNamespace = Replace(Application.StartupPath.ToString, "\bin", "") & "\hlp\CHM-example.chm"
    HelpProvider1.SetShowHelp(Me, True)
    ...

To display the CHM file with opened Contents tab

Add the following code to the handle of the menu item:

Private Sub MnuHelpContents_Click(sender As Object, e As EventArgs) Handles MnuHelpContents.Click
    '--- Show the contents of the help file.
    Help.ShowHelp(Me, HelpProvider1.HelpNamespace)
End Sub

To display the CHM file with opened Index tab

Add the following code to the handle of the menu item:

Private Sub MnuHelpIndex_Click(sender As Object, e As EventArgs) Handles MnuHelpIndex.Click
    '--- Show index of the help file.
    Help.ShowHelpIndex(Me, HelpProvider1.HelpNamespace)
End Sub

To display the CHM file with opened Search tab

Add the following code to the handle of the menu item:

Private Sub MnuHelpSearch_Click(sender As Object, e As EventArgs) Handles MnuHelpSearch.Click
    '--- Show the search tab of the help file.
    Help.ShowHelp(Me, HelpProvider1.HelpNamespace, HelpNavigator.Find, "Basic")
End Sub

Calling by ContextID

Add the following code to the handle of the menu item:

Private Sub ShowHelpTopicIDToolStripMenuItem_Click(sender As Object, e As EventArgs) Handles ShowHelpTopicIDToolStripMenuItem.Click
    '--- old workaround through Ken COX [MVP] was: &HF = 15 = HH_HELP_CONTEXT
    '--- This works only with Option Strict OFF !!
    '    Dim iContextID As Integer
    '    iContextID = 10010
    '    Help.ShowHelp(Me, Me.hlpProvider1.HelpNamespace, &HF, iContextID)
    '--- fixed in .NET 2.0 by new member HelpNavigator.TopicId
    Dim iContextID As String
    iContextID = "10010"
    '--- Show CHM contents tab and a special topic by TopicID -----
    Help.ShowHelp(Me, HelpProvider1.HelpNamespace, HelpNavigator.TopicId, iContextID)
End Sub

---