Using the HelpBuilderHelpProvider

The Help Builder HelpProvider component replaces the existing Windows Forms HelpProvider component. You can either drop the HelpBuilderHelpProvider on a form instead of a HelpProvider component, or you can replace existing references in your source code.

To drop a new HelpBuilderHelpProvider on a form:

• Select the Windows Form Control Toolbox or other tab.
  
• Click Add Component and select the HelpBuilderHelpProvider.dll assembly
  
• Once installed, drag and drop the HelpBuilderHelpProvider component onto any form
  
• Set the HelpNameSpace property to your CHM file (no path or app relative path)
  

The VS.Net designer generates all the necessary initialization code for you. If you're not using VS.NET or a visual environment you can use code like this:

// Object reference declaration
private Westwind.Windows.Controls.HelpBuilderHelpProvider oHelp;

// Initialization
this.oHelp = new Westwind.Windows.Controls.HelpBuilderHelpProvider();

// Required property settings
this.oHelp.HelpNamespace = "webmonitor.chm";
this.oHelp.ParentForm = this;  // this is required! 

// Hooking up Controls for Help support (standard Help Provider behavior)
this.oHelp.SetHelpKeyword(this.txtUrl, "_1a8114npo.htm");
this.oHelp.SetHelpNavigator(this.txtUrl, System.Windows.Forms.HelpNavigator.Topic);
this.oHelp.SetHelpString(this.txtUrl, "");

To update an existing HelpProvider object to use HelpBuilderHelpProvider:

• Go into the source file for the form
  
• Do a Serach and Replace for System.Windows.Forms.HelpProvider with Westwind.Windows.Controls.HelpBuilderHelpProvider
  
• Bring up the form in design mode and Save.
  

This last step makes sure that the designer refreshes the new provider and updates the Form reference for the ParentForm property.

Globally enabling or disabling the Help Builder Pop up in your application

By default the HelpBuilderHelpProvider is enabled once dropped onto a form. However, operation of the provider can be globally controlled by setting the static EnableHelpBuilderHelpProvider property. You can manually set this property in the class or in your application startup code:

using Westwind.Windows.Controls;
...
HelpBuilderHelpProvider.EnableHelpBuilderHelpProvider = true;
HelpBuilderHelpProvider.HotkeyKey = Keys.F3;
HelpBuilderHelpProvider.HotkeyModifier = Keys.Control;

By default this flag is set to true which means Help Builder will try to pop up on the special hotkey.

When this flag is set to false, the event hooks are simply ignored and the HelpBuilderHelpProvider acts like a standard HelpProvider object. This makes it easy to enable or disable Help Builder activation from your application.

For best results you probably want to use a configuration flag that determines whether this functionality is enabled or not and set it once at application startup. For example your startup code might look like this:

[STAThread]
static void Main() 
{
	WebStoreConfig Config = new WebStoreConfig();
	Config.GetSettingsFromConfig();

	// *** Enable or disable Help Builder Editing at runtime
	HelpBuilderProvider.EnableHelpBuilderHelpProvider = Config.EnableHelpBuilderEditing;
	HelpBuilderHelpProvider.HotkeyKey = Keys.F1;
	HelpBuilderHelpProvider.HotkeyModifier = Keys.Control;

	Application.Run(new Form1());
}