Defines base classes used in the LCL help system.

lazhelpintf.pas contains types, classes, and routines used in the LCL help system. It defines various base classes that provide the interface for the help system. Many of the methods in these classes are defined as abstract virtual methods, and must be implemented in more specialized descendent classes.

Author: Mattias Gaertner

Specifies the interface used get a help query as a String value.

AsString is an abstract virtual String function which specifies the interface used get a help query item as a String value. AsString must be implemented in a descendent class to perform the actions needed to convert the query item to a String value.

String representation for the help query item. Performs actions needed to compare the help query items.

IsEqual is a Boolean function used to compare help query items. IsEqual compares the current class instance to the item specified in QueryItem by calling the AsString method for each item. The return value is True when the string representation for the help query items are the same.

True when the help query items are the same. Help query item compared to the current class instance. Enumerated type with values representing Pascal help contexts. Context is a file name. Context is a file name for a unit or library. Context is a property. Context is a procedure or function. Context is a list of parameters. Context is a variable. Context is a type. Context is a constant. Record type used to represent a Pascal help context and its descriptor. TPascalHelpContextType for the record. String representing the Pascal context. Pointer used to reference a TPascalHelpContextType instance. Implements a list for Pascal help contexts.

TPascalHelpContextList is a THelpQueryItem descendant used to access and maintain a list of Pascal help contexts. TPascalHelpContextList provides methods used to add, insert, and compare Pascal help contexts in the list. Properties are provided to determine the number of items in the list, and to access individual TPascalHelpContext instances in the list.

Adds a Pascal help context to the end of list in Items. Pascal help context added in the method. Inserts a Pascal help context at the specified position in Items. Ordinal position in Items where the context is stored. Pascal context inserted into the Items for the list. Clears the Items in the list of Pascal help contexts.

Clear is a procedure used to clear the list of TPascalHelpContext instances in the Items for the list. Clear iterates over the positions in Items, and sets the Context string for each item to an empty string (''). This allows the record instance to be finalized. Clear calls ReAllocMem to sets the length of the Items property to 0 (zero).

Destructor for the class instance.

Destroy is the overridden destructor for the class instance. Destroy calls the Clear method to remove Pascal help contexts stored in the Items for the List. Destroy calls the inherited constructor to finalize the class instance.

Indicates if the list is equivalent to the specified list of help contexts.

IsEqual is a Boolean function which indicates if the current list is equivalent to the list of help contexts specified in QueryItem. The return value is True when QueryItem is a TPascalHelpContextList instance which contains the same context items as the current instance.

IsEqual calls the CompareList method to examine and compare the context items in QueryItem.

True the lists are equivalent. List of help contexts compared in the method. Compares the specified list of help contexts to the current instance. Returns 0 when lists are the same. List of help contexts compared to the current instance. Gets the string representation for help contexts in Items. Indicates the number of help contexts stored in Items. Provides indexed access to help contexts in the List by ordinal position. Ordinal position for the help context. Pointer to the initial help context stored in the list. Enumerated type that identifies the method(s) available to locate a help topic.

THelpNodeType is an enumerated type which identifies the method(s) available to locate a topic in a help database. A help topic can be accessed buy ID (unique identifier), Help Context, or its URL (depending the content type for the help database). Each value inTHelpNodeType indicates the combination of access methods available for the help node.

THelpNodeType is the type used for the THelpNode.HelpType property. The value in HelpType is set based on the constructor used to create the help node class instance.

