CSHelp
.topic 10000
Delphi supports a central property to hold the name of the help file: The property Application.helpfile.
You can either set the property manually at run time or you can specify it directly in the Delphi IDE under "Project Options":
Resulting in our first problem
When you click Browse in the dialog shown above, Delphi not only saves the file name but the full path as well.
But when your application is installed on another computer, the path may differ.
It would be better to specify only the file name without a path or use a relative path name like ".\help\myhelpfile.hlp"
If you do so, you have to place your help file in the same directory as your application is. This is generally a good idea! If your application uses more help files than only one, you may want to bundle them in a separate sub-directory, as the relative path name above illustrates.
Resulting in a secondary problem
If you do not specify a fully qualified path name for your help file, the help file is assumed to be in the current directory or in a directory relative to the current. When your application starts, the current directory is usually the application directory, of course. At the beginning, this condition is true. But the current directory may change while your application is running. What happens then? Correct! The help file is not found.
Making it always work
Fortunately, you can change the Application.helpfile property at run time as well.
The best place to do this, is the OnCreate event of your main form:
Add the following code to this event (myhelpfile.hlp has to be replaced with your real help file name):
procedure TMainForm.FormCreate(Sender: TObject);
begin
Application.helpfile :=
extractfilepath(application.exename) + 'myhelpfile.hlp';
end;
This defines the help file including a fully qualified path (assumed that your help file is in the same directory as your application) and works in any case, whether the current directory has changed or not.
.topic 10100
Well, your Delphi application now knows that is has a help file. Fine. But how can you display the help file?
Delphi provides you with a method called
Application.Helpcommand(command, data).
This method encapsulates all help file calls. You can call the table of contents, display a specific topic, search for a keyword and much more.
Example:
procedure TFrmHelpman.mHelpContentsClick(Sender: TObject);
begin
Application.HelpCommand(HELP_FINDER, 0);
end;
The Command parameter must match one of the predefined Windows API constants and Data must be set accordingly.
The following topic explains the available parameters. The next chapter discusses almost the same, but from a more practical point of view. It tells you the how to does.
See also
Parameters of Application.HelpCommand
.topic 10200
The online help of Delphi describes the method Application.HelpCommand in a short sentence:
"Provides quick access to any of the Help commands in the WinHelp API.
function HelpCommand(Command: Word; Data: Longint): Boolean;"
This is not much, isn't it? Well, let's examine the WinHelp API. The Winhelp API defines the following constants for Command. Depending on Command, you must support an appropriate Data parameter as well. Don't worry, the following description illustrates the usage with a code example for each.
The list of available parameters:
HELP_COMMAND
Don't mistake this constant with the general "HelpCommand" function of Delphi. This constant has an underscore between help and command. It is used to execute a macro. The Data parameter is a pointer to a string that specifies the macro. A macro must also be used to display a specific topic by topic ID.
Code example to display a specific topic
Code example for another macro
HELP_CONTENTS
Displays the so-called "default topic" or the very first topic of your help file, if the "default topic" is not explicitly defined. It does not display the table of contents of a Winhelp file as its name suggests. It comes from 16 bit times when Windows help files did not have an extra table of contents but a topic instead, that displayed an overview and links to all other topics. This old "contents" topic is still alive. If the table of contents of a help file is missing, this topic is displayed when you open the help file.
Code example how to display the default topic
HELP_CONTEXT
Displays a topic by using its help context number. This is exactly what Delphi does automatically when it displays context sensitive help. The Data parameter is an integer value that represents the help context number.
Code example for context sensitive help
HELP_CONTEXTPOPUP
Displays a topic by using its help context number. This is exactly what Delphi does automatically when it displays context sensitive help. The Data parameter is an integer value that represents the help context number.
Code example
HELP_FINDER
This command actually displays the table of contents of a Windows 95 help file. The Data parameter is zero.
Code example
HELP_FORCEFILE
Ensures that WinHelp is displaying the correct Help file. If the incorrect Help file is being displayed, WinHelp opens the correct one; otherwise, there is no action.
Code example
HELP_HELPONHELP
Displays help on how to use a help file. This command forces Winhelp to open the appropriate topics of its own help file, Winhelp.hlp. The Data parameter is zero.
Code example
HELP_INDEX
This command is obsolete. Use HELP_FINDER instead.
HELP_KEY
This command searches for a single keyword:
· If the given keyword does not match any keyword of the help file, the keyword index is displayed.
· If there is only one topic, that specifies the keyword, the topic is displayed.
· If more topics than only one specify this keyword, a list of matching topics is displayed.
The Data parameter is a pointer to a string that contains the keyword to look for.
Code example for HELP_KEY
HELP_MULTIKEY
Displays the topic specified by a keyword in an alternative keyword table. Winhelp knows two types of keywords.
· K-keywords are normal keywords defined by K-footnotes. These keywords are displayed in the keyword index on the Index tab. You can also create links to other topics by using the KLink macro and K-keywords.
· A-keywords are hidden keywords defined by A-footnotes. These keywords are not displayed in the keyword index but used for context sensitive help. When you press F1 in the Delphi IDE, Delphi searches for an A-keyword matching the text the cursor is in or the selected property name in the Object Inspector. You can also create links to other topics by using the ALink macro and A-keywords.
If this keyword functionality does not satisfy you, you can define other keywords in your help file by additional footnotes (e.g. B-footnotes like Delphi did in version 2, C-footnotes and so on). The HELP_MULTIKEY command lets you access these keywords as the HELP_KEY command lets you access the normal K-keywords.
HELP_PARTIALKEY
This command works the same way as HELP_KEY.
Code example
HELP_QUIT
Closes a help file. The Data parameter is zero.
Code example
HELP_SETCONTENTS
This command is obsolete.
HELP_SETINDEX
This command is obsolete.
HELP_SETWINPOS
Sets the position and size of a help window. The Data parameter is a pointer to a THelpWinInfo structure.
Code example
.topic 1100
The following example displays the topic "howtoregister" of your help file. You may want to use it in an about dialog when your application is a demo version only. The macro "JI()" is short for "JumpID". For a complete list of available macros please refer to the help of the Microsoft help workshop (hcw.hlp).
var
command: array[0..255] of Char;
begin
command := 'JI(howtoregister)';
application.helpcommand(HELP_COMMAND, Longint(@command));
end;
You may find it easier to use the Delphi method Application.HelpJump instead.
See also:
More information about Winhelp macros
.topic 1010
Example, how to display the about box of the current help file. It uses the Winhelp macro "About()" which has no parameters.
procedure TForm1.ShowHelpAbout;
var
command: array[0..255] of Char;
begin
command := 'About()';
application.helpcommand(HELP_COMMAND, Longint(@command));
end;
If you are curious how this about box looks, click here.
See also:
More information about Winhelp macros
.topic 1020
This example displays the default topic. The data parameter is simply zero in this case:
begin
application.helpcommand(HELP_CONTENTS, 0);
end;
.topic 1030
This example displays the "table of contents" of a Windows 95 help file:
procedure TFrmHelpman.mHelpContentsClick(Sender: TObject);
begin
Application.HelpCommand(HELP_FINDER, 0);
end;
Remember: a Windows 95 (98/NT4/2000) help file consists of two files! If the table of contents is missing, Winhelp just displays the so-called default topic instead.
.topic 1040
Display context sensitive help from a HelpContext number. The topic is displayed in the main window of your help file. To display the context sensitive help as a popup topic, use HELP_CONTEXTPOPUP.
procedure TForm1.WhatsthisClick(Sender: TObject);
var
ihc: longint;
begin
if (Sender is TWincontrol) or (Sender = TMenuitem) then
begin
ihc := TWincontrol(Sender).HelpContext;
application.helpcommand(HELP_CONTEXT, ihc);
end
else showmessage('No context sensitive help available');
end;
You may find it easier to use the Delphi method Application.HelpContext instead.
By the way, this is the HelpContext property in the Delphi IDE:
See also
Command parameter HELP_CONTEXTPOPUP
About context sensitive help
.topic 1050
Display context sensitive help from a HelpContext number in a popup window.
procedure TForm1.WhatsthisClick(Sender: TObject);
var
ihc: longint;
begin
if (Sender is TWincontrol) or (Sender = TMenuitem) then
begin
ihc := TWincontrol(Sender).HelpContext;
application.helpcommand(HELP_CONTEXTPOPUP, ihc);
end
else showmessage('No context sensitive help available');
end;
See also
Command parameter HELP_CONTEXTPOPUP
About context sensitive help
.topic 1060
This example closes the help file if it is open. The data parameter is zero in this case:
begin
application.helpcommand(HELP_QUIT, 0);
end;
.topic 1070
This example displays the "help on help" topics from Winhelp.hlp.
procedure TForm1.mHelpHowtousehelp(Sender: TObject);
begin
Application.HelpCommand(HELP_HELPONHELP, 0);
end;
.topic 1080
This example searches for a single keyword.
procedure TForm1.Button1Click(Sender: TObject);
var
keyword: string;
Command: array[0..255] of Char;
begin
keyword := Edit1.text;
StrLcopy(Command, pchar(keyword), SizeOf(Command) - 1);
Application.helpcommand(HELP_KEY, Longint(@Command));
end;
.topic 1090
1. A non-working example?
This example should set the position and size of a help window. The following code should be correct. However, I never got it to work (if you do, please tell me how):
procedure TForm1.Button1Click(Sender: TObject);
var
hwi: THelpWinInfo;
begin
with hwi do
begin
wStructSize := SizeOf(hwi);
x := 0;
y := 0;
dx := 512;
dy := 512;
wMax := SW_SHOWNORMAL;
end;
Application.HelpCommand(HELP_SETWINPOS, LongInt(@HWi));
Application.HelpCommand(HELP_CONTENTS, 0);
end;
2. A working example:
Fortunately, there is also a help macro available that we can use to set the size and position of a help window. The following code is correct and works (in all cases, I hope):
procedure TForm1.Button1Click(Sender: TObject);
var
command: array[0..255] of Char;
begin
command := 'PW(0, 0, 512, 512, 1, "main")';
application.helpcommand(HELP_COMMAND, Longint(@command));
end;
What it does
The code example above uses the HELP_COMMAND constant to execute a macro. The macro we use here is "PositionWindow" or - short - "PW". It defines the upper left corner (x1, y1) as (0,0) and the lower right corner (x2, y2) as (512,512).
The following parameter is the integer constant for "SW_SHOWNORMAL". Winhelp does not recognize the string "sw_shownormal" in the macro string.
The last parameter is the name of the window.
One word about the coordinates of a help window
Te position and size of a help window always relates to a virtual screen size of 1024 x 1024 pixel, regardless of the screen resolution. If you set the size to (0, 0, 1024, 512), the help window would cover exactly the upper half of the screen.
