Indigoware White Paper

How to Add Context-Sensitive Help to Visual C# .NET Windows Applications

Why add context-sensitive Help? Adding context-sensitive Help can greatly improve the usability of your Microsoft Visual C# .NET Windows based applications by making it easier for users to teach themselves how to use the application. The benefits are twofold; users gain additional benefits by using more features of the application and support costs are reduced. If the development team or technical authors have gone to the trouble of writing a comprehensive Help file, then it makes sense to make the small extra effort required to make the information it contains as easy for the user to access as possible. By using Indigowares Help Publisher for Visual Studio in conjunction with Microsoft Visual C# .NET, providing context-sensitive Help can be a straightforward task. How users can access context-sensitive Help There are four main methods for users to access context-sensitive Help: Through a Help button on a Windows Form. This is the most intuitive method from the users point of view as it does not require any prior knowledge. By adding a menu item or toolbar button. By pressing the F1 key (F1 Help). It is a convention in Windows applications that the F1 key should bring up Help for the user. However while you should observe this convention, not all users are aware of this facility. Whats This Help displayed through the ? button on the Windows Forms title bar. The user clicks this button and the cursor then changes to a question mark. If the user then clicks on one of the forms controls, a popup window is displayed explaining the use of that control. Example application A zipped archive containing a simple Microsoft Visual C# .NET Windows application is available from http://indigoware.com/developers which demonstrates all the techniques described in this paper. It was produced using Visual Studio .NET 2003 together with Help Publisher for Visual Studio 2003.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 1 of 12

C# Context-Sensitive Help

.NET Framework support for context-sensitive Help There are two specialized classes provided by the .NET Framework, both in the System.Windows.Forms namespace, aimed at adding context-sensitive Help to a Windows application, the Help and HelpProvider classes. They both use the HelpNavigator enumeration to specify the method of selecting the Help topic or navigation pane to display in the HTML Help viewer. HelpNavigator enumeration The possible values of the HelpNavigator enumeration are described in the following table: HelpNavigator TableOfContents Index Find KeywordIndex AssociateIndex Topic Purpose Displays Contents navigation pane. Displays Index navigation pane. Displays Search navigation pane. Displays Help topic based on Index keyword. Displays Help topic based on Association keyword. Displays Help topic based on filename. Displays Help topic based on Help Context ID. Help.ShowHelp param argument None. None. String containing . String containing the Index keyword. ASCII String containing the Association keyword. String containing the filename of the Help topic, e.g. topic.htm String containing numerical value of the Help Context ID, e.g. 1001

TopicId (.NET Framework 2.0 Beta only)

The Help class The System.Windows.Forms.Help class has three static methods, ShowHelp, ShowHelpIndex and ShowPopup. It is used to display Help topics either as a page of a compiled HTML Help file displayed in the HTML Help viewer, as a popup window or as a web page displayed in a web browser. Help.ShowHelp method The Help.ShowHelp method displays a Help topic in either the HTML Help viewer or a web browser. In its full form it takes four parameters as described below. Various overloaded versions are also provided so that not all of the parameters need to be supplied.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 2 of 12

C# Context-Sensitive Help

Parameter Type parent Control

url

String

command param

HelpNavigator Object

Purpose Specifies the control that will be the parent window of the HTML Help viewer or web browser displaying the Help topic. Specifies either the URL of a web page or the location and filename of a compiled Help file (.chm file). Defines how the Help topic is to be selected, see table above. Specifies the Help topic to be displayed, see table above.

