Delphi and Microsoft HTML Help

By: Vino Rodrigues

Abstract: A paper that will guide you in creating HTML Help files and use them in your Delphi applications.

Delphi and Microsoft HTML Help

A white paper and tutorial by Vino Rodrigues
vinorodrigues@yahoo.com
www.geocities.com/vinorodrigues

What will be covered in this paper:

Microsoft HTML Help

Microsoft® HTML Help is the standard help system for the Windows 98 and 2000 platforms. Authors can use HTML Help to create online help for a software application or to create content for a multimedia title or Web site. Developers can use the HTML Help API to program a host application or hook up context-sensitive help to an application. As an information delivery system, HTML Help is suited for a wide range of applications, including training guides, interactive books, and electronic newsletters, as well as help for software applications.

HTML Help offers some distinct advantages over standard HTML, such as the ability to implement a combined table of contents and index and the use of keywords for advanced hyperlinking capability. The HTML Help compiler (part of the HTML Help Workshop) makes it possible to compress HTML, graphic, and other files into a relatively small compiled help (.chm) file, which can then be distributed with a software application, or downloaded from the Web.

HTML Help consists of the following components:

  • The HTML Help ActiveX® control, which provides navigation features, such as table of contents, index, related topics links, and initial splash window for Web sites and the HTML Help Viewer.

  • The layout engine, such as Microsoft Internet Explorer version 3.0 or later or any browser that supports ActiveX controls.

  • The HTML Help Viewer, which help authors can use to display compiled HTML in a customized, resizable window, independent of the user's browser.

  • Compressed HTML, which combines all sources (HTML, ActiveX controls, ActiveX Scripting, Java applets, graphics, full-text search indexes, keywords, and more) and compresses them into a single file.

  • Microsoft HTML Help Workshop, which contains a help compiler, WinHelp converter, and all the other tools necessary for creating and maintaining an HTML Help project.

  • Pop-up windows, which enable help authors to create small windows for definitions or glossary terms that appear on top of a topic window.

Microsoft HTML Help is available and free to download from: http://msdn.microsoft.com/workshop/author/htmlhelp/

Delphi and HTML Help

Delphi does not include an implementation of HTML Help, but one can easily be created. The process involves creating some API that call the HTMLHelp API and trapping Delphi application events to trigger the HTML Help system.

You can get the complete 'htmlhelp.h' object pascal translation form the web, but for this example will only use the following API:

const
  HH_DISPLAY_TOPIC        = $0000;
  HH_DISPLAY_TOC          = $0001;
  HH_CLOSE_ALL            = $0012;

function HtmlHelp(hwndCaller: HWND;
  pszFile: PChar; uCommand: UINT;
  dwData: DWORD): HWND; stdcall;
  external 'HHCTRL.OCX' name 'HtmlHelpA';

We will discuss trapping help events in the example.

Creating Help Projects

NOTE: You will need 'Microsoft HTML Help Workshop' to complete this paper and it is available and free to download from: http://msdn.microsoft.com/workshop/author/htmlhelp/

An HTML help project (.hhp) file is a text file that brings together all the elements of a help project. It contains the data HTML Help Workshop needs to combine topic (.html, .htm), image (.jpeg, .gif, .png), index (.hhk), and contents (.hhc) files into a single compiled help (.chm) file.

The project file also contains information about how a compiled help file will appear. Window definitions you create in the project file determine attributes of your help windows, such as size and position.

As a help author, you create the project file and add to it the locations of your topic, contents, index, and other files. You can modify the project file options and customize your help windows to match the design of your system. You can make other changes depending on the size and complexity of your help system.

When you create a new project, contents, or index file, the minimum necessary settings are added automatically. The project file is divided into sections; for example, [FILES] and [OPTIONS] are included in every help project file. You can edit these sections by double-clicking the section title.

Once your project file is complete, you compile it to create the final help file. Then you test the help file to make sure everything appears the way you want it.

How to create HTML help

The Microsoft HTML Help workshop comes with extensive documentation we do not want to reproduce here. (-- Yea! Right!)

You will need to start up the HTML Help Workshop.

Create a new help project file

  1. On the File menu, click New, and then click Project.

  2. Follow the instructions in the New Project Wizard.

Note: You can also convert an existing help project into an HTML Help project.

Add file locations to a project file

The most important information that you provide in a project file is the location of your HTML topic, contents (.hhc), and index (.hhk) files. This enables HTML Help Workshop to find all the information it needs to compile a help file.

To add or remove HTML topic files from a project file

  1. Open a project (.hhp) file, and then click Add/Remove Topic Files.

  2. In the Topic files box, click Add or Remove.

Note: When using HTML Help Workshop, the number of topic files you can view and add is limited to 5,000. Projects with more than 5,000 files will compile correctly, and links from entries in the index and contents files will work, but you will need to use a text editor to view, add, or edit them.

To specify the location of contents files

  1. Open a project (.hhp) file, and then click Change Project Options.

  2. Click the Files tab, and then in the Contents file box, enter the name and location of your contents (.hhc) file.

Note: If you want a contents file created for you, select the Automatically create contents file (.hhc) when compiling check box, and then in the Maximum heading level box, select the heading level at which you want contents entries to be created.

