Customizing F1 Help in VCL Applications

From RAD Studio
Jump to: navigation, search

Go Up to Calling HTML Help from Applications


The developer can explicitly program the OnHelp event handlers of the Application object and of particular forms.

To modify the OnHelp event handler of a form, open the form in the Form Designer.

Then, in the Object Inspector, select the Events tab, locate the OnHelp event, and double-click in the right column. The Code Editor opens the file with the form-handling code and places the cursor inside the begin … end block of the generated frame code for the OnHelp event handler. The generated code can look like this:

function TForm1.FormHelp(Command: Word; Data: Integer; var CallHelp: Boolean): Boolean;
begin
 ... 
end; 

Here you can type your help-handling code. Because the TForm1.FormHelp' event handler is the method of the Form1 object of the TForm1 class, you can use any help features of the Form1 and Application objects. For example, you can write the code like this:

function TForm1.FormHelp(Command: Word; Data: Integer; var CallHelp: Boolean): Boolean;
begin
  HelpFile := ExtractFilePath(Application.ExeName) + HelpFile; 
  Application.HelpShowTableOfContents();
  CallHelp :=  False; // True; - to execute the default OnHelp event handler
end; 

Here, in the first line, when redefining HelpFile, you assume that the initial HelpFile contains the relative path from the application executable to the help file local for the Form1 form. This redefinition guarantees that this help file will always be correctly located by the running application.

Application.HelpShowTableOfContents shows the Table of Contents in the CHM help file defined in the TForm1.HelpFile for the Form1 form.

Notice that setting CallHelp to False indicates that the default OnHelp event handler does not execute. If you need that the default OnHelp event handler execute after your manually programmed event handler, then you need to define:

CallHelp :=  True; 


Note: Notice that you cannot use the Application.HelpCommand in your code of the OnHelp event handler
Application.HelpCommand(NativeCommand, Data)  
to pass the NativeCommand options to the native HTMLHelp API function (or other native API). The Application.HelpCommand function triggers the OnHelp event on the active form. Therefore, calling the HelpCommand function inside the OnHelp event handler leads to an endless loop in the OnHelp event.
Therefore, to pass the NativeCommand options to the HTMLHelp API function, you should call
IHelpSystem.GetHelpSystem(HelpSystem)
and then
HelpSystem.Hook(Handle, HelpFile, NativeCommand, Data);

See Also