On the surface the Help.ShowHelp method seems to provide all the functionality a developer could need to display Help topics. However there are a number of problems with its implementation: Calling with HelpNavigator.AssociateIndex does not work as there is a bug in the implementation that passes the Association keyword as a Unicode string where the HTML Help viewer API expects an ANSII string. The example application includes a helper routine, ToAsciiString, which can be used to workaround this bug. The .NET Framework 1.x surprisingly does not include any support for Help Context IDs, even though they are the main method of providing context-sensitive Help in Visual Basic and Visual C++ applications. Fortunately a workaround exists for .NET Framework 1.x and Help Context ID support is being added in .NET Framework 2.0. What are Help Context IDs? Help Context IDs are integer values that link a user interface element (such as a control, Windows Form, or menu) to a related topic in a Help file. Although it is possible to assign a Help Context ID for every control on a Windows Form, it is usually only necessary to assign them at Windows Form level and have a single Help topic describing all the controls on the Windows Form. Mapping Help topics to Help Context IDs The mapping between Help Context IDs and Help file topic pages is defined in the .HHP Help project file which is used by the Help compiler. You can create and edit .HHP files using HTML Help Workshop, however if you use Help Publisher for Visual Studio, as described later in this paper, it will take care of creating the .HHP file automatically.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 3 of 12

C# Context-Sensitive Help

