Default Handling of F1 Help in VCL Applications
Go Up to Calling HTML Help from Applications
Contents
The standard way of activating help in applications is pressing F1. RAD Studio IDE supports appropriate options to define help parameters for automatic generation of code for activating help on pressing F1. In this case, RAD Studio automatically generates the default code necessary to execute an appropriate call to the help-handling function on pressing F1 in VCL applications.
This topic describes how to define parameters of calls to help-handling functions and how these calls are executed. Notice that the following discussion applies only to VCL GUI applications.
Help parameters you need to set
When you press F1, the OnHelp event triggers in the form that has focus. As a result, your application executes the default event handler of the OnHelp event. The IDE generates the OnHelp event handler code using the specified help parameters. In the IDE, you can specify the HelpFile, HelpType, HelpContext, and HelpKeyword help parameters that are described in the following sections.
HelpFile
First of all, you need to specify the help files that contain help topics for your application. You can specify one or several help files. You can specify the main help file for an application using the TApplication.HelpFile property of the global Application object and also a personal help file for each form, using the TForm.HelpFile property of the corresponding Form object.
You can specify these HelpFiles at design time as corresponding IDE properties used to programmatically define the HelpFile properties of corresponding objects.
The usual way to designate the main help file for an application is using the HelpFile property of the global Application object.
Open the Project Options dialog box (Project > Options) and select the Appearance page (under Application). In the Help file option, specify the help file. Click Browse. By default, the Application Help File dialog box shows only files with the .hlp extension. To specify other types of help files, select the Any file (*.*) type in the Files of type control. Then you will be able to select help files of types such as .CHM, .HTML, and others.
This option sets the Application.HelpFile property. This property defines the main help file to the application. When the application receives any help-handling command, it, by default, uses this help file to execute the help command.
To specify an individual help file for a particular form, you can use the HelpFile property of this form.
In the Form Designer, select your form; the Object Inspector shows the properties of this form as in the following figure:
In the right column of the HelpFile property, specify Form1.chm. This defines the TForm.HelpFile property of the Form1 object. This property sets the Form1.chm help file for the particular Form1 form.
The application usually searches for the help file in the directory from which the application's executable file runs. Therefore, if the specified help file is in another directory, then you should specify the relative path to this file. For example, you can specify .\Help\Form1.chm.
The default OnHelp event handler uses the help file specified in the HelpFile property of the form having the focus. If the TForm.HelpFile property contains an empty string, then the event handler uses the help file specified in the HelpFile property of the global Application object.
HelpType, HelpContext, and HelpKeyword
To generate the default event handler code for the OnHelp event, the IDE needs to know which help topic to show. The values of the HelpContext and HelpKeyword properties can define which topic to show. The HelpType property defines which of these two properties to use.
In the Object Inspector for the form, click the right column of the HelpType property. If you select the htContext value, then the value specified in the HelpContext property is used. If you select the htKeyword value, then the value specified in the HelpKeyword property is used.
What to add to the generated code
Applications developed with RAD Studio use external help viewers to show different types of help files. You need to instruct your application which external help viewer to use.
Wrappers of External Help Viewers
The VCL is designed to be independent of the external help viewer. All help features used by the default help event handlers are declared in interfaces of the System.HelpIntfs unit. The VCL provides packages that contain classes implementing these interfaces with a particular external help viewer (which handles the particular type of help files). For example, the Vcl.HtmlHelpViewer unit implements a wrapper to the HTMLHelp API for the viewer of CHM (Microsoft HTML Help) help files.
This independence (from external help viewers) means that you only need to specify the appropriate unit--providing the implementation of the HelpIntfs interfaces for a particular external help viewer--in the uses section. For example, you can specify the Vcl.HtmlHelpViewer unit to view CHM help files.
For instance, having defined the discussed above (HelpFile, HelpType, HelpContext, and HelpKeyword) properties , the default OnHelp event handler can use the help-handling function like this:
IHelpSystem.ShowContextHelp(Form1.HelpContext, Form1.HelpFile);
if HelpType = htContext, and like this:
IHelpSystem.ShowHelp(Form1.HelpKeyword, Form1.HelpFile);
if HelpType = htKeyword. Here IHelpSystem is the interface declared in the HelpIntfs unit.
Accessing External Help Viewers
The following sections discusses on how IHelpSystem and other interfaces, declared in the HelpIntfs unit, are implemented by classes in a unit that provides a wrapper for an external help viewer. For example, look at the Vcl.HtmlHelpViewer unit that provides a wrapper for the HTMLHelp function API. The Vcl.HtmlHelpViewer unit implements the THTMLHelpViewer class that provides an implementation for interfaces from the HelpIntfs unit. However, the THTMLHelpViewer class is declared in the implementation section of the unit. Therefore, you need to understand how members of this class can be accessed outside of the Vcl.HtmlHelpViewer unit.
The HelpIntfs unit provides two global functions: RegisterViewer and GetHelpSystem. These functions have the following declarations:
function RegisterViewer(const newViewer: ICustomHelpViewer; out Manager: IHelpManager): Integer; function GetHelpSystem(out System: IHelpSystem): Boolean;
The initialization section of the Vcl.HtmlHelpViewer unit executes the two following calls:
HelpViewer := THtmlHelpViewer.Create; HelpIntfs.RegisterViewer(HelpViewerIntf, HelpViewer.FHelpManager);
These calls create an object of type THtmlHelpViewer and register the wrapped external Help Viewer object as a Help System Manager object--HelpViewer.FHelpManager--of type IHelpManager.
To invoke the registered external Help Viewer, code can call the HelpIntfs.GetHelpSystem flat function, which can access the object stored in HelpViewer.FHelpManager and then return an IHelpManager type object in the IHelpSystem type object. TApplication has the HelpSystem property that also provides access to this IHelpSystem type object, through which TApplication methods call the Help viewer functions. IHelpSystem type objects provide IHelpSystem.ShowContextHelp, IHelpSystem.ShowHelp, and other help functions. The default OnHelp event handler and the user code can call these functions.
Steps to show the F1 help
When you press F1, the application activates the default event handler for the OnHelp event of the form that has focus. The previous sections of this topic discussed theoretical aspects of setting help properties in the Object Inspector and adding the code you need in order to activate the proper help page.
To achieve these in practice, use the following steps.
To show the F1 help
- Set the HelpFile property of the global Application object (the TApplication.HelpFile property) or of particular forms (the TForm.HelpFile property). For example, you can set:
TForm.HelpFile = Form1.chm
- For a particular form, select the HelpType property and set
htContextorhtKeyword. For example, you can set
TForm.HelpType = htContext
- Then set the proper
ContextIDvalue in the TForm.HelpContext property.ContextIDshould be an integer identifying a topic in the help file specified by HelpFile. For example, in case of CHM help files, you must map symbolic Context IDs of help topics to numericContextIDvalues in the [MAP] section of your project (.hhp) file. For example, set TForm.HelpContext = 714- Now, pressing F1 displays the topic with the
ContextIDequal to714from a CHM help file identified in HelpFile. - Otherwise, set
TForm.HelpType = htKeyword- Then set the proper
Keywordvalue in the TForm.HelpKeyword property. Now, pressing F1 displays the topic having the specifiedKeywordvalue as itsAlinktag value.
- Then set the proper
- In Delphi applications, add the Vcl.HtmlHelpViewer unit to the uses clause of the main module of your application.
In C++ applications, add the#include Vcl.HtmlHelpViewer.hppdirective.
Add#pragma package(smart_init)and#pragma link "Vcl.HtmlHelpViewer"
This defines that your application uses the API of the HTMLHelp function that shows CHM help files. - Select the Run > Run command. Your application opens.
- Select the Form1 form. Press F1. The automatically generated default OnHelp event handler shows the help topic specified by the HelpContext (or HelpKeyword) value in the specified .CHM help file.
Notice that no manual programming was necessary. All help handling on F1 pressing was implemented automatically. You only have to specify proper Help parameters using the Object Inspector.