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:
----------------
unit cdCHMHelp;
interface
uses
Windows, Classes, Controls, Forms, StdCtrls, SysUtils;
type
TForm1 = class(TForm)
Button1: TButton;
Button2: TButton;
procedure Button1Click(Sender: TObject);
procedure FormCreate(Sender: TObject);
procedure Button2Click(Sender: TObject);
private
{ Private declarations }
public
{ Public declarations }
end;
{ external declaration }
function HtmlHelpByName(hwndCaller: THandle; pszFile: PChar; uCommand: Cardinal; dwData: string): THandle; stdcall; external 'hhctrl.ocx' name 'HtmlHelpA';
function HtmlHelpByID(hwndCaller: THandle; pszFile: PChar; uCommand: Cardinal; dwData: integer): THandle; stdcall; external 'hhctrl.ocx' name 'HtmlHelpA';
var
Form1 : TForm1;
HELP_FILE : string;
const
{ takes user to... }
HH_DISPLAY_TOPIC = $0000; { ...individual HTML file within CHM file }
HH_HELP_CONTEXT = $F; { ...page, provided a [MAP] listing exists }
{ following variables can be substituted in place of HH_DISPLAY_TOPIC,
as appropriate - pass 'ActiveControl.HelpContext' via tHelpPage; this
only works with the HTMLPageByID function, due to tHelpPage having to
be declared as an Integer, not a String}
HH_DISPLAY_TOC = $0001; { takes user to the table of contents }
HH_DISPLAY_INDEX = $0002; { takes user to the main index }
implementation
{$R *.dfm}
{******************************************************************************}
{ this routine shows the appropriate page within the CHM file, based on the file
name being passed }
function ShowHtmlHelpByName(tHelpFile: string; cHELP_COMMAND: Cardinal; tHelpPage: string): Cardinal;
begin
Result := HtmlHelpByName(Form1.Handle, PChar(tHelpFile), cHELP_COMMAND, tHelpPage);
end;
{******************************************************************************}
{ this routine shows the appropriate page within the CHM file, based on the
tHelpPage integer being passed. Note, This requires a corresponding [MAP] ID
code to be present in the help file }
function ShowHtmlHelpByID(tHelpFile: string; cHELP_COMMAND: Cardinal; tHelpPage: integer): Cardinal;
begin
Result := HtmlHelpByID(Form1.Handle, PChar(tHelpFile), cHELP_COMMAND, tHelpPage);
end;
{******************************************************************************}
procedure TForm1.FormCreate(Sender: TObject);
begin
{ define path to CHM help file - modify accordingly}
HELP_FILE := ExtractFilePath(Application.ExeName) + '\TALFlatXPEdit.chm';
end;
{******************************************************************************}
procedure TForm1.Button1Click(Sender: TObject);
begin
{ passes name of help file, and helpcontext, to the main Help function }
ShowHtmlHelpByID(HELP_FILE, HH_HELP_CONTEXT, 1001);
end;
{******************************************************************************}
procedure TForm1.Button2Click(Sender: TObject);
begin
{ passes name of help file, and HTML file within, to the main Help function }
ShowHtmlHelpByName(HELP_FILE, HH_DISPLAY_TOPIC, 'html/license.html');
end;
{******************************************************************************}
end.