Note: You can also specify how the contents entries you create will respond when you single-click or double-click them in HTML Help Workshop.

To specify the location of index files

  1. Open a project (.hhp) file, and then click Change Project Options.

  2. Click the Files tab, and then in the Index file box, enter the location and name of your index (.hhk) file.

Note: You can also specify how the index entries you create will respond when you single-click or double-click them in HTML Help Workshop.

To specify the location of image or multimedia files

  1. Open an HTML file and add the <IMG> tag where appropriate.

If you are compiling your files, the HTML Help compiler will automatically add any referenced files to your project at compile time.

Note: The HTML Help Image Editor, a graphic editing tool that comes with HTML Help Workshop, makes it easy to take screen shots and add them to your help files.

Creating help projects: A Tutorial

The following text will teach you the process of creating a help file project from scratch:

Creating the help file

  1. Start up the HTML Help Workshop

  2. Create a new project file as:
    C:whateverpathtestprj.hhp (don't include any existing file...)

  3. With an HTML or text editor create the file C:whateverpathdefault.htm
    <HTML>
    <HEAD>
      <TITLE>Welcome</TITLE>
    </HEAD>
    
    <BODY>
    
    <H1>Hello World</H1>
    
    This will be your default page.
    
    </BODY>
    </HTML>
    

  4. Add this file to your project by pressing on the 'Add/Remove topic files' button:

    (Afterward you should see the file listed in the '[Files]' group.)

  5. Now lets add a Table of Contents by clicking on the 'Contents' tab. A dialog will appear informing us that the Table of Contents is not specified, and lets us create one:

  6. We can now add a link into our default file (also known as the Home file). Press the 'Insert a heading' button:

    Name the Entry title as "Sample Help" and then press the 'Add' button and select the 'Welcome' page (default.htm). Then the 'OK' button.

    Note: We can add more files to the Contents (by inserting headings or pages). The files can be accessed in an hierarchy fashion (by using the 'Move selection up | down | left | right' buttons.
    Remember that the help file is a virtual web-site and that the files are most likely structured in a flat fashion - but that does not stop you from creating a complex tree contents, which is just links to the HTML files.

  7. Now we want to change the topic's icon. Press the 'Edit selection' button:

    Once the 'Table of Contents Entry' dialog appears select the 'Advanced' tab and change the 'Image index' to "1". Press 'OK'.

  8. We are ready to compile the help project - but first we need to set some project properties, and this is done by pressing the 'Change project options' button (in the 'Project' tab):

    • In the 'General' tab set the 'Title' to: "Sample Help"

    • In the 'Files' tab set the 'Compiled file' to: "c:temptestprj.chm" - we don't what the compiled files in same directory as the source, now do we?

    • Press the 'OK' button.

  9. Compile the project by pressing the 'Save all files and compile' button:

  10. You can test the created HTMLHelp (.chm) file by double-clicking on it from the Windows Explorer.

Calling the help file from Delphi

  1. Create a new application and add the HTML Help API listed in the beginning of this paper to the main form.

  2. Set the Application.HelpFile to the .chm file you just created.

  3. Create a new public function (let's call it 'HH'):

    function TForm1.HH(Command: Word; Data: Integer;
      var CallHelp: Boolean): Boolean;
    begin
      if (Command = 0) and (Data = 0) then
          HtmlHelp(Application.Handle,
            PChar(Application.HelpFile),
            HH_DISPLAY_TOC, 0);
    
      CallHelp := False;
    end;
    

    Note: CallHelp must be set to FALSE to prevent Delphi from calling WinHelp.

  4. On the Form.OnCreate event add the following code: ¹

    Application.OnHelp := HH;

    ¹ This step can be replaced by a TApplicationEvents object, and trapping it's 'OnHelp' event handler.

  5. On the buttons OnClick event add the follwing code:

    HH(0, 0, dummy);

  6. Run the application and press the button to show the Table of Contents with the default help page.

The HelpContext property

This is a tricky one. The easiest way to implement a HelpContext (which in Delphi is an Integer) is to name the HTML files by HelpContext value:

i.e. If the HelpContext was 100 then the help HTML file would be named '100.htm'.

In the following example we formated the HTML file in the following fashion:

Hnnnnn.htm

(Where nnnnn is the zero padded HelpContext value.)

To access the a HelpContext specific file simply add the following code to the custom OnHelp event:

if (Command = 1) then
    HtmlHelp(Application.Handle,
      PChar(Format('%s::/H%5.5d.htm',
        [Application.HelpFile, Data])),
      HH_DISPLAY_TOPIC, 0);

Note: The Command value of "1" depicts that the F1 key was pressed.

Closing the help window

HTML help provides a simple function to close all windows opened directly or indirectly by the calling program:

HtmlHelp(0, nil, HH_CLOSE_ALL, 0);

*

Download some source code for this paper:
These files include:

  • htmlhlp.pas - A pascal translation of the 'htmlhelp.h' header file (with dynamic dll loading).
  • htmlhlpviewer.pas - A Delphi 6 'Help Manager' plug-in help viewer for HTML Help files.

Server Response from: ETNASC04