Table of Contents
Implementing Context Sensitive Help
HelpStudio provides rich support for linking to the generated help system from your application or from Visual Studio and other development environments.
Supporting F1 Help from Your Application
Development Tools that use Topic Names
Recent development tools use topic file names instead of Help Context IDs to support F1 help. In that scenario you can use the help file name and the topic name, with a .html suffix, as the help target.
Adding F1 Support to a Visual Studio .NET WinForms Project
Setting up the Project
- The first step is to add a HelpProvider control to your form for design time support.
- The HelpNamespace property can be set at either design time or runtime, but must be set with the name of the CHM file generated by HelpStudio.
- If you wish to support "What's This" help, set the HelpButton property of the parent form to True.
Setting What's This Help for Controls
- Select the control you wish to have help available for. Scroll down the list of properties until you reach the Misc section. Here you find a number of new properties added by the HelpProvider control. They have the suffix "on <name>", where <name> is the name of your HelpProvider control.
-
Set the HelpKeyword property to the name of your HelpStudio topic, with a .html suffix. For example, if you had a topic named default, you would enter default.html as the property value.
-
The HelpNavigator property defines the view displayed. By default this is AssociateIndex. You must change it to use Topic instead.
-
- Repeat for any other controls you wish to display What's This help for.
- At runtime, help can be invoked by either selecting the control and pressing F1, or by clicking the help button on the window title bar and then clicking a control which has help assigned to it.
Displaying a Help Topic in Code
The shared Help class offered by the System.Windows.Forms name space allows you to display your help Topics. You can use the ShowHelp method to display a topic. The URL parameter of this method should be filled with your CHM filename, and the param parameter with the name of your topic and the .html suffix.
For example, assuming you have a HelpProvider control already initialized named ContextHelp, and you want to display a topic named default, you can call the following code:
| Visual Basic .NET |
Copy Code |
|---|---|
' display the how to topic Help.ShowHelp(Me, ContextHelp.HelpNamespace, HelpNavigator.Topic, "default.html") | |
| C# |
Copy Code |
|---|---|
// display the how to topic Help.ShowHelp(this, ContextHelp.HelpNamespace, HelpNavigator.Topic, "default.html"); | |
Development Tools that use Context IDs
If you have development environments such as unmanaged Visual C++, Visual Basic 6 and older versions of Delphi using numbers to associate elements of an application to topics in the help system, you can use tools within HelpStudio to assist with the mapping of context IDs to topics.
Depending on your development approach you might already have context IDs assigned in your application and want to map those to topics, or you might want to generate a set of context IDs from your topics so that the developers can assign those to user interface elements.
To Map Existing Context IDs to Topics
Follow this procedure to map existing context IDs that the application development team have already assigned to user interface elements.
- Open the Context ID Mapper from the Tools ribbon menu.
- If you have not already done so, you will be prompted to identify the location of the .h file containing the context IDs to map. If you don't already have this file, you need to obtain it from the development team.
- The Context ID Mapper shows a list of assigned and un-assigned context IDs.
- You can associate a Context ID with a topic using drag and drop.
To Assign Context IDs to Topics and Generate a Context ID .h File
Follow this procedure if the application development team have not already assigned help context IDs to user interface elements and wish to have you provide a .h file containing a context ID for each Topic in the project which they can then assign to user interface elements.
- Select Create Context ID Header File from the Tools ribbon menu.
- On the displayed file dialog, identify where you would like the .h file saved.
- Provide the generated .h file to the development team.
Once you have established the mapping between help context IDs in the application and the Topics in your help system, all that remains is to set the help file name in your application. You should therefore liase with your development team to agree the output .chm filename to use for the help system so that when F1 is pressed in the application it is looking for the correct .chm file name.
Supporting F1 Help from Visual Studio
Conceptual Topics
If you are producing an AddIn or Tool that integrates with Visual Studio and you want to provide links to your help system, you need to define F1 keywords. You can find more background information on Help Integration with Visual Studio in the MSDN Library.
To add an F1 keyword to a Topic:
- Open the topic for edit.
- Switch to the Index Keywords view.
- Select the New toolbar button.
- Enter the desired keyword prefixed with the ! character - this indicates a hidden F1 keyword rather than a keyword in the visible index.
Once the F1 keyword has been defined for the Topic and the generated help system is deployed, F1 requests for that keyword from your Visual Studio integrated Tool or AddIn displays the Topic against which you defined the F1 keyword.