Contains types and classes used to integrate and access help files in HTML format.

lazhelphtml.pas contains types and classes used to integrate and access help files in HTML format (.htm or .html file extensions). It registers THTMLHelpDatabase and THTMLBrowserHelpViewer components on the System tab in the Lazarus IDE component palette.

Provides support for context-sensitive help using HTML help files.

THTMLHelpDatabase is a THelpDatabase descendant that provides support for using HTML files as context-sensitive help displayed when the F1 key is pressed in an application. THTMLHelpDatabase extends the ancestor class to include properties and methods needed to associate Help Keywords to specific HTML files, and to retrieve and display the help content.

The KeywordPrefix property determines the keywords that can be accessed in the help database. BaseURL determines the path searched when accessing HTML files for the help database.

An application can create a THTMLHelpDatabase instance, assign the KeywordPrefix and BaseURL for the help database, and use AutoRegistered to enable the help database. Controls on the Form should use the value htKeyword in their HelpType property, and their HelpKeyword property must be set to a value that includes the KeyWordPrefix and the HTML file name accessed for the control.

THTMLBrowserHelpViewer is a companion component that allows the correct HTML help file to be displayed for the keyword/url in a web browser when the F1 key is pressed.

There is an example program that demonstrates usage of the components in the examples/helphtml directory for the Lazarus installation.

Stores the base URL for files using the keyword prefix. URL used when BaseURL is empty. The prefix used for keyword help in the help database. Node in the help file for entries having the keyword prefix. Indicates if the value in BaseURL is stored for the help database.

IsBaseURLStored is a Boolean function used to determine if the value in BaseURL is stored for the help database class instance. The return value is True when the values in BaseURL and DefaultBaseURL are not the same.

True when the property value is stored. Sets the value in the BaseURL property. New value for the BaseURL property. Sets the value for the DefaultBaseURL property. New value for the property. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited method using the value in TheOwner as the owner of the class instance. Create calls AddSupportedMimeType to ensure that the 'text/html' MIME type is included the MIME types used for files in the HTML database.

Use Free to destroy instances of the HTML help database.

Owner of the class instance. Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy ensures that the THelpNode used in KeyWordPrefix is freed. Destroy calls the inherited destructor to free the HTML help database instance.

THelpNode Displays a help viewer for the specified HTML help topic.

ShowURL is a TShowHelpResult function used to display the HTML help topic for the specified URL. ShowURL gets the help viewer registered for the 'text/html' MIME type, resolves the URL to an absolute path ( if needed), and displays the corresponding help node in the viewer.

URL contains the URL protocol, path and file information, and optional URL parameters. For example: 'file://myapp/myform.html'.

Title contains the value displayed in the title bar for the help viewer.

The return value indicates the status of the requested operation, and contains the value shrSuccess when the HTML help viewer successfully displays the topic for the help context. One of the following enumeration values from TShowHelpResult may be returned under certain circumstances:

shrViewerNotFound: A help viewer was not found for the HTML help MIME type.
shrViewerError: An error occurred while displaying the help topic in the help viewer.
shrContextNotFound: The value in URL contains file path information not located on the local file system.

The ErrMsg parameter is a variable argument updated to contain specific information about return values other than shrSuccess.

Status of the help display operation. Identifies the path, file, and topic information displayed in the method. Value displayed in the title bar of the help viewer. Message which describes the error condition in the return value. Displays a context-sensitive HTML help topics in the HTML database.

ShowHelp is a TShowHelpResult function used to display context-sensitive HTML help topics in the HTML database. The return value indicates the status for the topic display request. It contains the value shrContextNotFound if the requested help node does not represent a valid URL for the HTML help database.

ErrMsg is a variable parameter which is updated to contain details for an error condition in the request.

ShowHelp calls the ShowURL method using the URL and Title from the NewNode parameter.

Please note that the Query, BaseNode, and QueryItem parameters are not used in the method.

Status of the help display request. Not used in the method implementation. Not used in the method implementation. Help node with the URL and Title displayed in the method. Not used in the method implementation. Message which describes an error condition in the return value. Populates the list with help nodes using the KeywordPrefix for the HTML help database.

GetNodesForKeyword is an overridden TShowHelpResult function used to populate the ListOfNotes parameter with the help nodes using the specified help keyword.

HelpKeyword contains the help keyword to locate in nodes for the HTML help database.

