Hooking up help to a WinForm Form

In order to hook Help to a WinForm application, you typically use a HelpProvider control from the Windows Form Control Toolbox. This control gets dropped onto the form and shows in the Component Tray of the form. This HelpProvider component is an Extender Property that adds extended Help related properties to each of the controls and the form itself.

Note:
Help Builder ships with a customized HelpProvider control you can optionally use. This custom control extends the standard HelpProvider with the ability to optionally pop up Help Builder at runtime in a context sensitive manner to allow editing of topic content. This is great to allow your technical writers to document the app while running it.

The first step to hooking up a custom help file is to add a HelpProvider object to a Windows Form and set its HelpNameSpace property to the name of the help file.

Note the Help Provider component in the Component tray. By default VS.Net tries to add an absolute path which you should immediately change to a relative path based on the application directory. I typically drop my help file into the application directory, so the path will be only the filename.

By adding a HelpProvider onto a form each control on the form and the form itself receive new Extender properties that relate to activating Help.

The key properties are the HelpNavigator property which should always be set to Topic if you want to link to a specific Help topic, and the HelpKeyword which requires the internal filename of the Help Topic to display. The filename maps to Help Builder's Topic PK, which is shown as a Topic Filename on the Related Topics tab of the Help Builder Edit form. You can double click on the filename and it copies the filename to the clipboard for easy pasting. You will also need to make sure that the ShowHelp property is set, but this property is set automatically once you assign a HelpKeyword value.

If you use Visual Studio .Net you can enable the Help Builder Add-In and right click on a selected control on a WinForm that has a Help Provider, which can automate this updating process by pulling the topic ID directly out of Help Builder into the current control's HelpKeyword property.

Help Activation Hierarchy

Help in your applications is activated via F1 when a HelpProvider exists on a form. If no controls or the form are hooked up the default display shows which typically will be Index page of the Help File. Help Display is controlled by a simple hierarchy flowing from the lowest level container/control back up to the form based on which control has focus. If a Control has focus and its Help Properties are set, these override any settings that might be set on the Form or another container (like a TabPage). If the currently selected control does not have any Help Settings then the HelpProvider walks up the hierarchy until it finds a container that does. So, if you only set Help properties on the Form itself, all controls that might have focus will show that Help topic unless they explicitly override with their own Help Settings.