Difference between revisions of "Add Help to Your Application"

From Lazarus wiki
Jump to navigationJump to search
 
(35 intermediate revisions by 13 users not shown)
Line 1: Line 1:
 
{{Add Help to Your Application}}
 
{{Add Help to Your Application}}
  
The LCL comes with a help system.
+
The LCL comes with a help system, and allows you to '''create help for your own applications'''.
  
 
== Quick Start ==
 
== Quick Start ==
 
 
Open the example in examples/helphtml/.
 
Open the example in examples/helphtml/.
  
 
This project demonstrates how to use the HTML help components. Just drop them on a form of your project. Setup the paths and create some HTML pages. Then give each control of your application a HelpKeyword.
 
This project demonstrates how to use the HTML help components. Just drop them on a form of your project. Setup the paths and create some HTML pages. Then give each control of your application a HelpKeyword.
 +
 +
See the CHM help section if you want to use CHM help files instead of HTML help files.
 +
 +
There is a very nice simple demo (chmdemo.zip) here:
 +
http://forum.lazarus.freepascal.org/index.php/topic,38487.msg261731.html#msg261731
  
 
== Help Basics ==
 
== Help Basics ==
 +
The LCL help mainly consists of two parts: Help databases and help viewers. A Help Database contains the mapping from the keywords (ID, node, message, pascal, ...) to the help page (or help web site or...). The Help Viewer is invoked by the Help Database to show the help to the user.
 +
* A [[THelpDatabase]] manages content. It can be a collection of HTML pages or fpdoc XML files or a CHM file or a database or whatever.
 +
* A [[THelpViewer]] is a component that shows help content. For example a viewer for the mime type text/html can start a web browser.
  
The LCL help mainly consists of two parts: Help databases and help viewers. A Help Database contains the mapping from the keywords (ID, node, message, pascal, ...) to the help page (or whatever). The Help Viewer is invoked by the Help Database to show the help to the user.
+
When help is requested, the LCL queries each registered [[THelpDatabase]] and each database can return a list of entries.
 +
If several entries are returned, the LCL asks the user to choose an entry.
 +
Then the LCL asks the database to show the help for the entry. The database extracts the help content and asks the LCL for a viewer that supports the mime type of the content.
 +
Finally, the viewer shows the help content.
  
A THelpDatabase manages content. It can be a collection of html pages or fpdoc xml files or a chm file or a database or whatever.  
+
== CHM ==
A THelpViewer is a component to show help content. For example a viewer for the mime type text/html can start a webbrowser.
+
Context-sensitive CHM application help can be used from Lazarus 1.0 and later.
  
When help is requested the LCL queries each registered THelpDatabase and each database can return a list of entries.
+
A demonstration program is included that shows how to include context-sensitive help using CHM and the [[lhelp]] CHM viewer (the same one that is used for IDE help by default).
If several entries are returned the LCL asked the user to select one entry.
+
Please see ${lazarusdir}/components/chmhelp/democontrol/.
Then the LCL asks the database to show the help for the entry. The database then extracts the help content and asks the LCL for an viewer that supports the mime type of the content.
 
The viewer then shows the help content.
 
  
== HTML ==
+
You can write your own CHM files, e.g. with the now ancient Microsoft HTML Workshop or with the new Lazarus chmmaker tools in $(lazarusdir)/tools/chmmaker
 +
You can use a [[TCHMHelpDatabase]] control like the [[THTMLHelpDatabase]] control described below.
 +
 
 +
The advantages of using the CHM system are a smaller, self contained help file instead of multiple files. On the other hand, not every system has a CHM viewer installed by default, so you might want to include lhelp, a CHM viewer written in Pascal and included with the Lazarus sources (components/chmhelp/lhelp/lhelp.lpi).
 +
 
 +
===Using LHelp===
 +
 
 +
*Drop a '''<tt>TCHMHelpDatabase</tt>''' on your form.
 +
*Set its '''<tt>FileName</tt>''' property to the path to the chm file, and set '''<tt>AutoRegister</tt>''' to <tt>true</tt>.
 +
*In '''<tt>KeywordPrefix</tt>''' specify the path to the html files contained in the chm file as seen from the chm root. Example: If the html help files during chm creation are in the subfolder ''html'' the <tt>KeywordPrefix</tt> is <tt>html</tt> (without trailing path delimiter!).
 +
*Put a '''<tt>TLHelpConnector</tt>''' on your form.
 +
*Set '''<tt>LHelpPath</tt>''' to the name and location of the LHelp executable (this can be absolute, or relative to the application directory)
 +
*Set '''<tt>AutoRegister</tt>''' to <tt>true</tt>.
 +
 
 +
<syntaxhighlight lang="pascal">
 +
// Example with both chm file and LHelp.exe in Application folder.
 +
procedure TForm1.FormCreate(Sender: TObject);
 +
begin
 +
  if FileExists(ChangeFileExt(Application.ExeName, '.chm')) then
 +
  begin
 +
    CHMHelpDatabase1.Filename := ChangeFileExt(Application.ExeName, '.chm');
 +
    CHMHelpDatabase1.KeywordPrefix := 'html';
 +
    CHMHelpDatabase1.AutoRegister:=True;
  
The LCL provides two components to use html files for help: THTMLHelpDatabase and THTMLBrowserHelpViewer.
+
    LHelpConnector1.LHelpPath := IncludeTrailingBackSlash(ExtractFileDir(Application.ExeName)) + 'lhelp.exe';
To see the html help see the lazarus example examples/helphtml/htmlhelp1.lpi.
+
    LHelpConnector1.AutoRegister:=True;
 +
  end
 +
  else
 +
    mnuHelpMain.Enabled := False;
 +
end;
  
=== Setup html help for your application ===
+
procedure TForm1.Button1Click(Sender: TObject);
 +
begin
 +
  if mnuHelpMain.Enabled then 
 +
    ShowHelpOrErrorForKeyword('', 'html/main.html');
 +
    //ShowTableOfContents;  (Not implemented for TCHMHelpDatabase)
 +
end;   
 +
</syntaxhighlight>
  
Adding html help to your application is easy:
+
When LHelp is invoked during execution of your project it is started by ''Inter-Process Communication'' (IPC) in a separate process which normally does not terminate when you application is closed. If you want to close LHelp with your application you should write an <tt>OnDestroy</tt> event handler to send an <tt>mrClose</tt> command to LHelp via IPC:
 +
<syntaxhighlight lang="Pascal">
 +
uses
 +
  LHelpControl;  // for "mrClose"
 +
   
 +
procedure TForm1.FormDestroy(Sender: TObject);
 +
begin
 +
  if (LHelpConnector1.Connection <> nil) and LHelpConnector1.Connection.ServerRunning then
 +
    LHelpConnector1.Connection.RunMiscCommand(LHelpControl.mrClose);
 +
end;
 +
</syntaxhighlight>
  
 +
== HTML ==
 +
The LCL provides two components to use HTML files for help: [[THTMLHelpDatabase]] and [[THTMLBrowserHelpViewer]].
 +
To see the HTML help, see the lazarus example examples/helphtml/htmlhelp1.lpi.
 +
 +
=== Setup HTML help for your application ===
 +
[[File:LazHtmlHelp.jpg|500px|thumb|right|Lazarus help items]]
 +
Adding HTML help to your application is easy:
 
*Put a '''THTMLHelpDatabase''' on a form.
 
*Put a '''THTMLHelpDatabase''' on a form.
 
*Set '''AutoRegister''' to true.
 
*Set '''AutoRegister''' to true.
*Set '''KeywordPrefix''' to '''HTML/'''. It means all keywords must start with the string ''HTML/''.
+
*Set '''KeywordPrefix''' to '''html/'''. It means all keywords must start with the string ''html/''.
*Set '''BaseURL''' to '''file://html/'''. This will search the html files in the sub folder ''html''. You can specify full paths like ''file:///usr/lib/yourhelp/'' or an URL like ''http://www.yoursite.com/''.
+
*Set '''BaseURL''' to '''file://yourhelp/'''. This will search for  HTML files in the sub folder 'yourhelp' relative to the application directory. You can specify an absolute path to the directory where HTML files are stored. For UNIX-like platforms, use an URL like ''file:///usr/lib/yourhelp/'' for local access or an URL like ''http://www.yoursite.com/'' for web access. For the Windows platform, use an URL like ''file://c:/temp/html/'' or ''file://c:\temp\html''.
 