Using Help.ShowHelp with Help Context IDs Although no HelpNavigator value exists for using Help Context IDs in .NET Framework 1.x, a little exploring of how Help.ShowHelp is implemented uncovered an undocumented way of adding Help Context ID support. If you pass 15 as the HelpNavigator value and pass the Help Context ID as an int in the param argument, Help.ShowHelp will display a Help topic based on the Help Context ID. The value 15 works as it is equal to the HH_HELP_CONTEXT command in the HTML Help viewer API. The even better news is that the Beta release of .NET Framework 2.0, as used in Visual Studio 2005, includes an extra value for the HelpNavigator enumeration, TopicId, which does support Help Context IDs. The following helper routine, included in the example application, can be used to encapsulate both .NET Framework 1.x and 2.0 support therefore making future migration easier.
private void ShowHelpTopicId(int TopicId) { #if VS2005 // Only works with .NET Framework 2.0 Help.ShowHelp(this, HelpFile, HelpNavigator.TopicId, TopicId.ToString()); #else // Only works with .NET Framework 1.x Help.ShowHelp(this, HelpFile, (HelpNavigator)15, TopicId); #endif }

Using Help.ShowHelp with a web browser An alternative to using a compiled Help file is to display HTML pages containing the Help topics in a web browser. To display a web-based Help topic simply call ShowHelp with the parent control as the first argument and the URL of the Help topic HTML page as the second argument. Help.ShowIndex method This method displays the Index navigation pane of the Help file in the HTML Help viewer and is simply equivalent to Help.Show(parent, url, HelpNavigator.Index). Help.ShowPopup method This method displays a Whats This Help style pop-up message. It takes three arguments; the control that will be the parent window of the displayed message, the message string and the position on the screen to display the message.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 4 of 12

C# Context-Sensitive Help

The HelpProvider class The second class in the System.Windows.Forms namespace of interest is the HelpProvider component. It can be added to a Windows Form by dragging it from the Toolbox to a Windows Forms component tray. It is designed to add content-sensitive Help at an individual control level, both by pressing the F1 key and by clicking on the ? button on the Windows Forms title bar. The following table describes HelpProviders properties: Property HelpNamespace Type String Level Per a HelpProvider component. Per a control. Purpose Specifies location and filename of the compiled Help file (.chm file) or an HTML page. Used for F1 Help and defines how the Help topic is to be selected in the same way as with Help.ShowHelp. Used for F1 Help and maps onto the Help.ShowHelp param argument (see table above). Contains the Whats This Help pop-up window message string. True if context-sensitive Help is supported on the control.

HelpNavigator

HelpNavigator

HelpKeyword

String

Per a control.

HelpString

String

Per a control. Per a control.

ShowHelp

bool

Although the HelpProvider component shows much promise, it is however best to avoid with its current implementation for the following reasons: No Help Context ID support is provided and the workaround described for Help.ShowHelp cannot be used with HelpProvider. It inherits the Association keyword bug from Help.ShowHelp. It does not work with HTML Help topic files at control level. If used to provide only Whats This Help, it will also insist on displaying a Help pop-up window whenever the F1 key is pressed. This pop-up window will have the message text for the active control, but positioned wherever the cursor happens to be, which can be confusing for the user.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 5 of 12

C# Context-Sensitive Help As neither Help Context IDs or Association keywords can be used with HelpProvider the only remaining methods to specify a Help topic are: An Index keyword, but more than one Help topic is frequently linked to the same Index keyword, so this approach is not recommended. The Help topics filename. However using Help topic filenames creates a far too close relationship between the Help files physical layout and the application for many developers. Note also that if you use the HelpString property to provide Whats This Help then you must also set the HelpNavigator and HelpKeyword properties as well in order to avoid the misplaced pop-up window problem mentioned above. A better approach than using the HelpProvider component is to handle the Windows Forms HelpRequested event directly which can be very straightforward as described below. Handling the HelpRequested event When the user either presses the F1 key or clicks the ? button on the Windows Forms title bar, the .NET Framework raises the HelpRequested event on the active control. If a control has no event handler for this event it passes it to its container control (and so to the Windows Form on which the control is located). The following short routine, included in the example application, shows how to implement a HelpRequested event handler at Windows Form level to provide both F1 and Whats This Help:
private void OnHelpRequested(object sender, HelpEventArgs hlpevent) { if(Control.MouseButtons != 0) // Show What's This Help { // Get the control where the user clicked Control ctl = this.GetChildAtPoint( this.PointToClient(hlpevent.MousePos)); // Get the tooltip associated with the control string toolTip = this.toolTip1.GetToolTip(ctl); // Show as a Help pop-up if (toolTip != "") Help.ShowPopup(ctl, toolTip, hlpevent.MousePos); } else // Show F1 Help using ShowHelpTopicId helper routine ShowHelpTopicId((int)HelpTopicIds.IDH_DEFAULT); // Set flag to show that the Help event as been handled hlpevent.Handled = true; }

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 6 of 12

C# Context-Sensitive Help

Implementing Whats This Help The HelpRequested event handler described above uses the ToolTip component to store the pop-up window message text displayed for each control. With Visual Basic and Visual C++ it was common to store these message texts in the compiled Help file itself. However with .NET applications a better approach is to use a component such as the ToolTip component (or HelpProvider, but see above) for the following reasons: .NETs excellent localization facilities can then be used. Help.ShowPopup does not support message texts embedded in the Help file. Whats This Help message texts can if desired also be used as tool tips. In fact some developers might dispense with the ? button entirely and just use tool tips instead. Another approach is to use the ? button to display a relevant Help topic instead of a pop-up message (which would still be available as a tool tip). The example application can easily be modified to take this approach by: Setting the Active property of the ToolTip component to True. Removing the Whats This Help branch of the if statement in the HelpRequested event handler. Adding the ? button to a Windows Form The following Windows Form properties have to be set in order for the Whats This Help button to be displayed on a Windows Forms title bar: MinimizeBox = False MaximizeBox = False HelpButton = True Using ErrorProvider An additional method of providing context-sensitive Help to the user is the ErrorProvider component. It can display a warning icon with an error message tool tip next to a control when the value entered in the control is invalid. For further details see the example application and Visual Studio .NETs Help file. Note on MS Help 2.0 format Help files Microsofts original intention was to introduce a new Help file format, MS Help 2.0, along with the .NET Framework. However it subsequently backtracked and HTML Help 1.x remains the current Help file standard for Windows applications. The MS Help 2.0 format is used however for Help files displayed within Visual Studio .NET and are shown using the Visual Studio .NET extensibility API (not covered in this paper).

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 7 of 12

C# Context-Sensitive Help

Using Help Publisher for Visual Studio with Microsoft Visual C# .NET Although it is possible to produce a Help file just by using Visual Studio .NET and HTML Help Workshop, the task is a lot easier using Indigowares Help Publisher for Visual Studio. You can use Help Publisher to manage the contents and index and add navigation buttons. Help Publisher can manage the mapping between topic pages and Help Context IDs. By using Help Publisher for Visual Studio it is therefore unnecessary to edit the HHP file directly or use the often buggy and complicated HTML Help Workshop interface. For larger Help files it is recommended to use Microsoft FrontPage in conjunction with Indigowares Help Publisher for FrontPage to update the Help file, as described in the section below. Creating and editing the Help file with Help Publisher for Visual Studio To add a Help Publisher for Visual Studio project to your solution open Visual Studio .NETs New Project dialog and select New HTML Help 1.x (.chm) File in the Help Publisher Projects list of project types. Make sure that the Add to Solution option is selected if shown.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 8 of 12

C# Context-Sensitive Help If you are not familiar with how to use Indigowares Help Publisher for Visual Studio to update topic files and create an Index or Contents, take the Help Publisher Tutorial by selecting Run the Help Publisher Tutorial from the list of Help Publisher project types. Alternatively if you have an existing Help file you can import it into Help Publisher for Visual Studio using the Import wizard. See Help Publishers own Help file for further information. Assigning Help Context IDs to Help topic pages You can use the Help Context IDs view of the Context IDs Editor to assign Help Context IDs to Help topic pages. To open the Context IDs Editor click on the icon on the Solution Explorer toolbar or select Context IDs Editor from the Projects menu. Once the Context IDs Editor is open, simply select New ID from the Context IDs menu and enter the name of the new Help Context ID, which can be either a number or the name of a constant. Once added it can be associated with a Help topic by clicking on the Topic Title or Location fields and selecting the desired Help topic.

Alternatively Help Context IDs can be set through a Help topic pages properties sheet. Simply enter the name of the Help Context ID in the Help Context IDs property field. To ease the task of integrating the Help file with the application, Help Publisher for Visual Studio can generate an exported C# .NET file containing all the Help Context IDs assigned in the Help file.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 9 of 12

C# Context-Sensitive Help

To enable this option: 1. Open the Context IDs Editor by clicking the icon on the Solution Explorer toolbar or selecting 'Context IDs Editor' from the Project menu. 2. Select the 'Export File' view. icon or pressing 3. Open the Properties window by pressing clicking the F4. 4. Check that the 'Programming Language' field is set to 'Visual C# .NET'. 5. In the 'Generated Filename' field, enter the desired filename for the exported C# .NET file. 6. Rebuild the Help Publisher project and the export file will be generated. 7. Add the generated C# .NET file in your C# .NET project.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 10 of 12

C# Context-Sensitive Help In the example application four Help Context IDs are defined. Two have numerical names making constant name to numerical value mapping unnecessary, leaving two Help Context IDs which are the ones defined in the Export file. Editing the Help File in Help Publisher for FrontPage As a Help file grows larger the HTML editing facilities of Visual Studio can become restrictive when creating and updating Help topics. However included in the Help Publisher Developer Edition is the FrontPage version of Help Publisher. In addition to the facilities available in the Visual Studio 2003 version you will be able to: Use FrontPages HTML editor to write the Help topics rather than Visual Studio .NETs own very basic HTML editor. Use all of FrontPages additional functionality such as link and spell checking, scripting and multimedia support. If you are using FrontPage 2003 you can use Dynamic Web Templates making it easy to give your topic pages a consistent look and feel. You can add See Also menus and other HTML Help ActiveX controls. All project settings are shared between the Visual Studio and FrontPage versions, so changing a setting in one application immediately updates that setting in the other. To launch FrontPage and edit the Help file click the button on the Solution Explorer toolbar or select Edit with Microsoft FrontPage from the Project menu. Note that Microsoft FrontPage version 2000, 2002 or 2003 must be installed on the same PC as Visual Studio for this option to be available. Conclusion Microsoft Visual C# .NET and the .NET Framework provide most of the basic functionality necessary to support context-sensitive Help. However a small amount of additional coding is required, as described in this paper, if the information contained in the Help file is to be made available to the user in the most accessible form. The combination of using Indigowares Help Publisher for Visual Studio with Microsoft Visual C# .NET can make the task of producing professional Help files that support context-sensitive Help much easier. If you are not already familiar with how to use Help Publisher for Visual Studio to edit the Help files contents and index, or how to add See Also menus, now is a good time to take the tutorial supplied with Help Publisher for Visual Studio. Free Trial For a free trial version of Help Publisher for Visual Studio visit: http://indigoware.com/download.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 11 of 12

C# Context-Sensitive Help

Microsoft, Visual C# .NET, Visual Studio .NET, Visual Basic, Visual C++ and FrontPage are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

V2.0

Copyright 2004-2005 Indigoware Ltd

Page 12 of 12