<Help>VB 6.0</Help>

This column appeared in the May 1999 edition of EXE. It discusses the new HTML Help format that Microsoft are encouraging developers to adopt.

---

Writing help files for applications can be a rather fiddly affair if you choose to use the standard Microsoft Help Workshop in preference to one of the third–party tools. The original help compiler was written to understand RTF (Rich Text Format) files so the authoring process can mean writing your help file source in Microsoft Word, adding a curious combination of footnote characters, and then saving the file in RTF format in order to achieve the desired result. As a natural successor to this technology Microsoft have developed a new help system that is centred around the HTML format, which of course means that you can use your favourite HTML editor and save the result in native format. This month’s column complements the feature by Dave Jewell in the October 1998 edition of EXE ("Help me in HTML") in which he reviewed the relative merits of three third–party HTML Help development tools. However I’m discussing the creation of HTML–based help files via the Microsoft HTML Help Authoring Kit that ships along with Visual Studio, and which is also available for free from the Microsoft web site.

At first glance it’s not immediately obvious that Visual Basic 6.0 directly supports HTML–based help files. In order to associate a help file with a project it is necessary to select the Project Properties dialog and then raise the Browse dialog next to the Help File Name field. The resulting common dialog displays by default a file type of "WinHelp Files (*.hlp)". However, opening the file type drop down list box now also displays "HtmlHelp Files (*.chm)". Once a suitable file has been identified then associating the HelpContextID value with each form in a project works in exactly the same way.

In order to install the HTML Help Workshop from the Visual Studio disks you will need to run the installation program from the HtmlHelp directory on disk 1. Since this is theoretically quite an important part of the overall development studio it is curious that it isn’t included in the main Visual Studio setup program. The kit supplied on the CD is version 1.1, but the Microsoft web site now offers version 1.2 for free download. Sadly this newer version doesn’t seem any more robust than its predecessor; while it is quite usable it does have a tendency to forget to repaint parts of its main form from time–to–time. Also, most of the dialogs have "What’s This?" help buttons but very few controls actually have an associated help topic. Oh, and it crashed on me the other day after I’d typed in – and before I’d saved – a whole load of entries into the Table of Contents definition area. Having said all this it is stable enough to develop with, and any prolonged use will soon condition you as to where the specific foibles are so you’ll quickly find yourself working around them as a matter of course. Sad, but true.

Creating a help file

In order to create a new HTML–based help project a rudimentary wizard will ask you a few basic questions before providing you with an empty project file. As with any system you really need to plan your layout before you start authoring. The simplest way to get results is to have one HTML file for each topic. These files can be created in any HTML editor in the same way that you would create a web page. Authors of the old style help files will be pleased to realise that you can just insert image files directly onto the design page so there’s no more messing about with {bmc} macros.

As you create each HTML file you need to introduce it into the [FILES] section of the project. In the Workshop environment make sure the Project tab is selected and press the Add/Remove topic files button. This will display a standard File Open dialog which allows you to build up the list of files quite quickly, particularly because it allows you to select multiple files in one go. A couple of other tabs allow you to create a Table of Contents page and an Index page.

In order to make the help topics available for API calls you need to provide a bit of lookup information, entered into the project file manually or included as C–style header (.h) files. One file should provide a list that maps the symbolic ID of a help topic to a topic id, for which I’ve shown an example in Listing 1.

#define IDH_Home 2000
#define IDH_Topic1 2001
#define IDH_Topic2 2002

Listing 1: Mapping a reference to an ordinal number

A second file provides an alias lookup for each of these symbolic IDs to the actual source files that they represent, this being illustrated in Listing 2.

IDH_Home=Home page.htm
IDH_Topic1=Topic 1.htm
IDH_Topic2=Topic 2.htm

Listing 2: Mapping the reference to the source file

Note the use of the IDH_ prefix in front of the symbolic IDs. If this prefix is used then the workshop will perform a cross–reference check between the topic IDs in the compiled help file with those mapped to numeric values in the project file, and will warn you of any inconsistencies found.

As an aside, one useful feature that the Workshop does provide is a Decompile feature. This allows you to convert an existing CHM file back into it’s constituent components so you can grab your favourite resources from other help files and use them in your own…no, forget I said that!

Programmatic access

