VSTO & .NET & Excel

August 31, 2007

Providing Form-Based help for Managed COM Add-ins

Filed under: .NET & Excel, COM Add-ins, VSTO & Excel — Dennis M Wallentin @ 3:20 pm

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).

helptopics.png

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:

helpprovider.png

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:

helpsettings.png

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:

help.png

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

Kind regards,
Dennis

Advertisements

4 Comments »

  1. Thanks for this post Dennis, you make it look all so easy. 🙂

    The truth is that I find Help files to be very important, but they aren’t easy because how we execute them seems to always change depending on whether we’re using VBA, VB6, or .NET. This as a very nice walkthrough…

    And just for an opinion, is RoboHelp your first choice for Help file editors then?

    Comment by Mike Rosenblum — September 1, 2007 @ 6:11 pm

  2. Thanks for Your kind words Mike.

    In the mid of the 90’s I started out with RoboHelp and since then I use it. Unfortunately I no longer have the money to keep me up to date with the latest version.

    I know Ken (Puls) use West Wind HTML Help Builder. It would be of interest to learn what other developers actually use when it comes to help authoring tools.

    Kind regards,
    Dennis

    Comment by Dennis Wallentin — September 1, 2007 @ 10:17 pm

  3. I’ve used the bog standard MS HTML help sdk in the past in conjunction with any wysiwyg web page designer.

    The thing about help files is that they always come last then just when you have the project complete you realise how big a job it is to create one!

    Comment by Mark Rowlinson — September 2, 2007 @ 8:27 pm

  4. Mark,

    Agreed – Creating help files does challenge us. Not only for the time it take but also that we need to actually evaluate the logic in our solutions.

    Perhaps SDK & HTML tools is a common solution among developers?

    Kind regards,
    Dennis

    Comment by Dennis Wallentin — September 2, 2007 @ 11:49 pm


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: