How to build Help into a WPF Program

Over the last couple of days, I have spend an inordinate amount of time trying to figure out how to integrate on-line help into my WPF programs. I am amazed at how difficult it was to find concise and useful information on this subject. In fact, it makes me think that I must be missing something major. Also, it seems that none of my programming books do a very good job covering the subject.

In fact, creating the Help File and Linking to it are two separate topics and will be dealt with separately.

Lest there be any doubt, we are limiting ourselves to creating “CHM” help files.

Using HTML Help Workshop

This is a free download from Microsoft and it is pretty basic. It starts with HTML files into which you can put links to other HTML files. You add these HTML files to a Table of Contents as “Topics”. You can also insert Headings and Files. My theory is that a Heading is just like a Topic, except that it does not NEED to have an HTML file associated with it.

The biggest draw-back to this program is that it does not allow interactive editing of HTML files. Also, it was far from intuitive to use. I found an excellent Help Workstation Tutorial by Char James-Tanny. I downloaded it from http://frogleg.mvps.org/helptechnologies/htmlhelp/hhtutorials.html.

BUT – there is something better out there for preparation of CHM files.

Using HelpNDoc to create Help Files

A search for Free Help Authoring Tools brought me to http://www.helpndoc.com/ from whence I was able to download HelpNDoc which is free for non-commercial use.

This program is very cool and I think it could be just the thing I need for documenting programs. The reason that it would be better than MS Word or something like that is that it allows me to work in outlines and it allows me to enter hyperlinks. It would be really nice if allowed me to follow them while I was authoring something, but you can’t have everything.

It comes with a pretty good on-Line help system of its own and is pretty easy to use.

Another nice thing about it is that it outputs in any or all of four different formats: CHM, HTML, DPF and Word.

And if you look in the CHM folder, it seems that it puts out all the files that would be used by HTML Help Workshop. According to one source, HTML Help Workshop must be installed for HelpNDoc to compile its help projects.

It was not clear that it allows you to create indexes, but if this is important, one might be able to do this using HTML Help Workshop as a post-processing step. Experimentation would be useful here.

Linking to help from WPF Programs

As nice as these free programs are, neither explains how to link a WPF application to the help.

The Char James-Tanny tutorial does discuss linking using the hhctrl.ocx control from VB 5/6 and perhaps it would be possible to adapt those instructions.

Apparently, there is a System.Windows.Forms.HelpProvider control. This appears to not work with WPF controls.

I did, however, find a way to open CHM help files.

But first, a little about the structure of HelpNDoc.

HelpNDoc builds a help system out of Topics. Each Topic is one entry in the table of contents, and when as the help system is being built, it creates an HTML file on the topic. This HTML file gets compressed and included in the CHM file, but a copy of the HTML file is left in the CHM directory.

This topic gets a name or Help ID based on the Topic Name in the Table of Contents. You can change this Help ID by right clicking the TOC entry. This Help ID plus “.html” is used as the name of the HTML file for this topic.

You can also add Anchor points to a Topic. You can set an anchor by placing the cursor where you want the anchor, going to the Insert tab and clicking Insert/Remove Anchor on the right side of the ribbon. The program then prompts you to enter the name of the anchor. You can see a green bar where the anchor is placed, but unfortunately, I did not find a way to go back later and see what the name had been set to. I was able to see it after generating the help file by looking at the source code in the resulting HTML file.

So, now we have a generated CHM help file, HTML files holding topics that have been compiled into this help file and possibly anchors in some of the Topic/ HTML files. How do we access them.

The answer is to use the static ShowHelp method of System.Windows.Forms.Help. Here is what the calls will look like. Assume that the help file is named MyHelp.chm. Assume that the Help ID is MyTopic and that the topic file in that help file is therefore named MyTopic.html. Also, there is an anchor point in this file named MyAnchor. You might want to use a full path instead of just a filename.

To open the help file at the beginning, use:

Help.ShowHelp(null, @"MyHelp.chm");

The following will open the help file at the MyTopic page:

Help.ShowHelp(null, @" MyHelp.chm", "MyTopic.html");

And the following will open the help file at the anchor point:

Help.ShowHelp(null, @"MyHelp.chm", "MyTopic.html#MyAnchor");

So, that is enough to get me started. As I learn more, perhaps I will update this note.