ListOfNodes is a THelpNodeQueryList instance which is populated in the method.

ErrMsg describes any error condition for the return value in the method.

GetNodesForKeyword calls the inherited method using the values in HelpKeyword, ListOfNodes, and ErrMsg as arguments. The return value is set to the TShowHelpResult enumeration value returned from the inherited method. No additional actions are performed in the method when the return value is not shrSuccess.

GetNodesForKeyword ensures that a THelpNode is included in ListOfNodes for the default topic matching the KeywordPrefix used in the HTML help database. GetNodesForKeyword calls CreateNodeQueryListAndAdd to populate the help nodes starting with the node for the Keyword prefix.

Please note that the list of node is populated at run-time only; the list is not populated at design-time.

Status of the help display request. Help keyword to locate in the HTML help database. List used to store help nodes matching the keyword prefix and keyword value. Describes an error condition encountered in the help display requested. Gets the effective Base URL used to access a topic in the HTML help database.

GetEffectiveBaseURL is a String function used to get the effective value for the BaseURL needed to access a topic in the HTML help database.

When BaseURL is not an empty string (''), it is used to construct the URL path for its file name. When multiple HTML help databases have been registered, the help manager calls its GetBaseURLForBasePathObject method to derive the URL for the base path. Otherwise, the value in DefaultBaseURL is used construct the URL for the help topic file name.

GetEffectiveBaseURL ensures that a trailing path delimiter is appended to the URL in the return value.

GetEffectiveBaseURL is used in the implementation of the ShowURL method.

THelpDatabases THelpManager Derived value for the URL needed to access the HTML help topic. Loads HTML help database settings from the specified configuration storage.

Load is an overridden procedure in THTMLHelpDatabase, and calls the inherited method. Load ensures that the value for the BaseURL setting in Storage is used as the value for the BaseURL property. If the setting does not exist in Storage, the value from DefaultBaseURL is used in BaseURL.

Use Save to store the value from BaseURL to the configuration storage.

Configuration storage with values loaded in the method. Saves configuration settings to the specified storage. Storage for the configuration settings. Default value for the BaseURL used in the HTML help database. BaseURL for the HTML help database. Indicates if the HTML help database is automatically registered at run-time.

AutoRegister is a published Boolean property which indicates if the HTML help database is automatically registered at run-time. Changing the value in AutoRegister causes the RegisterSelf or UnregisterSelf methods to be called. RegisterSelf is called when the property is True; otherwise UnregisterSelf is called.

Common prefix which identifies the related keyword topics handled in the HTML help database.

KeywordPrefix is a String property which identifies the related keyword topics handled in this instance of the HTML help database. KeywordPrefix is used in the GetNodesForKeyword method to select help topics using a specific Keyword. It also allows the path to help files using the keyword prefix to be determined using the BaseURL for the help topic.

Specifies an event handler signalled to get the browser application name and parameters.

TOnFindDefaultBrowser is an object procedure which defines the event handler signalled to find a help browser for HTML help topics. Applications can implement an object procedure using this signature to assign values to the DefaultBrowser and Params arguments. TOnFindDefaultBrowser is the type used to implement the OnFindDefaultBrowser event handler in THTMLBrowserHelpViewer.

Path to the default browser application used for HTML help topics. Command line parameters for the browser application needed to open and display the HTML help topic. Implements a browser/viewer for HTML help topics.

THTMLBrowserHelpViewer is a THelpViewer descendant which extends the ancestor class to display HTML help topics in a web browser application. Properties and methods are provided to perform the following types of operations:

Register the viewer for use documents using the '' MIME type
Get the browser and command line parameters used to display HTML help topics
Display a node in the HTML help document
Load and save configuration settings for the HTML help viewer

THelpViewer Sets the value in the BrowserParams property. New value for the property. Sets the value in the BrowserPath property. New value for the property. Constructor for the class instance.

Create is the overridden constructor for the class instance. Create calls the inherited constructor using the value in TheOwner as the owner for the class instance.

Create ensures that the 'text/html' MIME type is included in the MIME types supported in the HTML help viewer. Create also sets the default value for the BrowserParams property to '%s'. The value in the ParameterHelp property is set to the constant hhsHelpTheMacroSInBrowserParamsWillBeReplacedByTheURL.

THelpViewer.ParameterHelp Owner of the class instance. Displays the help node for a HTML help topic.