+
*Put a '''THTMLBrowserHelpViewer''' on the form. This component can start the user's default browser.
*Put a '''THTMLBrowserHelpViewer''' on the form. This component can start the default browser of the user.
 
 
*Set '''AutoRegister''' to true.
 
*Set '''AutoRegister''' to true.
  
 
=== Creating a help entry ===
 
=== Creating a help entry ===
  
*Now create the sub folder ''html'' and create a html page ''html/edit1.html''.
+
* Now create the subfolder ''yourhelp'' and create an HTML page ''yourhelp/edit1.html''. In case of a website, the help page should be accessible as ''http://www.yoursite.com/edit1.html''
*Put a TEdit on a form.
+
* Put a TEdit on a form
*Set '''HelpType''' to ''htKeyword''
+
* Set '''HelpType''' to ''htKeyword''
*Set '''HelpKeyword''' to ''HTML/edit1.html''
+
* Set '''HelpKeyword''' to ''html/edit1.html''
 +
 
 +
When running the program you can focus the edit control and press {{keypress|F1}} to invoke the help. Under macOS the help key sequence is {{keypress|Cmd-?}} (or {{keypress|Cmd+Shift+?}} depending on your keyboard layout).
 +
 
 +
Note: Some window managers, widget set combinations do not pass {{keypress|F1}} to the LCL.
 +
 
 +