URL, ID, and Context are valid for the help node. Only the URL is valid for the help node. URL and ID are valid for the help node. Only ID is valid for the help node. Only Context is valid for the help node. URL and Context are valid for the help node. . Constructor for the class instance. Help database that owns the help node. Help node with property values stored in the new help node; basically, it is a copy Constructor. Title for the help node. URL for the help node. Unique identifier for the help node. Context for the help node. Alternate constructor using the URL for the help node. Help database that owns the help node. Title for the help node. URL for the help node. Alternate constructor using the ID for the help node. Help database that owns the help node. Title for the help node. Unique ID for the help node. Alternate constructor using the URL and ID for the help node. Help database that owns the help node. Title for the help node. URL for the help node. Unique ID for the help node. Alternate constructor using the Context for the help node. Help database that owns the help node. Title for the help node. Context for the help node. Alternate constructor using the URL and Context for the help node. Help database that owns the help node. Title for the help node. URL for the help node. Context for the help node. Help database that owns the help node. Indicates if the URL for the help node is valid. True if the URL was provided to the constructor for the help node. Indicates if the unique identifier is valid for the help node. True if the ID was provided to the constructor for the help node. Indicates if the help context is valid for the help node. True if the help context was provided to the constructor for the help node. Gets the string representation for the help node. Contains the value in the Title property. Assigns values from Source to the current class instance. Help node with values stored in the current class instance. Title for the help node. Type for the help node. URL used to access content for the help node. Unique identifier for the help node in a help database. Help context for the help node. Constructor for the class instance. Constructor for the class instance. Destructor for the class instance. Indicates the number of entries stored in the Items property. Number of entries stored in the Items property. Adds the specified help node, node query, and query item to the Items in the list. Deletes the help node query at the specified ordinal position in the list. Ordinal position removed in the method. Gets the ordinal position in the list where the specified node and query items are stored. Removes all items stored in the list. Provides indexed access to help nodes and query selectors by their ordinal position. Ordinal position for the requested item. Constructor for the class instance. Help node for the new item. Destructor for the class instance. Help node for the item. Sets the value for the Filename property. New value for the property. Constructor for the class instance. Help node for the new item. File name for the new item. Indicates if the specified file name matches the value in the Filename property. True when the file name matches the Filename property. File name compared to the current class instance. Gets the value for the BasePath needed to access the file. Value for the BasePath for the file. Represents the BasePath used to access the source file. Constructor for the class instance. Help node for the new item. File name for the new item. File mask used to select files displayed in the directory. Indicates if subdirectories are visited when accessing the directory. Provides support for integrating a collection of related help topics with a table of contents. Sets the value for the AutoRegister property. New value for the property. Sets the value in the ID property. New value for the property. Sets the value in the Databases property. New value for the property. Sets the value in the SupportedMimeTypes property. List of MIME types stored in the property. Adds a MIME type entry to the list in SupportedMimeTypes. MIME type added in the method. Constructor for the class instance. TComponent.Create Owner of the class instance. Destructor for the class instance. Increments the number of references for the class instance. Ensures that the LCL Help system has been initialized.

Calls CreateLCLHelpSystem if HelpDatabases has not been assigned. HelpDatabases, HelpManager, and HelpViewers are initialized when the LCL Help system is set up in the Lazarus IDE.

Sets Databases to the value in HelpDatabases.

Called when a new value is assigned to the ID or AutoRegister properties. Called when is created and added to THelpDatabases in its CreateHelpDatabase method.