The software developer gains direct programmatic access into the HtmlHelp system through the HHCTRL.OCX file. From this file name one would expect to set a reference to it through the Components dialog under the Project menu. Not so! The file should be treated as a standard DLL, for which you make a function declaration as follows:

Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As HH_COMMAND, dwData As Any) As Long

where

1. hwndCaller is the handle of the calling window, or Null
   
   
2. pszFile is the .CHM file to call upon
   
   
3. uCommand is the action to perform (N.B. HH_COMMAND is an enumerated type list that provides the added benefit of allowing the Visual Basic editor to display a popup list of possible values as you type the function)
   
   
4. dwData is additional data, the nature of which depends upon the value of uCommand

In order to invoke a help file with the context of a Table of Contents view you would make a call as follows:

Const HH_DISPLAY_TOC = &H1
Const lReply AS Long

LReply = HtmlHelp(Me.hWnd, App.HelpFile, HH_DISPLAY_TOC, ByVal 0&)

These direct calls are only required for menu or command button invocations, otherwise you can just set the HelpContextID value for each form to match the value of the topic id declared for each help file. It feels a little strange having such a new technology as this being presented to the Visual Basic developer as a DLL–style call, but of course this will change. Version 2 of HTML Help will be COM–based.

Context–sensitive help

What’s This? functionality is a very useful form of help, but sadly tends to get missed out of many developments, particularly those performed in–house (as opposed to commercially available products which seem to fare a little better). To create a set of text pop–ups you need to add the values to a separate text file and then add it into the help project. The format of the entries for this text file is

.topic topic_id
topic_text

as illustrated in Listing 3.

.topic 4000
Applies changes to database

.topic 4001
Cancels changes

Listing 3: Providing the text for "What's This?" help

This file should then be added into the help file project definition via the Text Pop–ups tab of the HtmlHelp API information dialog. To then tie this in to a Visual Basic form you need to set both the KeyPreview and WhatsThisHelp property values to True, and then set an appropriate WhatsThisHelpID value for each control. Setting the WhatsThisButton value to True then displays the What’s This? question mark button on the form caption bar, but only if you’ve set the border style as either Fixed Single or Fixed Dialog.

There are a couple of issues to be aware of when you are programming for a What’s This? implementation. The first is that a form with the WhatsThisHelp property set to True will also take F1 key presses as invocations of the same kind of help. This means that if you want the user to also have access to the full help file then you need to find another way to offer it other than the F1 key. I would suggest that in this case either menu access or a dedicated Help command button would be the most appropriate. The second issue is that you need to provide slightly different definitions of the application help file depending upon whether you are providing What’s This? help or normal, F1–style help. To define the help file for the normal F1 kind of help the definition is along the lines of

App.HelpFile = "Example.chm"

However, to define the help file for use with a What’s This? implementation you also need to specify the source file that contains the What’s This? source text, such as

App.HelpFile = "Example.chm::/popup.txt"

If you attempt to leave this second format in place while attempting the normal F1 help then the help file will open but an error message is displayed. Alternatively, trying to activate What’s This? help with the help file set in the first format will merely display a message box that states "Cannot open the file Example.chm". Therefore if you are designing an application that will need to have a mix of the two different kinds of help then I would suggest that you include the relevant App.HelpFile declaration within the Form_Activate method of each form.

Microsoft Book

Just to finish up I thought I’d mention that Microsoft Press publishes a book called The Official Microsoft HTML Help Authoring Kit. The content is well presented and would certainly be of use to folk who need to write HTML-based help files that go beyond the basics. Somebody with previous experience of the Help Workshop would probably pick up the mechanics of the new HTML Help Workshop fairly quickly and so would be unlikely to need it for basic help files. However it does show you what else can be achieved, such as using the "Training Card" mode which allows for a greater amount of interaction between an application and the help file. The author takes care to present sample code for both the Visual C++ and the Visual Basic camps, but there is no getting away from the fact that the HTML Help programming interface is really written with the C++ programmer in mind. One word of warning about this book, the Visual Basic content relates to version 5 which didn’t natively support HTML Help. Therefore there is a discussion concerning the implementation of What’s This? help through window subclassing which is now obsolete. At the time of writing I could find no indication of any planned updates to this book. This aside, I would still recommend it to anybody who intends to get serious about HTML Help file development. For that matter though, I would also seriously recommend that such a person take a good look at the products reviewed by Dave Jewell a few months back.