How to: Specify a Help File for Your Component

In most situations, you should let the developers who are using your component enable the run-time Help. In some cases, however, it will make sense to allow your component to display HTML Help when called. HTML Help can be provided for components through the System.Windows.Forms.Help object. This object is a static class that encapsulates the HTML Help 1.x engine. This class cannot be instantiated, and its methods must be called directly. To display Help, invoke the Help.ShowHelp Method method. This overloaded method requires at least two arguments: the control that acts as the parent control of the Help dialog box, and the URL of the Help file. The Help file can be a compiled HTML Help 1.x file (.chm file) or an HTML file in the HTML Help format.

If you are going to incorporate support for a Help file directly in your component, you have two options for when and how to show it:

• The preferred option is to implement a Help method that can be called by the client application. The client application can pass parameters to the Help method to ensure that the correct topics are displayed, and the developer coding with your component has the option of bypassing Help altogether.

• The other option is to invoke the ShowHelp method in response to conditions as they occur in code. This approach provides you the most control over what Help is displayed when, but it severely limits future developers in the use of your component.

To specify and display a Help file for your component

1. Create and compile your .chm Help file.

2. If you do not already have a reference to the System.Windows.Forms namespace in your component, add one.

3. Create a public method to show Help. This method should provide an easy way for developers to specify what Help they need to display.

   ' This method takes parameters from the client application that allow
   ' the developer to specify when Help is displayed.
   Public Sub DisplayHelp (ByVal parent as System.Windows.Forms.Control, _
                           ByVal topic as MyHelpEnum)
      ' The file to display is chosen by the value of the topic
      ' parameter.
      Select Case topic
         Case MyHelpEnum.enumWidgets
            Windows.Forms.Help.ShowHelp(parent, "C:\Help\Widgets.chm")
         Case MyHelpEnum.enumMechanisms
            ' Insert code to implement additional functionality.
      End Select
   End Sub
   

   // This method takes parameters from the client application that allow
   // the developer to specify when Help is to be shown.
   public void MyHelp(System.Windows.Forms.Control parent, 
   myHelpEnum topic)
   {
      // The file to display is chosen by the value of the topic.
      switch (topic)
      {
         case myHelpEnum.enumWidgets:
            System.Windows.Forms.Help.ShowHelp(parent, " C:\\help\\widgets.chm ");
            break;
         case myHelpEnum.enumMechanism:
            // Insert code to implement additional functionality.
            break;
      }
   }
   

See Also

Reference

Help

Other Resources

User Assistance for Components