Raises an EHelpSystemException exception when Databases already contains a registered LCL Help Database. Decrements the internal reference count for the help database` Indicates if the list of help databases has been initialized for the database instance. Determines if a Table of Contents node is available for the help database. Displays the Table of Contents in the TOCNode for the help database. Displays an error message using the help manager, or raises an exception. Displays a help topic with the specified file name. Determines is the specified MIME type is supported in the help database. True when the MIME type is in the list of supported MIME types. MIME type to locate in the list of supported MIME types. Creates or updates a list of help nodes using the specified help HelpKeyword. Status for help request. Help keyword to locate in nodes in the help database. List of nodes updated in the method. Message describing an error condition in the return value. Creates or updates the list of help nodes for the specified help context. Creates or updates a list of nodes for the specified Pascal help GetNodesForPascalContexts. Creates or updates a list of help nodes for the specified class. Creates or updates a list of help nodes matching the specified message. Gets the help viewer which supports the specified MIME type. Adds the specified item to the search items for the help database. Adds a search item to the help database for the specified help node. Adds a search item to the help database for the source file with the specified file name. Removes the specified item from the search items for the help database. Gets the number of registered search items for the help database. Used to load configuration settings for the help database. It is an empty implementation in THelpDatabase. Must be implemented in a descendant class. Used to save configuration settings for the help database. It is an empty implementation in THelpDatabase. Must be implemented in a descendant class. Gets the localized name (ID) for the help database. Help databases registered for use with the LCL help manager. Unique identifier for the hep database. Contains the list of MIME types supported in the help database. Represents the base path for the help database. Help node with the Table of Contents for the help database. Indicates if the help database is automatically registered at run-time. Event handler signalled to locate the viewer for the help database. Class reference for the THelpDatabase type. Implements support for accessing and maintaining registered help database classes in the help system. List with registered help database instances. List with class references for each registered help database. Gets a value in the Items property by its ordinal position. Value for the indexed property. Ordinal position for the indexed property value. Performs actions needed to register the specified help database.

DoRegisterDatabase is a procedure used to perform actions needed to register the help database specified in ADatabase. The Reference method in ADatabase is called to increment the reference count for the help database.

DoRegisterDatabase ensures that the Items property contains a valid TFPList class instance, and adds the THelpDatabase instance in ADatabase to the Items property.

Help database registered in the method. Constructor for the class instance. Destructor for the class instance. \Gets the number of registered help database instances in the Items property. Provides indexed access to registered help database instances. Ordinal position for the help database instance. Gets the help database with the specified unique identifier. The registered help database instance, or Nil when ID is not found. Unique identifier to locate in Items. Gets the help database instance with the specified ID. Gets the ordinal position in Items for the help database with the specified ID. Creates a unique identifier for a help database using a suggested identifier prefix. Creates and optionally registers a unique help database instance using the specified class reference. Displays the Table of Contents.

ShowTableOfContents is not implemented in THelpDatabases. The return value is always shrHelpNotFound, and ErrMsg is set to the value 'THelpDatabases.ShowTableOfContents not implemented'.

Displays an error dialog for status result codes other than shrSuccess and shrCancel.

ShowError calls the MessageDlg routine to display an error dialog for status result codes other than shrSuccess and shrCancel. ShowError uses the value in ShowResult to determine the caption displayed on the message dialog, including:

	Status code	Caption for the Dialog
shrNone	rsHelpError
shrDatabaseNotFound	rsHelpDatabaseNotFound
shrContextNotFound	rsHelpContextNotFound
shrViewerNotFound	rsHelpViewerNotFound
shrHelpNotFound	rsHelpNotFound
shrViewerError	rsHelpViewerError
shrSelectorError	rsHelpSelectorError
Default for status codes other than shrSuccess and shrCancel	rsUnknownErrorPleaseReportThisBug

A message dialog is not displayed when ShowResult contains the value shrSuccess or shrCancel.

ShowError is used in the implementation of the THelpDatabase.ShowError method.

Status result code examined in the method. Message displayed for the error condition. Gets a URL representing the base path object for the help databases. Gets the directory for the base path object in the help databases. Finds the registered help viewer for the specified MIME type. Used to substitute macros. Always returns True in THelpDatabases. Displays help for nodes matching the specified query list. Displays help for the specified THelpQuery. Displays help nodes matching the specified help query context. Displays help nodes matching the specified keyword help query. Displays help nodes matching the specified Pascal help query. Displays help for the Pascal source contexts in the help query. Always returns shrHelpNotFound with the error message 'THelpDatabases.ShowHelpForPascalSource not implemented'. Displays the requested help file in the help viewer. Displays the help topic for the requested URL in the help viewer. Populates a list with help nodes using the specified help keyword. Populates a list with help node for the specified help context. Loads configuration settings for each registered help database in the container. Configuration storage with values loaded in the method. Saves configuration settings for each register help database in the container. Configuration storage updated in the method. Base class for help viewers used in the LCL help system.

THelpViewer is a TComponent descendant that provides the interface used for help viewers in the LCL help system. THelpViewer provides properties and methods used to access and display help topics using their corresponding help nodes, including a Table of Contents. Most methods are declared as virtual and should be overridden in descendent class that handle specific MIME types.

Methods are provided to register and unregister the help viewer for a specific MIME type. The AutoRegister property controls whether the viewer is automatically registered at run-time.

Use classes like TCHMHelpViewer, THTMLHelpViewer, THTMLBrowserHelpViewer, and THelpConnector for help databases that use the specific MIME types for the respective classes.

THTMLBrowserHelpViewer Sets the value in the AutoRegister property. New value for the property. Sets the value in the SupportedMimeTypes property. List with value used in the property. Adds the specified MIME type to the SupportedMimeTypes property. MIME type added in the method. Constructor for the class instance. Owner of the class instance. Destructor for the class instance. Indicates if the help viewer can display a table of contents for the specified help node. Displays the table of contents for the specified help node. Indicates if the specified MIME type exists in the SupportedMimeTypes property. Displays the help topic for the specified help node. Hides the help viewer. Must be implemented in a descendent class. Assigns property values from the specified source to the current class instance. Loads configuration settings for the help viewer from the specified storage. Must be implemented in a descendent class. Saves configuration settings to the specified storage. Must be implemented in a descendent class. Gets the localized name for the help viewer. Registers the help viewer for use in the LCL help system. Unregisters the help viewer in the LCL help system. Contains MIME types supported in the help viewer. Contains a help message describing how parameters are used in the help viewer. Indicates the storage used for configuration settings in the help viewer. Indicates if the help viewer is automatically registered at run-time. Class reference used to create instances of the help viewer. Used to access and maintain registered help viewers for the LCL help system. Indicates if the class is being freed. Help viewer at the specified ordinal position. Ordinal position in the list for a help viewer. Constructor for the class instance. Destructor for the class instance. Frees all help viewers in the Items property. Indicates the number of registered help viewers in the Items property. Number of help viewers in the list. Populates a list with help viewers that support the specified MIME type. Adds a help viewer to the list of registered viewers in Items. Help viewer added in the method. Unregisters the specified help viewer and removes it from the Items property. Loads configuration settings from the specified storage for each registered help viewer. Saves configuration settings to the specified storage for each registered help viewer. Gets the ordinal position for the specified help viewer in the Items property. List with the registered help viewers for the LCL help system. Stores the base file path for help databases.

THelpBasePathObject is a TPersistent descendant used to represent the base file path for topics in help databases. It is used in the implementation of the THelpDatabases.GetBaseDirectoryForBasePathObject method.

Sets the value for the BasePath property. New value for the property. Constructor for the class instance. Initial value for the BasePath property. Represents the base file path for topics in a help database. Stores the base URL for topics in help databases. Sets the value in the BaseURL property. New value for the property. Constructor for the class instance. Initial value for the BaseURL property. Represents the base URL for topics in a help database. Contains the list of registered help databases used in the Lazarus IDE. Contains the list of registered help viewers used in the Lazarus IDE. Ensures the HelpDatabases and HelpViewers variables are initialized for use in the LCL help system. Frees the HelpDatabases and HelpViewers used in the LCL help system. Frees unreferenced Help databases and viewers in the LCL help system.

FreeUnusedLCLHelpSystem is a procedure used to free unreferenced Help databases and viewers in the LCL help system. No actions performed in the method when HelpViewers and HelpDatabases are assigned and contain valid class references.

FreeUnusedLCLHelpSystem calls FreeLCLHelpSystem to free and release the HelpViewers, HelpDatabases, and HelpManager instances.

FreeUnusedLCLHelpSystem is called when a THelpDatabase instance calls its UnregisterSelf method.

Gets the URL with file path information for the specified file name.

FilenameToURL is a String function used to get the URL value for the specified file name. FilenameToURL calls FilenameToURLPath to get the file path information needed for the URL. The value 'file://' is prepended to the return value to indicate that the file URL scheme is used in the URL.

URL for the specified file name. File name converted to a URL in the function. Separates a URL into its scheme, path, and parameter component values.

SplitURL is a procedure used to separate the value specified in URL into the URLScheme, URLPath, and URLParams output parameters. The default value for these output parameters is an empty string (''), and indicates that the component value is not present in URL.

URLScheme will contain the URL scheme found in URL, and normally contains values like 'file', 'http', or 'https'. It does not contain the '://' characters which mark the end of the URL scheme.

URLPath contains file path information found in URL. It does not include any portion of URL occurring after the initial '?' or '#' character used in parameter values. Those values are stored in the URLParams argument.

URL examined in the function. URL scheme used in the URL. File path information from the URL. Parameters found in the URL. Builds a URL using the specified scheme, path, and parameter values.

CombineURL is a String function used to build a URL using the specified parameter values.

URLScheme contains the name of scheme used in the URL, like 'file', 'http', or 'https'. It should not include the characters '://'; these are appended to URLScheme just prior to URLPath in the function.

When assigned, values in URLParams are included at the end of the return value.

URL for the specified values. URL scheme to use in the URL. Path to the file used in the URL. Parameter values for the URL. Indicates if the specified URL contains an absolute file path.

URLFilenameIsAbsolute is a Boolean function used to determine if the URL specified in URLPath represents an absolute file. URLFilenameIsAbsolute calls URLPathToFilename to get the file name used in the URL. The return value is determined by calling FilenameIsAbsolute for the file name. The return value is True when the path to the file does not require resolution of "." or ".." relative path markers.

True when the URL does not have relative file path information. URL examined in the function. Gets the position in the URL where the file path is located. Position where the file path begins, or -1 if not found. URL examined in the routine. Gets the position in the URL for the final character in the file path. URL examined in the routine. Removes URL parameters from the specified URL. URL with any parameters removed. URL examined in the routine. Gets the path information from the specified URL. File path information from the URL. URL examined in the routine. Gets directories in the file path for the specified URL. File path information up to and including the final path delimiter. URL examined in the routine. Removes leading or trailing spaces in the file path for the specified URL. URL examined in the routine. Removes leading and trailing whitespace in the file path for the specified URL.

TrimURLPath is a String function used to remove leading and trailing whitespace that occurs in the file path specified in URLPath. TrimURLPath converts the file path to a file name on the local file system, removes whitespace, and reconverts the file name to a valid URL file path.

TrimURLPath calls URLPathToFilename to get the file name portion of the URL, and calls TrimFilename to remove leading and trailing whitespace. TrimURLPath calls FilenameToURLPath to get the return value for the function.

File path for the URL after removing whitespace. URL examined in the routine. Determines if the specified URL uses the 'file:' URL scheme. True when 'file:' is included in the URL. URL examined in the routine. Includes a trailing path delimiter in the file path for the specified URL. URL path information including the trailing path delimiter. URL path information examined in the routine. Ensures that a TList has been created before adding the specified object instance. Object instance added in the routine. List instance created or updated in the routine. Indicates if the object is added only when it does not already exist in the list. Ensures the THelpNodeQueryList instance has been created prior to adding the specified help query item. Help node to locate in the list of query items. Query item for the help node. List examined in the routine. Indicates if the help node and query item are added only when they do not already exist in the list.