hh_doc.txt

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

================================================================================
  Title:       "HTML Help Kit for Delphi"
  Description: Add Html Help support to Delphi
  Platform:    Delphi 2, 3, 4, 5, 6 ...
  Version:     1.6

  Email:       [e-mail]
  Web:         http://www.helpware.net
  Copyright (c) 1999-2000 The Helpware Group

  Changes:
    22-Feb-1999 1.0 Original version
    23-Feb-1999     Now official - The kit is freeware (see bottom of this file)
    31-Mar-1999 1.1 Now get HHCtrl.OCX path from registry instead of winsys dir.
    04-Feb-1999 1.2 hh.pas - Now uses LoadLibrary so we can silently detect if hhtrcl.ocx is installed.
    09-Jun-1999 HH.PAS 1.3
                    - Follows Borland coding guidelines more closely - but no support for C++ Builder.
                    - GetPathToHHCtrlOCX() now uses registry.OpenKeyReadOnly() for safe NT support.
                      ** Thanks Heedong Lim <[e-mail]>
                    - tagHH_GLOBAL_PROPERTY = record now padded for correct 8 byte alignment.
                      ** Thanks "Marcel van Brakel" <[e-mail]>
                HH_FUNCS.PAS 1.3
                    - Now handles early IE three number version numbers correctly
                      Was returning x.x.0.x instead of x.x.x.0
                      ** Thanks "Silterra, Enrico" <[e-mail]>
                    - Add IE5.0 & IE5.0a version numbers to GetIEFriendlyVer()
                    - DebugOut() is only called now with _DebugMode flag.
    02-JUL-1999 HH_FUNCS.PAS 1.4
                    - HH.EXE 1.1b onwards supports help context command line param.
                      "HH.EXE -mapid ID chm". Code no longer reports error.
                      Removed error HH_ERR_UnsupportedCall = 4;
                    - Function IsDirWritable() added
                      Make debug file to winDir if drive if not writable. EG exe on CDROM.
                    - Fixed some compile errors with D3
                HH.PAS 1.4
                    - Slight changes to some structures. Most data structures have been tested.
    18-APR-2000 HH_FUNCS.PAS 1.5
                    - Now supports Delphi 2 compiler (was D3 an greater)
                    - The Hook "Application.OnHelp" object now has some callbacks so
                      you can easily override the default actions. It also now supports
                      "Whats this" field based help.
                    - Added function HHCloseAll(). It simply calls the API with command HH_CLOSE_ALL
                HH.PAS 1.5
                    - Now supports Delphi 2 compiler (was D3 an greater)
                    - Remove references to WIN32 conditional define as not applicable
    22-DEC-2001 HH_FUNCS.PAS 1.6
                    - New Func to detect Windows media Player Installations.
                    - New version numbers added for IE and HH version funcs
                    - After call to HHCloseAll() call Sleep(0). Helps fix a bug in HH 1.x
                HH.PAS 1.6
                    - Better support for Delphi 2 & 3. No longer makes a Read/Write call
                      into the registry to the the hhctrl.ocx path. Was causing access
                      violations on non-admin NT systems. 


================================================================================

CONTENTS
  1. WHAT IS IT
  2. UNIT HH.PAS
  3. UNIT HH_FUNCS.PAS
     3.1 GLOBALS VARS AND CONSTANTS
     3.2 MAKING DELPHI USE HTML HELP
     3.3 HTML HELP FUNCTIONS
     3.4 DEBUGING FUNCTIONS
  4. LEGAL INFO


================================================================================
1. WHAT IS IT
================================================================================
   This Kit contains two Delphi Units to give you access to
   the HTML Help API via Delphi 3 or 4.

   o HH.PAS       ........ Constants and interface to MS Html Help API.
                           translation from "htmlhelp.h".

   o HH_FUNCS.PAS ........ Library of HTML Help related functions.

                           o Hook "Application.OnHelp" so that all Delphi
                             Help call are directed to access HTML Help.
                           o Functions to parse HTML help paths.
                           o Functions to check component versions.
                           o Functions to open help via Windows "HH.EXE"
                             and KeyWorks program "KEYHH.EXE".


