The usage of the Microsoft® HTML Help in the Visual Basic 5.0 applications.

Report to the DevCon98

Yuri Volkov. Software developer. Moscow.
Email: programmer@iname.com

Section: developing tools. Report level: 3 - specific technology

In the report the experience on the commercial application development was presented. As a help-system the Microsoft® HTML Help was used. The results are presented as demonstratiuon of the working application. (As an example the application from the previous report "The usage of the DirectX with Visual Basic 5.0" was presented).

The access to the HTML Help executable was made on the base of the API. The third side components were not used

The usage of the HTML Help gave possibility to create the reference documentation forms in the hyper text format, to generate content and alphabetical index and to obtain the search capabilities for full text of the help documents. All files where compiled to one with .chm extention.

1. What is the HTML Help?

The Microsoft® HTML Help is the set of the tools that are used to create the full featured help system in the HTML format. These tools make possible to group help documents and to perform the search in the Internet

HTML Help is the suuccessor of the WinHelp. The calls to the HTML Help from the applications (API) and the base tool for the development (HTML Help Workshop) is similar to that for the WinHelp. There are an utility for the converting WinHelp projects to the HTML Help.

It is very convinient that the help documents can be published in the Internet too. The compiling of the project creates the one .chm file, but this file can be converted to the set of the HTML files. Some functions, as search, for example, are working for the single compliled .chm file only.

The access th HYML Help is possible through the Internet. However, in the case of the compiled file it should be downloaded as a whole before the use of the first page.

According to Microsoftr idea the HTML Help does not require the browser, but by the 1998 May the distribution pack for the HTML Help without browser was under development. See http://www.microsoft.com/workshop/author/htmlhelp/.

The examples of the HTML Help usage are the Internet Explorer 4.0 and it's components. Look for the files with .chm extension.

One of the examples of the creating the content for the document see at the proccedimgs of the previous conference (DevCon97)

2. HTML Help Components

• HTML Help Workshop - the development tool and image editor (Authoring Guide included).
• HTML Help ActiveX Control (or HTML Help Java Applet) - should be put to the HTML-page to enable the additional features such as content list, index, pop-up windows, etc..
• The compiled HTML (.chm) - contains all the help documents. This packed file is very convinient for the distribution.
• Executable program hh.exe presents the compiled HTML as sequence of the pages with appropriate search and navigation interface.

3. The Internet resiurces

• HTML Help Workshop can be free downloaded from http://www.microsoft.com/workshop/author/htmlhelp/. The supplementary documentation includes the description of the HTML Help, API, HTML Help WorkShop and HTML. It's hard enough to start: there are no any project examples.
• After registering in the MSDN Online you can download eAuthor Help from HyperAct (http://premium.microsoft.com/msdn/downloads/eAuthor/default.htm). eAuthor Help - it is a RAD tool for the HTML Help. In the distribution the OCX for the Visual Basic is supplied too.
• Blue Sky Software proposes the RoboHTML (http://www.blue-sky.com/Products/robohtml.htm) for the 3--day trial. They proposes the on-line bool "Mastering Microsoft HTML Help Book": (http://www.blue-sky.com/regforms/bookreg.htm) that contains the description of the nice features of the RoboHTML and variety of the useful information on the HTML Help itself.

4. HTML Help Workshop

• This tool is not convinient for the fast development as the third side products. But it is open and do not tie the writer to the possibilities of the specific tool.
• I have used the HTML Help Workshop and ordinary HTML-editors.
• There were some bugs and application fails during automated compiling of the Table Of Content. However the TOC should be changed by hand and this is working nicely.
• The images directly referenced from the HTML are included during compiling automatically. The additional files (*.js and *.css ) ahould be added manually to the [FILES] section.

5. The context help call from VB

The context help can be called by the use of one HTML Help API fucntion:

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

In the simple case to call the page by the name only can use the commands:

Const HH_DISPLAY_TOPIC As Long = 0
Dim Hwnd As Long
Hwnd = HtmlHelp( MyForm.hwnd, 
                 "TkmW.chm", 
                 HH_DISPLAY_TOPIC, "Welcome.htm")

To find the context help by the HelpContextID attribute of the currently active control you can use the following lines (the one piece of the code for all program required). This code is called after pressing of the F1-key:

Const HH_HELP_CONTEXT As Long = &HF
Dim frm1 As Form     ' active form
Dim ctl1 As Control	  ' active control
Dim lngContextID As Long
Dim mhWnd As Long
  On Error Resume Next
  Set frm1 = Screen.ActiveForm
  If Err = 0 Then
    Set ctl1 = frm1.ActiveControl
    If Err <> 0 Then Set ctl1 = Nothing
    If Not (ctl1 Is Nothing) Then
      lngContextID = ctl1.HelpContextID
    End If
    If lngContextID = 0 Then
      ' If there are no identifier for the context help for the control
      ' use the context help for the form
      lngContextID = frm1.HelpContextID
    End If
    mhWnd = HtmlHelp(frm1.hwnd, "TkmW.chm", HH_HELP_CONTEXT, lngContextID)
  End If

6. The general system for the context identifiers

The identifiers of the context are in the 3 places in the project of VB and HTML Help. Start their names with IDH_. To simplify the future changes it is convinient to create 3 files:

1. HelpMap.bas - contains the constant definitions and should be included to the VB-project(TkmW.vbp, for example). The example of the file content:

  Attribute VB_Name = "HelpMap"
  Global Const IDH_About = 10
  Global Const IDH_Plasma = 4
  Global Const IDH_PlasmaEdit = IDH_Plasma
  Global Const IDH_Welcome = 11

2. HelpMap.h - the same definitions for the C-project. This file is to include to the [MAP] section of the HTML Help project( TkmW.hhp ):

  [MAP]
  #include HelpMap.h

The content of the HelpMap.h:

  #define IDH_About 10
  #define IDH_Plasma 4
  #define IDH_PlasmaEdit 4
  #define IDH_Welcome 11

3. HelpAlias.h - connects the conterxt identifiers and the file names of the HTML pages. This file is included to the [ALIAS] section of the HTML Help project( TkmW.hhp ):

  [ALIAS]
  #include HelpAlias.h

The HelpAlias.h content:

  IDH_About = About.htm
  IDH_Plasma = Plasma.htm
  IDH_PlasmaEdit = Plasma.htm
  IDH_Welcome = Welcome.htm

HTML Help Workshop gives possibility to find some errors in the HelpMap.h and HelpAlias.h. The support of the compliance between HelpMap.bas and HelpMap.h is the author responcibility. The utility for the automated converting of the first to second may be of help.

7. Demonstration, discussion