How to Implement Context-Sensitive Help in .NET Applications Created with C#, VB.NET, etc.

The Microsoft.NET (dot net) framework uses HTML Help files (chm files) for context-sensitive help. You can easily create help files in HTML Help format with HelpScribble and connect it to your WinForms .NET application. It doesn't matter whether it is written in Visual Basic, C# (C sharp) or any other .NET language, or whether you use Microsoft's Visual Studio VS.NET or another IDE such as Borland C#Builder or Delphi 2005.

How To Connect Your CHM Help Files to Your .NET Applications

To connect a help file to a form, drop a HelpProvider component on the form and set its HelpNamespace property to the full path to the .chm file. If the .chm file is in the same folder as the .exe file of your application, you can specify the .chm filename only (e.g.: helpfile.chm).

Adding the HelpProvider component to the form will make new properties available for each control on the form. Associate help topics with the controls as follows:

1. Set the ShowHelp property of the control to True
2. Set the HelpNavigator property to "Topic"
3. Set the HelpKeyword property to "html\hs1234.htm" where 1234 is the Topic ID of the topic in HelpScribble.
4. Make sure the HelpString property is blank.

The value you assign to HelpKeyword is actually the file name or URL of the topic file inside the compiled .chm file. In HTML Help files created with HelpScribble, the file name of the topic with ID 1234 is "html\hs1234.htm". If you changed the context string of the topic in HelpScribble using Topic|Properties, you need to use "html\contextstring.htm" instead. HelpScribble bases the file name of each topic on the context string.

When the user presses F1, your application will show the help topic associated with the control that has keyboard focus. When the user clicks on the question mark button on the caption bar of the window, and then on a control, help for that control is displayed. If a control does not have ShowHelp set to True, the help topic associated with the control's parent control is used instead. If none of the parent controls have a help topic specified, the help topic associated with the form itself is displayed. If the form does not have help either, nothing will happen. No error message will be displayed.

To make the question mark button appear on the caption bar of your form, set the form's HelpButton property to True, and set both MaximizeBox and MinimizeBox to False.

To programmatically display help, you can use the static method ShowHelp() of the Help class.

To show the table of contents, call: Help.ShowHelp(this, "helpfile.chm");

To show the topic with Topic ID 1234, call: Help.ShowHelp(this, "helpfile.chm", HelpNavigator.Topic, "html\hs1234.htm"); If you changed the context string, use "html\contextstring.htm" instead.

You can download a small utility that will read a .hsc HelpScribble project file, and generate a list of the proper URLs to use for the HelpKeyword property. The list includes the Topic ID and the Topic Title for reference. You, or the developers integrating your help file into their application, can use this list for easy reference.

The download includes both the C# source code as well as the compiled .exe. The .exe requires the Microsoft .NET framework to run. If you don't have it installed on your computer, the .exe will terminate with an error: "The application failed to initialize properly." Only the framework is required. The application does not need the .NET SDK, Visual Studio, or even HelpScribble.

Allowing The User to Switch Back to Your Application

Due to a design limitation of the HelpProvider component in .NET, if you call Help.ShowHelp() with "this" as the first parameter, the help file may be displayed in a modal window. The user then won't be able to switch back and forth between your application and your help file.

To work around this limitation, create a dummy form and pass that as the owner form to Help.ShowHelp().

Form form = new Form();
Help.ShowHelp(form, ...);

You Need HelpScribble to Provide Context-Sensitive Help with Your Applications