================================================================================
2. UNIT HH.PAS
================================================================================
   Like WinHelp there is one function provided by the HTML Help API
   that allows you to open help files, show help pages, show popups
   and so on.

   For help in using this function download Html Help Workshop,
   open the online help and search for "API reference".

     OR

   Download just the API.CHM from the MS web site

   http://msdn.microsoft.com/library/tools/htmlhelp/wkshp/download_main.htm

      ---------------------------------------------------------

      function HtmlHelp( hwndCaller: HWND;
                         pszFile: PChar;
                         uCommand: UInt;
                         dwData: DWORD): HWND;

      ---------------------------------------------------------

      EG. To open a CHM file

          HtmlHelp(GetDesktopWindow, "Help.chm", HH_DISPLAY_TOPIC, 0);

      EG. To open a CHM file at a particular Topic

          HtmlHelp(GetDesktopWindow, "Help.chm::/Intro.htm", HH_DISPLAY_TOPIC, 0);

      EG. To open a CHM file at a particular Topic and use a Window definition
          called "Mainwin".

          HtmlHelp(GetDesktopWindow, "c:\Help.chm::/Intro.htm>Mainwin", HH_DISPLAY_TOPIC, 0);

      EG. To open a CHM file using context help = 1001


          HtmlHelp(GetDesktopWindow, "c:\Help.chm", HH_HELP_CONTEXT, 1001);


      Note: Most people tend to use 0 instead of GetDesktopWindow. 


   **** Warning Warning Will Robinson ****

      If you call the HH API directly from your application, that is not though
      a second helper program like HH.EXE or KEYHH.EXE, you MUST close any open help
      windows before shutting down the application or you will probably crash Windows.

      The call to close all windows is simply:

         HH.HtmlHelp(0, nil, HH_CLOSE_ALL, 0);
      

================================================================================
3. UNIT HH_FUNCS.PAS
================================================================================
   Optional Unit provides a library of handy functions to help you
   access HTML Help from Delphi 3, 4 and 5 applications.


3.1 GLOBAL VARS AND CONSTANTS
================================================================================

   At the heart of HH is the activeX control "HHCTRL.OCX".
   At the heart of IE is the activeX control "SHDOCVW.dll".
   We can get lots of useful information from these two DLLs.
   These variables are initialized at program startup.

   VAR
     _hhInstalled: Boolean;           Set TRUE if HTML Help is installed
     _hhVerStr: String;               eg. '4.73.8252.1' or '' if not found
     _hhMajVer: word;                 eg. 4
     _hhMinVer: word;                 eg. 73
     _hhBuildNo: word;                eg. 8252
     _hhSubBuildNo: word;             eg. 1
     _hhFriendlyVerStr: String;       eg. '1.2'
     _ieInstalled: Boolean;           Set TRUE if Internet Explorer Installed
     _ieVerStr: String;               eg. '5.00.0910.1309'
     _ieFriendlyVerStr: String;       eg. 'Internet Explorer 4.01'


   Sometimes you need to use a special CHM path prefix.
   1. When opening a CHM file using "HH.EXE" command line.
      (prefix not required in later version of HTML Help)
   2. When opening a CHM file from web page link or in Internet Explorer.

   In these cases you need to prefix the CHM path with either:

   CONST
     HH_PREFIX_IE4 = 'ms-its:';             //IE4 and above compatible command line prefix
     HH_PREFIX_IE3 = 'mk:@MSITStore:';      //IE3 and above compatible command line prefix

   EG. ms-its:c:\Help.chm::/Intro.htm
   EG. mk:@MSITStore:c:\Help.chm::/Intro.htm

   Note: 'ms-its:' can be shorted to just 'its:'. IE4/5 understands this. 


3.2 MAKING DELPHI USE HTML HELP
================================================================================
   Class "THookHelpSystem" can be used to redirect all Delphi Help calls
   to HTML Help calls.

   TO INSTALL:

     // 1. Use the unit and declare a global
     USES HH, HH_FUNCS;
     var mHHelp: THookHelpSystem;

     // 2. Create the Object in main form create.
     procedure TMainForm.FormCreate(Sender: TObject);
     begin
       mHHelp := THookHelpSystem.Create(pathToCHM, '', htHHAPI);
       ...

     // 3. Free the object in main form destroy
     procedure TMainForm.FormDestroy(Sender: TObject);
     begin
       //Unhook and free
       mHHelp.Free;
       HHCloseAll;     //Close help before shutdown or big trouble
       ...

     Thats all there is to it. Delphi will now direct all its help
     calls to the specified CHM help file instead of the WinHelp system.
     You simply continue to use the "HelpContext" properties and commands
     like you always have.

     EG. Set Form.HelpContext=1001. Press F1 will open the CHM using context 1001.
     EG. Set Control.HelpContext=1002. Press F1 will open the CHM using context 1002.
     EG. Application.HelpContext(1003) will open the CHM using context 1003.


   CALLBACKS (new for V1.5):

     Normally the hook class simply receives the WinHelp help messages and executes a 
     standard HTML Help context call. Two callbacks are available so you can overwrite  
     the WinHelp Help_Context and Help_ContextPopup messages with your own functions.

     In the real world example that follows, we have intercepted both types of WinHelp 
     messages so that we can look up the topic path in an ini file using the HelpId.

     Note:  Help_ContextPopup messages (with the controls X,Y position) only appear 
        if you set the the forms BorderIcons property to include biHelp. Alternatively
        in the FormCreate() -- Self.BorderIcons := Self.BorderIcons + [biHelp];