Fancy using HTML Help in your Delphi applications ?
Borland included an easy way to add help functionality to your Delphi applications,
as long as you were happy to use *.hlp files. If, however, you wanted to use CHM
files, then this would involve a little more work.
Ther are several examples of how to do this, available on the Internet. Most of
which that I have found have been written in the form of units, which add a lot of
code to an application. Granted, this makes life easier when it comes to adding
HTML-based functionality, but, it does complicate matters. I wanted to try and
simplify the code, so that it was easier to understand, and at least be usable to
provide basic help. Below is my result - please feel free to read, and use the code
as you wish.
The process, based around the example below, is as follows, although it does rely
on some previsions:
1. You have started a new project, which has been saved.
2. On the form for this project, there are 2 buttons: Button1 has "Show Help by
[MAP] ID" as a caption. Button2 has "Show Help by File Name" as its caption.
4. Within the same folder, you have a CHM help file.
- Its name is not critical, but it must be the same as the name used in the
project below.
- You must know the names of the HTML files which have been compiled into the CHM
file.
The code has been tested on Delphi 7 - it may work in earlier versions, but this
cannot be guaranteed. It is possible to add other constants, to extend the
functionality, but the code below will illustrate the basic workings of how to use
compiled help.
THE PROCESS:
------------
1. Open your project (.hhp) file in a text editor, such as Notepad.
2. Add a [MAP] section and define the IDs your require - for example:
[ALIAS]
IDH_HomePage=intro.html
IDH_Topic1=html/license.html
3. Skip a line, then add an [ALIAS] section and define the mapping between each ID
and a help topic - see below for an example. The IDs used are not criticial, but
must match what is used in the Delphi unit:
[MAP]
#define IDH_HomePage 1000
#define IDH_Topic1 1001
4. Recompile the Help file. You should not see any difference in the finished
product, but it will now have the appropriate IDs for use in calling context-based
help.
THE DELPHI CODE:
----------------
1 unit cdCHMHelp;
2
3 interface
4
5 uses
6 Windows, Classes, Controls, Forms, StdCtrls, SysUtils;
7
8 type
9 TForm1 = class(TForm)
10 Button1: TButton;
11 Button2: TButton;
12 procedure Button1Click(Sender: TObject);
13 procedure FormCreate(Sender: TObject);
14 procedure Button2Click(Sender: TObject);
15 private
16 { Private declarations }
17 public
18 { Public declarations }
19 end;
20
21 { external declaration }
22 function HtmlHelpByName(hwndCaller: THandle; pszFile: PChar; uCommand: Cardinal;
23 dwData: string): THandle; stdcall; external 'hhctrl.ocx' name 'HtmlHelpA';
24
25 function HtmlHelpByID(hwndCaller: THandle; pszFile: PChar; uCommand: Cardinal;
26 dwData: integer): THandle; stdcall; external 'hhctrl.ocx' name 'HtmlHelpA';
27
28 var
29 Form1 : TForm1;
30 HELP_FILE : string;
31
32 const
33 { takes user to... }
34 HH_DISPLAY_TOPIC = $0000; { ...individual HTML file within CHM file }
35 HH_HELP_CONTEXT = $F; { ...page, provided a [MAP] listing exists }
36
37 { following variables can be substituted in place of HH_DISPLAY_TOPIC,
38 as appropriate - pass 'ActiveControl.HelpContext' via tHelpPage; this
39 only works with the HTMLPageByID function, due to tHelpPage having to
40 be declared as an Integer, not a String}
41 HH_DISPLAY_TOC = $0001; { takes user to the table of contents }
42 HH_DISPLAY_INDEX = $0002; { takes user to the main index }
43
44 implementation
45
46 {$R *.dfm}
47
48 {******************************************************************************}
49 { this routine shows the appropriate page within the CHM file, based on the file
50 name being passed }
51 function ShowHtmlHelpByName(tHelpFile: string; cHELP_COMMAND: Cardinal; tHelpPage:
52 string): Cardinal;
53 begin
54 Result := HtmlHelpByName(Form1.Handle, PChar(tHelpFile), cHELP_COMMAND,
55 tHelpPage);
56 end;
57 {******************************************************************************}
58 { this routine shows the appropriate page within the CHM file, based on the
59 tHelpPage integer being passed. Note, This requires a corresponding [MAP] ID
60 code to be present in the help file }
61 function ShowHtmlHelpByID(tHelpFile: string; cHELP_COMMAND: Cardinal; tHelpPage:
62 integer): Cardinal;
63 begin
64 Result := HtmlHelpByID(Form1.Handle, PChar(tHelpFile), cHELP_COMMAND, tHelpPage);
65 end;
66 {******************************************************************************}
67 procedure TForm1.FormCreate(Sender: TObject);
68 begin
69 { define path to CHM help file - modify accordingly}
70 HELP_FILE := ExtractFilePath(Application.ExeName) + '\TALFlatXPEdit.chm';
71 end;
72 {******************************************************************************}
73 procedure TForm1.Button1Click(Sender: TObject);
74 begin
75 { passes name of help file, and helpcontext, to the main Help function }
76 ShowHtmlHelpByID(HELP_FILE, HH_HELP_CONTEXT, 1001);
77 end;
78 {******************************************************************************}
79 procedure TForm1.Button2Click(Sender: TObject);
80 begin
81 { passes name of help file, and HTML file within, to the main Help function }
82 ShowHtmlHelpByName(HELP_FILE, HH_DISPLAY_TOPIC, 'html/license.html');
83 end;
84 {******************************************************************************}
85 end.
|