== INF (using fpGUI's DocView help viewer) ==
 +
See the message and example project included in the Lazarus Forums. [http://forum.lazarus.freepascal.org/index.php/topic,27864.msg173887.html#msg173887]
 +
 
 +
It shows a fully working example of an LCL application using [[fpGUI]]'s [http://fpgui.sourceforge.net/screenshots_apps.shtml DocView help viewer]. It shows context sensitive help and general help.
 +
 
 +
For example:
 +
* Set focus to a specific control and press {{keypress|F1}}. It will show the help topic for that specific control.
 +
* Click the Help button and it will show the help topic for the dialog/form.
 +
* Select the "Help -> Show Help" menu item and it will show the general application help and display the first topic in the help file.
 +
 
 +
== See also ==
  
When running the program you can focus the edit and press F1 to invoke the help. This does not work under OS X :-(
+
* [[Add an Apple Help Book to your macOS app]]
  
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]
 +
[[Category:Help and Docs]]
 +
[[Category:CHM]]

Latest revision as of 08:44, 10 March 2024

Deutsch (de) English (en) español (es) français (fr) русский (ru) 中文(中国大陆)‎ (zh_CN)

The LCL comes with a help system, and allows you to create help for your own applications.

Quick Start

Open the example in examples/helphtml/.

This project demonstrates how to use the HTML help components. Just drop them on a form of your project. Setup the paths and create some HTML pages. Then give each control of your application a HelpKeyword.

See the CHM help section if you want to use CHM help files instead of HTML help files.

There is a very nice simple demo (chmdemo.zip) here: http://forum.lazarus.freepascal.org/index.php/topic,38487.msg261731.html#msg261731

Help Basics

The LCL help mainly consists of two parts: Help databases and help viewers. A Help Database contains the mapping from the keywords (ID, node, message, pascal, ...) to the help page (or help web site or...). The Help Viewer is invoked by the Help Database to show the help to the user.

  • A THelpDatabase manages content. It can be a collection of HTML pages or fpdoc XML files or a CHM file or a database or whatever.
  • A THelpViewer is a component that shows help content. For example a viewer for the mime type text/html can start a web browser.

When help is requested, the LCL queries each registered THelpDatabase and each database can return a list of entries. If several entries are returned, the LCL asks the user to choose an entry. Then the LCL asks the database to show the help for the entry. The database extracts the help content and asks the LCL for a viewer that supports the mime type of the content. Finally, the viewer shows the help content.

CHM

Context-sensitive CHM application help can be used from Lazarus 1.0 and later.

A demonstration program is included that shows how to include context-sensitive help using CHM and the lhelp CHM viewer (the same one that is used for IDE help by default). Please see ${lazarusdir}/components/chmhelp/democontrol/.

You can write your own CHM files, e.g. with the now ancient Microsoft HTML Workshop or with the new Lazarus chmmaker tools in $(lazarusdir)/tools/chmmaker You can use a TCHMHelpDatabase control like the THTMLHelpDatabase control described below.

The advantages of using the CHM system are a smaller, self contained help file instead of multiple files. On the other hand, not every system has a CHM viewer installed by default, so you might want to include lhelp, a CHM viewer written in Pascal and included with the Lazarus sources (components/chmhelp/lhelp/lhelp.lpi).

Using LHelp

  • Drop a TCHMHelpDatabase on your form.
  • Set its FileName property to the path to the chm file, and set AutoRegister to true.
  • In KeywordPrefix specify the path to the html files contained in the chm file as seen from the chm root. Example: If the html help files during chm creation are in the subfolder html the KeywordPrefix is html (without trailing path delimiter!).
  • Put a TLHelpConnector on your form.
  • Set LHelpPath to the name and location of the LHelp executable (this can be absolute, or relative to the application directory)
  • Set AutoRegister to true.
// Example with both chm file and LHelp.exe in Application folder.
procedure TForm1.FormCreate(Sender: TObject);
begin
  if FileExists(ChangeFileExt(Application.ExeName, '.chm')) then
  begin
    CHMHelpDatabase1.Filename := ChangeFileExt(Application.ExeName, '.chm');
    CHMHelpDatabase1.KeywordPrefix := 'html';
    CHMHelpDatabase1.AutoRegister:=True;

    LHelpConnector1.LHelpPath := IncludeTrailingBackSlash(ExtractFileDir(Application.ExeName)) + 'lhelp.exe';
    LHelpConnector1.AutoRegister:=True;
  end
  else
    mnuHelpMain.Enabled := False;
end; 

procedure TForm1.Button1Click(Sender: TObject);
begin
  if mnuHelpMain.Enabled then  
    ShowHelpOrErrorForKeyword('', 'html/main.html');
    //ShowTableOfContents;  (Not implemented for TCHMHelpDatabase)
end;

When LHelp is invoked during execution of your project it is started by Inter-Process Communication (IPC) in a separate process which normally does not terminate when you application is closed. If you want to close LHelp with your application you should write an OnDestroy event handler to send an mrClose command to LHelp via IPC:

uses
  LHelpControl;  // for "mrClose"
     
procedure TForm1.FormDestroy(Sender: TObject);
begin
  if (LHelpConnector1.Connection <> nil) and LHelpConnector1.Connection.ServerRunning then
    LHelpConnector1.Connection.RunMiscCommand(LHelpControl.mrClose);
end;

HTML

The LCL provides two components to use HTML files for help: THTMLHelpDatabase and THTMLBrowserHelpViewer. To see the HTML help, see the lazarus example examples/helphtml/htmlhelp1.lpi.

Setup HTML help for your application

Lazarus help items

Adding HTML help to your application is easy:

  • Put a THTMLHelpDatabase on a form.
  • Set AutoRegister to true.
  • Set KeywordPrefix to html/. It means all keywords must start with the string html/.
  • Set BaseURL to file://yourhelp/. This will search for HTML files in the sub folder 'yourhelp' relative to the application directory. You can specify an absolute path to the directory where HTML files are stored. For UNIX-like platforms, use an URL like file:///usr/lib/yourhelp/ for local access or an URL like http://www.yoursite.com/ for web access. For the Windows platform, use an URL like file://c:/temp/html/ or file://c:\temp\html.
  • Put a THTMLBrowserHelpViewer on the form. This component can start the user's default browser.
  • Set AutoRegister to true.

Creating a help entry

  • Now create the subfolder yourhelp and create an HTML page yourhelp/edit1.html. In case of a website, the help page should be accessible as http://www.yoursite.com/edit1.html
  • Put a TEdit on a form
  • Set HelpType to htKeyword
  • Set HelpKeyword to html/edit1.html

When running the program you can focus the edit control and press F1 to invoke the help. Under macOS the help key sequence is Cmd-? (or Cmd+Shift+? depending on your keyboard layout).

Note: Some window managers, widget set combinations do not pass F1 to the LCL.

INF (using fpGUI's DocView help viewer)

See the message and example project included in the Lazarus Forums. [1]

It shows a fully working example of an LCL application using fpGUI's DocView help viewer. It shows context sensitive help and general help.

For example:

  • Set focus to a specific control and press F1. It will show the help topic for that specific control.
  • Click the Help button and it will show the help topic for the dialog/form.
  • Select the "Help -> Show Help" menu item and it will show the general application help and display the first topic in the help file.

See also