All my managed COM Add-ins solutions extensively use Windows forms. With .NET it’s very easy to create help that are directly associated with Windows forms which I hope this blogpost also will show.
For all my solutions I use complete helpfiles (.chm) created and compiled with RoboHelp which is also used here. A compiled helpfile consists of several HTML files and the common term for these files is “topics”. Usually I place the helpfiles in the same directory as the solutions are placed in.
Basically Form-based help means that a specific topic is associated with a specific Windows form.
The following screenshot is from RoboHelp and shows the list of topics for a help project. For the case here I will be using the topic “Move Database” (its filename is Move_database.htm).
In order to add Form-based help we need to add an instance of the HelpProvider to the Windows form. Like the ErrorProvider and other providers the HelpProvider is added to the Windows form’s component tray as the following screenshot shows:
When adding the component to the Windows forms five new properties are added to the form’s properties:
- Help button:
True if we want to add a help button to the Windows form’s caption bar to the right.
- HelpKeyword on HelpProvider:
Determines the Help keyword associated to the form or to the control. Here we refer to the topic filename as the below screenshot shows.
- HelpNavigator on HelpProvider:
Determines the kind of Help associated with the form or the control. Here we set it to Topic.
- HelpString on HelpProvider:
Determines the Help string associated with the form or the control. Here we leave it empty.
- ShowHelp on HelpProvider:
Determines if help is available or not for the form or for the control. This property should always be set to True.
The following screenshot shows the first four properties’s settings:
When the Windows form has been loaded and has the focus the HelpProvider component starts to monitor the Windows form. When the end users press the F1 key the named topic is loaded in its own window.
In the property window for the HelpProvider we also need to add the filename to the HelpNamespace:
What should be notable is the following:
- No code is used to get the above solution.
- In .NET we can refer to topics and are not forced to use TopicIDs.
- No code or any settings are used to hook the help to the F1 key.
It can be discussed whether the use of F1 key is the best approach or not. A help button can be a better solution under some other conditions.
- For Windows forms that have multiply purposes the Form-based help approach should be replaced with a Control-based approach.
To see the final result of the above please see helpaction.png