ShowNode is an overridden TShowHelpResult function used to display the help node for a HTML help topic. The return value is one of the values from the TShowHelpResult enumeration.

Node contains the THelpNode displayed in the method.

ErrMsg is a variable parameter updated to describe an error condition occurring in the return value for the method, or an empty string when an error condition is not encountered.

When Node contains an invalid URL, the value in ErrMsg is set to 'THTMLBrowserHelpViewer.ShowNode Node.URLValid=false'. If Node has an empty URL, ErrMsg is set to the value 'THTMLBrowserHelpViewer.ShowNode Node.URL empty'. ErrMsg may contain a constant value for other specific error conditions, such as:

hhsHelpNoHTMLBrowserFoundPleaseDefineOne
hhsHelpNoHTMLBrowserFound
hhsHelpBrowserNotFound
hhsHelpBrowserNotExecutable
hhsHelpErrorWhileExecuting

ShowNode uses the value in BrowserPath as the executable for the HTML help viewer. BrowserParams is used as the arguments passed to the executable. When BrowserPath is unassigned, the FindDefaultBrowser method is called to update the executable and parameters used in the help viewer. For the Windows platform, the executable may contain a quoted value; the quotes are removed before the FileExistsUf8 and FileIsExecutable methods are called to verify the executable file name.

ShowNode ensures that a '%s' macro marker in BrowserParams is updated with the URL for the help node in Node.

ShowNode creates a TProcessUTF8 instance that is used to execute the browser application with the required browser parameters. The process does not inherit standard handles for input, output or errors. The process is freed when execution has been completed.

The return value is set to shrSuccess when the HTML help topic has been successfully displayed in the help browser. An exception that occurs during execution of the browser process is handled in the method. ErrMsg is updated to reflect the exception message, and the return value is set shrViewerError.

ShowNode is used in the implementation of the ShowURL method.

Status code for the requested operation. Help node displayed in the method. Message describing an error condition in the return value. Locates the default browser application used for HTML help topics. Browser application used for the HTML help viewer. Parameters needed for the browser application. Stores property values from the specified help browser to the current class instance. Help browser with properties stored in the current class instance. Loads configuration settings for the help viewer from the specified storage. Storage for the configuration settings. Save configuration settings for the help viewer to the specified storage. Storage for the configuration settings. Gets the localized name for the HTML help browser/viewer application. Value for the localized name of the application. Event handler signalled to find the default browser for the help viewer.

OnFindDefaultBrowser is a TOnFindDefaultBrowser property that represents the event handler to find the default browser for the help viewer.

Path to the browser application used to view a HTML help topic.

BrowserPath is a String property that contains the path on the local file system for the browser application executable used to view HTML help topics. For example:


  AViewer.BrowserPath := '/usr/bin/mozilla';  // or
  AViewer.BrowserPath := ''"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe "'';

When BrowserPath contains an empty string (''), the FindDefaultBrowser method is used to get the value for the property. The method uses the OnFindDefaultBrowser event handler when assigned, or the value in the DefaultBrowser property.

BrowserPath is updated/used during execution of the ShowNode method.

Use BrowserParams to access the arguments passed on the command line to the browser application in BrowserPath.

Parameters passed to the browser application to display a HTML help topic.

BrowserParams is a String property used to specify arguments passed on the command line to the browser application. The arguments identify the URL and any optional command line switches needed for the executable in BrowserPath. BrowserParams uses the '%s' notation to represent a macro that is substituted with the URL for the Help topic when it is displayed. The value in BrowserParams can be overridden, but should always include '%s' to allow insertion of the URL for the help topic.

BrowserParams is updated/used when the HTML help topic is displayed in the ShowNode method. When BrowserParams contains an empty string (''), the value in DefaultBrowserParams is used.

Use BrowserPath to access the browser application used to view HTML help topics. Use the OnFindDefaultBrowser event handler to perform conditional browser path and parameter assignment based on user-defined criteria.

Indicates if the help viewer is automatically registered in the Lazarus Help system.

AutoRegister is a published Boolean property in THTMLBrowserHelpViewer. AutoRegister determines whether the RegisterSelf or UnregisterSelf method for the help viewer is called at run-time. RegisterSelf is called when AutoRegister contains True; otherwise UnregisterSelf is called.

THelpViewer THelpViewer.AutoRegister THelpViewer.RegisterSelf THelpViewer.UnregisterSelf Registers database and viewer components for HTML help on the System tab in Lazarus.