All projects you created over the years had time planned to create documentation and probably help files. How many projects are now completed without proper documentation and help files? Please don’t lie to me!
In this column, I’ll show you how to link your VB.Net Windows application to a help file. Before getting to it, I’ll show you, and that’s where all the books and articles normally fall short, how to create these simple help files (that may explain why many programmers never tried to create help files!).
What you need?
You will first need a HTML editor. Microsoft FrontPage works just fine. If you don’t have it, you can use MS Word (be sure to save your document as a Web Page), or Cute HTML, or Visual Studio .Net IDE, or even Notepad if you are a HTML pro. The editor will be used to create each page of your help file.
You will also need a help compiler. I will use a free tool that you probably already have installed on your PC or that can be downloaded for free. This tool is the Microsoft HTML Help Workshop. To download the latest version of the free software, visit Microsoft HTML Help downloads and download htmlhelp.exe.
Now that we are set
You now need to ask yourself the kind of help you want to give the users. Some of the ways includes (but are not limited to):
- Descriptive labels
- Messages in the status bar
- Tooltips
- What’s this help
- Help files
Each of these methods has pros and cons. You have to decide which one you need.
This column will focus only on creating help files and linking them to your VB application.
Creating the HTML files
Go ahead. Open your HTML editor and create your HTML files. You should have one topic per file. Each file should be as complete as possible (I am sure you don’t like it yourself when you have to dig 10 related-topics down to find the single information you where looking for). Be sure to create a title page or an introduction page as we will need one later.
Compiling your HTML files
It is now the time to start the HTML Help Workshop application.
You first need to create a project. From the File menu, select New. From the New dialog that will open, be sure that Project is selected and click the OK button.
A wizard will start. Because we are starting a brand new project, do not check the convert checkbox and press the Next button.
You are now required to specify a name and a path for your project file (you can click the Browse button to select the destination folder but you will need to type the name of your project). After your path and name are set, click the Next button again.
From the “New project – Existing files” step, check “HTML Files (.htm)” to be able to add the files you created previously and click the Next button.
You are now supposed to be in the “New Project – HTML files” step. Clicking the Add button will display an Open dialog box from which you can choose the HTML files you created before. When you are done, click the Next button.
Finally, you are shown the “New Project – Finish” step. Simply click the Finish button and you should now see something like the image shown in Figure 1.
Figure 1: HTML Help Workshop
Be sure that the Project tab is selected and click the “Change Project Options” button (top-left from inside the Project tab). I won’t explain each setting here. I will only tell you to give a significant name to your project (in the Title) and to set the Default file to the title page or introduction page I asked you to create when creating your HTML files. Try to guess what this page will be used for? You can now click the OK button return to the main dialog.
You are now (I should say finally!) ready to compile your first help project. You can use the “Compile HTML file” button of the toolbar or the “Compile…” item from the File menu.
From the “Create a compiled file” dialog, be sure that the “Save all files before compiling” is checked. You can click the Compile button. The compilation is now processing and a log will be displayed.
You can now view it either by using your Windows Explorer and double-clicking the .chm file that has been created or by selecting the “Compiled file…” item from the View menu (or the red glasses from the toolbar). You should now see your title/intro page (mine is shown in figure 2) and … nothing more! No Contents page. No Index page. I can ear you say: All that for this simple page? Hold on, I haven’t said all yet, I just wanted you to take a small break!
Figure 2: The introduction page
Adding a Table of Content
Still from the HTML help workshop application (with your project opened in it), click the Contents tab. A dialog will ask you to create a new contents file or to open an existing one. Be sure you select “Create a new contents file” and click the OK button. Another dialog is now showing asking you to give a filename to your table of contents. We normally accept the default value to this question (Table of Contents.hhc). Click the Save button.
You are now supposed to be in the Content tab. Notice that the vertical toolbar (at the left) just changed. Click the “Insert a heading” button from this toolbar (second button from the top). In the “Table of Contents Entry” dialog, you are now required to enter an “entry title”. I enter “UTMag demo”. This is entry is similar to a chapter. You can now click the OK button.
You now need to add pages to this section. To do so, click the “Insert a page” button (third button from the top). A question is now asking you if you want to insert this page at the beginning of the table of contents. You have to answer No in order to have the new page added to the section we just created (it would be a good idea to answer yes for the title/intro page you created). Now click the Add button and select the HTML title you want to insert into your section. Give an “Entry title” for this page and click the OK button.
You can now redo this procedure to add other pages to this section and you could also add other sections. You may have to use the arrows from the toolbar to set/change the order and hierarchy of your sections.
It is now the time to re-compile your help project (using the same technique we already used). Be sure that your compiled help file is closed before trying to re-compile otherwise you will receive the error HHC5010. If you now view your compiled help file, you will be tempted to say that you did something wrong because you were awaiting a table of contents and you see the same as you saw before! You did nothing wrong. There is one exception to the viewer. You now have a toolbar at the top (if you don’t see it, you seriously have a problem). Click the Show button from this toolbar and you’ll see it. Your table of contents can be used to navigate through your pages.
Adding an index
Get back once again to the HTML Help Workshop application to discover some more dialogs! This time we will add an index to our help project.
By clicking the Index tab, you will see the “Index not specified” dialog come up. Select the “Create a new index file” option and click the OK button. Another dialog is now asking you a filename. We normally accept the default value (Index.hhk) and click the Save button.
Once again you can see that the toolbar of this tab (shown on the left has changed).
From here you need to add all the keywords you want to appear in the index and link them to according page(s). To do it, click the “Insert a keyword” button (second button from the top). Enter the Keyword in the textbox at the top and use the Add button to link to the according pages (you may have more then one). Click the OK button.
Repeat this last step for all the keywords you want. You may be asked if you want to insert this entry at the beginning of the index. Answer whatever you like, it doesn’t matter. After you enter all your keywords, click the “Sort keywords alphabetically” button.
Compile your project again and view it. If you followed the steps correctly, you should now see an index tab with your keywords in it.
Creating a test application
It is now time link the help file with a VB.Net application. Create a simple Windows application that we will use to test the linking to our help file.
The very first thing you need to do (after you created your application) is to copy your .chm file to the bin folder.
Method 1: The Process class
The easiest way of displaying your help file is to use the Process class (see my column from December 2003 on this topic). Only this single line of code is required:
System.Diagnostics.Process.Start(Application.StartupPath & "\UTMagDemo.chm")
This is perfect to display your complete help file from a Help menu item.
Method 2: The Help class
Another very easy way of displaying your help file is to use the Help class. This class has two shared methods that you can use to open your help file showing either the table of contents or the index tab.
Here is the code you need to display the table of contents:
Help.ShowHelp(Me, Application.StartupPath & "\UTMagDemo.chm")
And here is the code to display the index:
Help.ShowHelpIndex(Me, Application.StartupPath & "\UTMagDemo.chm")
For both methods, the first argument is the parent (Me is passed as a referenced to the current form) and the second argument is the complete path to the help file.
Method 3: The HelpProvider control
The HelpProvider control is an extender control (much like the Tooltip control). Adding a HelpProvider control will add properties (HelpString, HelpKeyword, and HelpNavigator) to the form to which it is added and to all existing controls of this form. These new properties let you bind your form and controls to a help file. These properties let you create context-sensitive help.
First, add a HelpProvider control to your form. Books will normally tell you to set the HelpNameSpace property of this control directly from the properties dialog. Don’t do it. It will work perfectly on your PC but will fail (without any exceptions) on clients’ PCs. You need to set this property dynamically at runtime (because the path changes from the design time to run time) with this line of code that is best located into the Load event of the form:
HelpProvider1.HelpNamespace = Application.StartupPath & "\UTMagDemo.chm"
This line supposes that your HelpProvider control is named HelpProvider1 and that your help file is named UTMagDemo.chm and is located into the application folder. Once your help provider is set, your F1 key will not work yet! You need to bind your form/controls to your help provider.
In the properties of your form, set the HelpKeyword property to one of the keyword you have created earlier when you have created your index in your help project and set the HelpNavigator to KeywordIndex. Notice that these keywords are not case-sensitive and can contains spaces. Once these two properties are set, you can run your project. Pressing the F1 key anywhere on this form should open your form in the page you want.
This behaviour may be fine for most control on the screen. If you want to use a different page for one of the control just set the HelpKeyword and the HelpNavigator accordingly and this new page will be displayed for this particular control.
A comment about the HelpString property
This property is added when you add a HelpProvider control to your form and is used to display a string (what is typed into this property) much like a tooltip is doing but only when the user is pressing the F1 key. You have to know that this string will only appear if the HelpNameSpace property of your HelpProvider control is not set.
For more information
There are some sites over the net that gives you more details on the many ways and the many products you can used to create help files.
There is a comprehensive tutorial written by Char James-Tanny that you can download for free from www.mvps.org/htmlhelpcenter/htmlhelp/hhtutorials.html.
Also be sure to visit these other sites for other links:
Conclusion
The article is quite long but the operations are far from being complicated. There are no reasons why you shouldn’t be able to implement context-sensitive help into your next project.
I hope you appreciated the topic and see you next month.