home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 December / Chip_2000-12_cd1.bin / zkuste / Delphi / unity / d2345 / htmlhelp / hh_doc.txt < prev    next >
Encoding:
Text File  |  2000-08-29  |  19.0 KB  |  466 lines
  1. ================================================================================
  2.   Title:       "HTML Help Kit for Delphi"
  3.   Description: Add Html Help support to Delphi
  4.   Platform:    Delphi 2, 3, 4, 5 ...
  5.   Version:     1.5
  6.  
  7.   Email:       support@helpware.net
  8.   Web:         http://www.helpware.net
  9.   Copyright (c) 1999-2000 The Helpware Group
  10.  
  11.   Changes:
  12.     22-Feb-1999 1.0 Original version
  13.     23-Feb-1999     Now official - The kit is freeware (see bottom of this file)
  14.     31-Mar-1999 1.1 Now get HHCtrl.OCX path from registry instead of winsys dir.
  15.     04-Feb-1999 1.2 hh.pas - Now uses LoadLibrary so we can silently detect if hhtrcl.ocx is installed.
  16.     09-Jun-1999 HH.PAS 1.3
  17.                     - Follows Borland coding guidelines more closely - but no support for C++ Builder.
  18.                     - GetPathToHHCtrlOCX() now uses registry.OpenKeyReadOnly() for safe NT support.
  19.                       ** Thanks Heedong Lim <hdlim@dcenlp.chungbuk.ac.kr>
  20.                     - tagHH_GLOBAL_PROPERTY = record now padded for correct 8 byte alignment.
  21.                       ** Thanks "Marcel van Brakel" <brakelm@bart.nl>
  22.                 HH_FUNCS.PAS 1.3
  23.                     - Now handles early IE three number version numbers correctly
  24.                       Was returning x.x.0.x instead of x.x.x.0
  25.                       ** Thanks "Silterra, Enrico" <enrico.silterra@nortel.com>
  26.                     - Add IE5.0 & IE5.0a version numbers to GetIEFriendlyVer()
  27.                     - DebugOut() is only called now with _DebugMode flag.
  28.     02-JUL-1999 HH_FUNCS.PAS 1.4
  29.                     - HH.EXE 1.1b onwards supports help context command line param.
  30.                       "HH.EXE -mapid ID chm". Code no longer reports error.
  31.                       Removed error HH_ERR_UnsupportedCall = 4;
  32.                     - Function IsDirWritable() added
  33.                       Make debug file to winDir if drive if not writable. EG exe on CDROM.
  34.                     - Fixed some compile errors with D3
  35.                 HH.PAS 1.4
  36.                     - Slight changes to some structures. Most data structures have been tested.
  37.     18-APR-2000 HH_FUNCS.PAS 1.5
  38.                     - Now supports Delphi 2 compiler (was D3 an greater)
  39.                     - The Hook "Application.OnHelp" object now has some callbacks so 
  40.                       you can easily override the default actions. It also now supports 
  41.                       "Whats this" field based help.
  42.                     - Added function HHCloseAll(). It simply calls the API with command HH_CLOSE_ALL 
  43.                 HH.PAS 1.5
  44.                     - Now supports Delphi 2 compiler (was D3 an greater)
  45.                     - Remove references to WIN32 conditional define as not applicable
  46.  
  47. ================================================================================
  48.  
  49. CONTENTS
  50.   1. WHAT IS IT
  51.   2. UNIT HH.PAS
  52.   3. UNIT HH_FUNCS.PAS
  53.      3.1 GLOBALS VARS AND CONSTANTS
  54.      3.2 MAKING DELPHI USE HTML HELP
  55.      3.3 HTML HELP FUNCTIONS
  56.      3.4 DEBUGING FUNCTIONS
  57.   4. LEGAL INFO
  58.  
  59.  
  60. ================================================================================
  61. 1. WHAT IS IT
  62. ================================================================================
  63.    This Kit contains two Delphi Units to give you access to
  64.    the HTML Help API via Delphi 3 or 4.
  65.  
  66.    o HH.PAS       ........ Constants and interface to MS Html Help API.
  67.                            translation from "htmlhelp.h".
  68.  
  69.    o HH_FUNCS.PAS ........ Library of HTML Help related functions.
  70.  
  71.                            o Hook "Application.OnHelp" so that all Delphi
  72.                              Help call are directed to access HTML Help.
  73.                            o Functions to parse HTML help paths.
  74.                            o Functions to check component versions.
  75.                            o Functions to open help via Windows "HH.EXE"
  76.                              and KeyWorks program "KEYHH.EXE".
  77.  
  78.  
  79. ================================================================================
  80. 2. UNIT HH.PAS
  81. ================================================================================
  82.    Like WinHelp there is one function provided by the HTML Help API
  83.    that allows you to open help files, show help pages, show popups
  84.    and so on.
  85.  
  86.    For help in using this function download Html Help Workshop,
  87.    open the online help and search for "API reference".
  88.  
  89.      OR
  90.  
  91.    Download just the API.CHM from the MS web site
  92.  
  93.    http://msdn.microsoft.com/library/tools/htmlhelp/wkshp/download_main.htm
  94.  
  95.       ---------------------------------------------------------
  96.  
  97.       function HtmlHelp( hwndCaller: HWND;
  98.                          pszFile: PChar;
  99.                          uCommand: UInt;
  100.                          dwData: DWORD): HWND;
  101.  
  102.       ---------------------------------------------------------
  103.  
  104.       EG. To open a CHM file
  105.  
  106.           HtmlHelp(GetDesktopWindow, "Help.chm", HH_DISPLAY_TOPIC, 0);
  107.  
  108.       EG. To open a CHM file at a particular Topic
  109.  
  110.           HtmlHelp(GetDesktopWindow, "Help.chm::/Intro.htm", HH_DISPLAY_TOPIC, 0);
  111.  
  112.       EG. To open a CHM file at a particular Topic and use a Window definition
  113.           called "Mainwin".
  114.  
  115.           HtmlHelp(GetDesktopWindow, "c:\Help.chm::/Intro.htm>Mainwin", HH_DISPLAY_TOPIC, 0);
  116.  
  117.       EG. To open a CHM file using context help = 1001
  118.  
  119.  
  120.           HtmlHelp(GetDesktopWindow, "c:\Help.chm", HH_HELP_CONTEXT, 1001);
  121.  
  122.  
  123.       Note: Most people tend to use 0 instead of GetDesktopWindow. 
  124.  
  125.  
  126.    **** Warning Warning Will Robinson ****
  127.  
  128.       If you call the HH API directly from your application, that is not though
  129.       a second helper program like HH.EXE or KEYHH.EXE, you MUST close any open help
  130.       windows before shutting down the application or you will probably crash Windows.
  131.  
  132.       The call to close all windows is simply:
  133.  
  134.          HH.HtmlHelp(0, nil, HH_CLOSE_ALL, 0);
  135.       
  136.  
  137. ================================================================================
  138. 3. UNIT HH_FUNCS.PAS
  139. ================================================================================
  140.    Optional Unit provides a library of handy functions to help you
  141.    access HTML Help from Delphi 3, 4 and 5 applications.
  142.  
  143.  
  144. 3.1 GLOBAL VARS AND CONSTANTS
  145. ================================================================================
  146.  
  147.    At the heart of HH is the activeX control "HHCTRL.OCX".
  148.    At the heart of IE is the activeX control "SHDOCVW.dll".
  149.    We can get lots of useful information from these two DLLs.
  150.    These variables are initialized at program startup.
  151.  
  152.    VAR
  153.      _hhInstalled: Boolean;           Set TRUE if HTML Help is installed
  154.      _hhVerStr: String;               eg. '4.73.8252.1' or '' if not found
  155.      _hhMajVer: word;                 eg. 4
  156.      _hhMinVer: word;                 eg. 73
  157.      _hhBuildNo: word;                eg. 8252
  158.      _hhSubBuildNo: word;             eg. 1
  159.      _hhFriendlyVerStr: String;       eg. '1.2'
  160.      _ieInstalled: Boolean;           Set TRUE if Internet Explorer Installed
  161.      _ieVerStr: String;               eg. '5.00.0910.1309'
  162.      _ieFriendlyVerStr: String;       eg. 'Internet Explorer 4.01'
  163.  
  164.  
  165.    Sometimes you need to use a special CHM path prefix.
  166.    1. When opening a CHM file using "HH.EXE" command line.
  167.       (prefix not required in later version of HTML Help)
  168.    2. When opening a CHM file from web page link or in Internet Explorer.
  169.  
  170.    In these cases you need to prefix the CHM path with either:
  171.  
  172.    CONST
  173.      HH_PREFIX_IE4 = 'ms-its:';             //IE4 and above compatible command line prefix
  174.      HH_PREFIX_IE3 = 'mk:@MSITStore:';      //IE3 and above compatible command line prefix
  175.  
  176.    EG. ms-its:c:\Help.chm::/Intro.htm
  177.    EG. mk:@MSITStore:c:\Help.chm::/Intro.htm
  178.  
  179.    Note: 'ms-its:' can be shorted to just 'its:'. IE4/5 understands this. 
  180.  
  181.  
  182. 3.2 MAKING DELPHI USE HTML HELP
  183. ================================================================================
  184.    Class "THookHelpSystem" can be used to redirect all Delphi Help calls
  185.    to HTML Help calls.
  186.  
  187.    TO INSTALL:
  188.  
  189.      // 1. Use the unit and declare a global
  190.      USES HH, HH_FUNCS;
  191.      var mHHelp: THookHelpSystem;
  192.  
  193.      // 2. Create the Object in main form create.
  194.      procedure TMainForm.FormCreate(Sender: TObject);
  195.      begin
  196.        mHHelp := THookHelpSystem.Create(pathToCHM, '', htHHAPI);
  197.        ...
  198.  
  199.      // 3. Free the object in main form destroy
  200.      procedure TMainForm.FormDestroy(Sender: TObject);
  201.      begin
  202.        //Unhook and free
  203.        mHHelp.Free;
  204.        HHCloseAll;     //Close help before shutdown or big trouble
  205.        ...
  206.  
  207.      Thats all there is to it. Delphi will now direct all its help
  208.      calls to the specified CHM help file instead of the WinHelp system.
  209.      You simply continue to use the "HelpContext" properties and commands
  210.      like you always have.
  211.  
  212.      EG. Set Form.HelpContext=1001. Press F1 will open the CHM using context 1001.
  213.      EG. Set Control.HelpContext=1002. Press F1 will open the CHM using context 1002.
  214.      EG. Application.HelpContext(1003) will open the CHM using context 1003.
  215.  
  216.  
  217.    CALLBACKS (new for V1.5):
  218.  
  219.      Normally the hook class simply receives the WinHelp help messages and executes a 
  220.      standard HTML Help context call. Two callbacks are available so you can overwrite  
  221.      the WinHelp Help_Context and Help_ContextPopup messages with your own functions.
  222.  
  223.      In the real world example that follows, we have intercepted both types of WinHelp 
  224.      messages so that we can look up the topic path in an ini file using the HelpId.
  225.  
  226.      Note:  Help_ContextPopup messages (with the controls X,Y position) only appear 
  227.         if you set the the forms BorderIcons property to include biHelp. Alternatively
  228.         in the FormCreate() -- Self.BorderIcons := Self.BorderIcons + [biHelp];
  229.  
  230.      {All Help_Context messages will come here} 
  231.      procedure MyHelpButtonEvent(ContextHelpID: Longint);        
  232.      var CHMPath: String;
  233.      begin
  234.         // We are have a look up table (ini file) containing the HelpID to HelpTopic mapping
  235.         CHMPath := LookUpPathFromID(ContextHelpID) ;
  236.         HH.HtmlHelp(GetDesktopWindow, PChar(CHMPath), HH_DISPLAY_TOPIC, 0)      
  237.      end;
  238.  
  239.      {All 'Whats This' & F1 Help_ContextPopup WinHelp events will come here}  
  240.      procedure F1HelpEvent(ContextHelpID: Longint; X, Y: Integer);
  241.      var ChmPath: String;
  242.      begin
  243.         // We are have a look up table (ini file) containing the HelpID to HelpTopic mapping
  244.         CHMPath := LookUpPathFromID(ContextHelpID) + '>$GLOBAL_F1WIN';
  245.         HH.HtmlHelp(GetDesktopWindow, PChar(CHMPath), HH_DISPLAY_TOPIC, 0)      
  246.      end;
  247.  
  248.     
  249.      // 2. Create the Object in main form create.
  250.      procedure TMainForm.FormCreate(Sender: TObject);
  251.      begin
  252.        mHHelp := THookHelpSystem.Create(pathToCHM, '', htHHAPI);
  253.  
  254.        {hook in our special functions}
  255.        mHHelp.HelpCallback1 := HelpButtonEvent;
  256.        mHHelp.HelpCallback2 := F1HelpEvent;
  257.  
  258.        {Enable Whats This help messages}
  259.        Self.BorderIcons := Self.BorderIcons + [biHelp];
  260.        ...
  261.  
  262.  
  263.      // 3. Free the object in main form destroy
  264.      procedure TMainForm.FormDestroy(Sender: TObject);
  265.      begin
  266.        //Unhook and free
  267.        mHHelp.Free;
  268.        HHCloseAll;     //Close help before shutdown or big trouble
  269.        ... 
  270.  
  271.    MORE INFO:
  272.  
  273.       constructor Create(aDefChmFile, aDefWinDef: String; aHostType: THostType);
  274.  
  275.         o aDefChmFile - Name of CHM help file opened when F1 pressed.
  276.         o aDefWinDef  - Set to empty string to specify the default help window.
  277.         o aHostType   - Normally you would specify "htAPI".
  278.  
  279.         "htAPI"       - This application is hosting the help via the HH API.
  280.         "htKeyHHexe"  - KeyWorks KeyHH.EXE is hosting the help calls.
  281.         "htHHexe"     - Windows HH.EXE is hosting the help calls.
  282.  
  283.         The advantage of using a separate EXE to call help is...
  284.         a) It separates help from your programs runtime memory
  285.         b) Delphi applications have problems with hosting HTML Help in the
  286.            situation where the online help is using a Delphi Automation Server.
  287.  
  288.            EG. We use a COM control to display videos. When the COM help shuts
  289.            down it produces and access violations. Whether its Delphs fault or
  290.            IEs fault its still a problem.
  291.  
  292.            If you do use ActiveX, COM, Automation libraries to extend your
  293.            help page capabilities and you get access violations on NT or
  294.            Win98 machines then change to using the "KeyHH.EXE" host. "HH.EXE"
  295.            has very limited options and only HH 1.1b and above supports
  296.            contextual help calls via the command line.
  297.  
  298.            Download "KeyHH.EXE" from "http://www.keyworks.net/"
  299.  
  300.            *** 18-Apr-2000: Delphi 5 + HH 1.3 seem OK now.
  301.  
  302.            
  303.       Other Methods and Properties:
  304.  
  305.         function HelpTopic(aTopic: String): Integer;
  306.         property ChmFile: String;
  307.         property WinDef: String;
  308.         property HostType: THostType;
  309.  
  310.         o You can change the CHM help file at any time.
  311.           EG. mHHelp.ChmFile := 'c:\myhelp.chm';
  312.  
  313.         o You can change the CHM window definition at any time.
  314.           EG. mHHelp.WinDef := 'Mainwin';
  315.           EG. mHHelp.WinDef := '';           // '' for default window
  316.  
  317.         o You can change the Host application at any time. See notes above.
  318.           EG. mHHelp.HostType = htAPI;
  319.  
  320.         o Open a help topic directly
  321.           EG. mHHelp.HelpTopic('\options\index.htm');
  322.  
  323.  
  324.      Note:
  325.  
  326.        With the new callback option in V1.5 we tend to ignore the above 
  327.        class methods and when our callback function receives a help event
  328.        we call the HH.htmlhelp() low level function directly. Its clearer
  329.        code and HH.htmlhelp() also returns the handle of the HH window.
  330.  
  331.      Whats This Help
  332.  
  333.        To enable the "Whats This" Help_ContextPopup messages you must set
  334.        Self.BorderIcons := Self.BorderIcons + [biHelp];
  335.        Do this in the FormCreate() or Object Inspector. The Whats This 
  336.        button in the title bar will not show if you have minimize
  337.        or maximize buttons. But you can make a toolbar button behave like 
  338.        a Whats This button like this..
  339.  
  340.        procedure TForm1.WhatsThisToolButtonClick(Sender: TObject);
  341.        begin
  342.           DefWindowProc(handle, WM_SYSCOMMAND, SC_CONTEXTHELP, 0);
  343.        end; 
  344.      
  345.  
  346.  
  347. 3.3 HTML HELP FUNCTIONS
  348. ================================================================================
  349.    Here are some HTML Help functions. You can go fishing through
  350.    hh_funcs.pas to discover other useful functions.
  351.  
  352.  
  353.    function HHDisplayTopic(aChmFile, aTopic, aWinDef: String;
  354.                            aHostType: THostType): Integer;
  355.  
  356.       Display a help topic from the CHM file using a specific Window Definition.
  357.  
  358.       aChmFile:  Name of compressed help file to display.
  359.       aTopic:    Path to html file in Chm file. Leave blank for default page.
  360.       aWinDef:   Specify a window definition. Leave blank for default Window.
  361.                  Note: not supported by some versions of HH.EXE and KeyHH.EXE
  362.       aHostType: Who will host the HH Window. See Notes above.
  363.       Returns:   All OK, HH_ERR_HHNotInstalled,
  364.                  HH_ERR_KeyHHexeNotFound (aHostType = htKeyHHexe)
  365.                  HH_ERR_HHexeNotFound (aHostType = htHHexe)
  366.       Example:   HHDisplayTopic('windows.chm','about_magnify.htm','windefault', htHHAPI);
  367.  
  368.  
  369.    function HHTopic(aCHMPath: String; aHostType: THostType): Integer;
  370.  
  371.       Same as above except aChmFile, aTopic and aWinDef are entered
  372.       as aChmPath EG. "aChmFile::/Topic>aWinDef"
  373.  
  374.  
  375.    function HHHelpContext(aChmFile: String; aContextID: DWord;
  376.                  aWinDef: String; aHostType: THostType): Integer;
  377.  
  378.       Displays a help topic from the CHM file based on a mapped topic ID.
  379.  
  380.       aChmFile:  Name of compressed help file to display.
  381.       aContext:  Specifies the numeric ID of the topic to display.
  382.       aWinDef:   Specify a window definition. Leave blank for default Window.
  383.                  Note: not supported by some versions of HH.EXE and KeyHH.EXE
  384.       aHostType: Who will host the HH Window. See Notes above.
  385.       Returns:   All OK, HH_ERR_HHNotInstalled,
  386.                  HH_ERR_KeyHHexeNotFound (aHostType = htKeyHHexe)
  387.                  HH_ERR_HHexeNotFound (aHostType = htHHexe)
  388.       Example:   HHHelpContext('windows.chm',200,'windefault', htHHAPI);
  389.  
  390.  
  391.    function HHContext(aChmPath: String; aContextId: Integer; aHostType: THostType): Integer;
  392.  
  393.       Same as above except aChmFile and aWinDef are entered as
  394.       aChmPath EG. "aChmFile>aWinDef".
  395.       Note: HH.EXE host reqires a prefix EG. "mk:@MSITStore:"
  396.  
  397.    Procedure HHShowError(err: Integer);
  398.  
  399.       Call to automatically display any error message for the above functions.
  400.  
  401.       Example:
  402.          ret := HHHelpContext('windows.chm',200,'windefault', htHHAPI);
  403.          HHShowError(ret);  //if ret <> 0 then we see an error
  404.  
  405.  
  406. 3.4 DEBUGING FUNCTIONS
  407. ================================================================================
  408.     To enable logging of debug messages to log file ".\HHdebug.txt" (you override the name)
  409.     either set the global var _DebugMode := TRUE
  410.     or create a file called ".\debug.debug".
  411.  
  412.     This can be very useful. If a client is reporting problems, then you can
  413.     simply create ".\debug.debug", run the program and examine the log file.
  414.  
  415.  
  416.     procedure DebugOut(msgStr: String; const Args: array of const);
  417.  
  418.        Send a string to the debug log file. Normally used with global "_DebugMode".
  419.        Takes same parameters as Delphs FORMAT() function.
  420.        Put lots of debug into you files. You never know when you may need it.
  421.  
  422.        Example:
  423.  
  424.          if _DebugMode then
  425.            DebugOut('_RunDir = "%s"', [_RunDir]);
  426.  
  427.          Or call DebugOut2() which does the same code.
  428.  
  429.     procedure ShowDebugFile;
  430.  
  431.        Display the debug file using windows default text editor.
  432.  
  433.     procedure ResetDebugFile;
  434.  
  435.        Reset the log file. Log is truncated and some global vars
  436.        are written to it.
  437.  
  438.  
  439. ================================================================================
  440. 4. LEGAL INFO
  441. ================================================================================
  442.  
  443.    o The Kit is Freeware.
  444.    o You are free to rewrite it and hack it to bits.
  445.      But please don't distribute it in a modified form.
  446.    o You may not freely distribute the Kit without the authors consent.
  447.      Companies and sites may however direct others to our web site.
  448.    o This software is provided 'as is'. Although tested thoroughly we cannot
  449.      guarantee the software is bug free. You use it at your own risk.
  450.    o Support is available via email within reason.
  451.      IE. Don't expect heaps for something you paid nothing for :-)
  452.  
  453.    Enjoy, and please take some time to check out the rest of our site
  454.    at http://www.helpware.net
  455.  
  456.    support@helpware.net
  457.  
  458. ================================================================================
  459.  
  460. *** END OF FILE ***
  461.  
  462.  
  463.  
  464.  
  465.  
  466.