Delphi - база знаний

       

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.



Содержание раздела