hh_doc.txt

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

     {All Help_Context messages will come here} 
     procedure MyHelpButtonEvent(ContextHelpID: Longint);        
     var CHMPath: String;
     begin
        // We are have a look up table (ini file) containing the HelpID to HelpTopic mapping
        CHMPath := LookUpPathFromID(ContextHelpID) ;
        HH.HtmlHelp(GetDesktopWindow, PChar(CHMPath), HH_DISPLAY_TOPIC, 0)      
     end;

     {All 'Whats This' & F1 Help_ContextPopup WinHelp events will come here}  
     procedure F1HelpEvent(ContextHelpID: Longint; X, Y: Integer);
     var ChmPath: String;
     begin
        // We are have a look up table (ini file) containing the HelpID to HelpTopic mapping
        CHMPath := LookUpPathFromID(ContextHelpID) + '>$GLOBAL_F1WIN';
        HH.HtmlHelp(GetDesktopWindow, PChar(CHMPath), HH_DISPLAY_TOPIC, 0)      
     end;

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

       {hook in our special functions}
       mHHelp.HelpCallback1 := HelpButtonEvent;
       mHHelp.HelpCallback2 := F1HelpEvent;

       {Enable Whats This help messages}
       Self.BorderIcons := Self.BorderIcons + [biHelp];
       ...


     // 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
       ... 

   MORE INFO:

      constructor Create(aDefChmFile, aDefWinDef: String; aHostType: THostType);

        o aDefChmFile - Name of CHM help file opened when F1 pressed.
        o aDefWinDef  - Set to empty string to specify the default help window.
        o aHostType   - Normally you would specify "htAPI".

        "htAPI"       - This application is hosting the help via the HH API.
        "htKeyHHexe"  - KeyWorks KeyHH.EXE is hosting the help calls.
        "htHHexe"     - Windows HH.EXE is hosting the help calls.

        The advantage of using a separate EXE to call help is...
        a) It separates help from your programs runtime memory
        b) Delphi applications have problems with hosting HTML Help in the
           situation where the online help is using a Delphi Automation Server.

           EG. We use a COM control to display videos. When the COM help shuts
           down it produces and access violations. Whether its Delphs fault or
           IEs fault its still a problem.

           If you do use ActiveX, COM, Automation libraries to extend your
           help page capabilities and you get access violations on NT or
           Win98 machines then change to using the "KeyHH.EXE" host. "HH.EXE"
           has very limited options and only HH 1.1b and above supports
           contextual help calls via the command line.

           Download "KeyHH.EXE" from "http://www.keyworks.net/"

           *** 18-Apr-2000: Delphi 5 + HH 1.3 seem OK now.

           
      Other Methods and Properties:

        function HelpTopic(aTopic: String): Integer;
        property ChmFile: String;
        property WinDef: String;
        property HostType: THostType;

        o You can change the CHM help file at any time.
          EG. mHHelp.ChmFile := 'c:\myhelp.chm';

        o You can change the CHM window definition at any time.
          EG. mHHelp.WinDef := 'Mainwin';
          EG. mHHelp.WinDef := '';           // '' for default window

        o You can change the Host application at any time. See notes above.
          EG. mHHelp.HostType = htAPI;

        o Open a help topic directly
          EG. mHHelp.HelpTopic('\options\index.htm');


     Note:

       With the new callback option in V1.5 we tend to ignore the above 
       class methods and when our callback function receives a help event
       we call the HH.htmlhelp() low level function directly. Its clearer
       code and HH.htmlhelp() also returns the handle of the HH window.

     Whats This Help

       To enable the "Whats This" Help_ContextPopup messages you must set
       Self.BorderIcons := Self.BorderIcons + [biHelp];
       Do this in the FormCreate() or Object Inspector. The Whats This 
       button in the title bar will not show if you have minimize
       or maximize buttons. But you can make a toolbar button behave like 
       a Whats This button like this..

       procedure TForm1.WhatsThisToolButtonClick(Sender: TObject);
       begin
          DefWindowProc(handle, WM_SYSCOMMAND, SC_CONTEXTHELP, 0);
       end; 
     


3.3 HTML HELP FUNCTIONS
================================================================================
   Here are some HTML Help functions. You can go fishing through
   hh_funcs.pas to discover other useful functions.


   function HHDisplayTopic(aChmFile, aTopic, aWinDef: String;
                           aHostType: THostType): Integer;

      Display a help topic from the CHM file using a specific Window Definition.

      aChmFile:  Name of compressed help file to display.
      aTopic:    Path to html file in Chm file. Leave blank for default page.
      aWinDef:   Specify a window definition. Leave blank for default Window.
                 Note: not supported by some versions of HH.EXE and KeyHH.EXE
      aHostType: Who will host the HH Window. See Notes above.
      Returns:   All OK, HH_ERR_HHNotInstalled,
                 HH_ERR_KeyHHexeNotFound (aHostType = htKeyHHexe)
                 HH_ERR_HHexeNotFound (aHostType = htHHexe)
      Example:   HHDisplayTopic('windows.chm','about_magnify.htm','windefault', htHHAPI);


   function HHTopic(aCHMPath: String; aHostType: THostType): Integer;

      Same as above except aChmFile, aTopic and aWinDef are entered
      as aChmPath EG. "aChmFile::/Topic>aWinDef"


   function HHHelpContext(aChmFile: String; aContextID: DWord;
                 aWinDef: String; aHostType: THostType): Integer;

      Displays a help topic from the CHM file based on a mapped topic ID.

      aChmFile:  Name of compressed help file to display.
      aContext:  Specifies the numeric ID of the topic to display.
      aWinDef:   Specify a window definition. Leave blank for default Window.
                 Note: not supported by some versions of HH.EXE and KeyHH.EXE
      aHostType: Who will host the HH Window. See Notes above.
      Returns:   All OK, HH_ERR_HHNotInstalled,
                 HH_ERR_KeyHHexeNotFound (aHostType = htKeyHHexe)
                 HH_ERR_HHexeNotFound (aHostType = htHHexe)
      Example:   HHHelpContext('windows.chm',200,'windefault', htHHAPI);


   function HHContext(aChmPath: String; aContextId: Integer; aHostType: THostType): Integer;

      Same as above except aChmFile and aWinDef are entered as
      aChmPath EG. "aChmFile>aWinDef".
      Note: HH.EXE host reqires a prefix EG. "mk:@MSITStore:"

   Procedure HHShowError(err: Integer);

      Call to automatically display any error message for the above functions.

      Example:
         ret := HHHelpContext('windows.chm',200,'windefault', htHHAPI);
         HHShowError(ret);  //if ret <> 0 then we see an error


3.4 DEBUGING FUNCTIONS
================================================================================
    To enable logging of debug messages to log file ".\HHdebug.txt" (you override the name)
    either set the global var _DebugMode := TRUE
    or create a file called ".\debug.debug".

    This can be very useful. If a client is reporting problems, then you can
    simply create ".\debug.debug", run the program and examine the log file.


    procedure DebugOut(msgStr: String; const Args: array of const);

       Send a string to the debug log file. Normally used with global "_DebugMode".
       Takes same parameters as Delphs FORMAT() function.
       Put lots of debug into you files. You never know when you may need it.

       Example:

         if _DebugMode then
           DebugOut('_RunDir = "%s"', [_RunDir]);

         Or call DebugOut2() which does the same code.

    procedure ShowDebugFile;

       Display the debug file using windows default text editor.

    procedure ResetDebugFile;

       Reset the log file. Log is truncated and some global vars
       are written to it.


================================================================================
4. LEGAL INFO
================================================================================

   o The Kit is Freeware.
   o You are free to rewrite it and hack it to bits.
     But please don't distribute it in a modified form.
   o You may not freely distribute the Kit without the authors consent.
     Companies and sites may however direct others to our web site.
   o This software is provided 'as is'. Although tested thoroughly we cannot
     guarantee the software is bug free. You use it at your own risk.
   o Support is available via email within reason.
     IE. Don't expect heaps for something you paid nothing for :-)

   Enjoy, and please take some time to check out the rest of our site
   at http://www.helpware.net

   [e-mail]

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

*** END OF FILE ***