lazarus/docs/xml/lazutils/lazconfigstorage.xml

923 lines
21 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
LazConfigStorage
====================================================================
-->
<module name="LazConfigStorage">
<short>
Defines various base classes for loading and saving configuration files.
</short>
<descr>
<p>
This file is part of the <file>LazUtils</file> package.
</p>
<p>
Author: Mattias Gaertner
</p>
</descr>
<!-- unresolved external references -->
<element name="Classes"/>
<element name="SysUtils"/>
<element name="typinfo"/>
<element name="Laz_AVL_Tree"/>
<element name="LazLoggerBase"/>
<element name="AvgLvlTree"/>
<element name="TConfigStorage">
<short>
Defines the base class for a configuration storage mechanism.
</short>
<descr>
<p>
<var>TConfigStorage</var> is a class used to create and maintain
configuration information using an XML-based storage format. TConfigStorage
is a base class; it contains abstract virtual methods which must be
implemented in descendent class to provide memory- or file-based storage for
its values.
</p>
<p>
TConfigStorage and descendent classes have a base path where its data is
stored, and sub-paths and values for the data items in the storage. Path
information uses an XPath-like notation which indicates where a given value
is stored, and the name associated with the stored value.
</p>
<p>
For example:
</p>
<code>
'path/to/loginform'
'path/to/loginform/top'
'path/to/loginform/left'
'path/to/loginform/width'
'path/to/loginform/height'
</code>
<p>
Values can be specified using one of the native Pascal data types supported
in the class, like:
</p>
<ul>
<li>String</li>
<li>Integer</li>
<li>Boolean</li>
<li>TStrings</li>
<li>TRect</li>
<li>TPoint</li>
<li>TPersistent</li>
</ul>
<p>
Methods are provided to get, set, or delete stored items using their path
notation. Methods are also provided to read or write published property values to or from persistent objects using RTTI.
</p>
<p>
Do not create instances of TConfigStorage. Use of the descendent classes like
TConfigMemStorage or TXMLConfigStorage.
</p>
</descr>
<seealso>
<link id="TConfigMemStorage"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>
<element name="TConfigStorage.FPathStack">
<short>Contains a path history built using AppendBasePath.</short>
</element>
<element name="TConfigStorage.FCurrentBasePath">
<short>Member used to store the value in CurrentBasePath.</short>
</element>
<element name="TConfigStorage.GetFullPathValue">
<short>
Specifies a method used to get a value or its default from the specified fully-qualified path.
</short>
<descr>
<p>
Returns the value stored using the path and name in the APath argument. The
value in ADefault is returned if APath is not found in the configuration
storage. The overloaded variants allow the return and default values to be
specified using String, Integer, or Boolean types.
</p>
<p>
GetFullPathValue is an abstract virtual method in TConfigStorage. It is
implemented in a descendent class to use the storage mechanism for the class
instance.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.GetFullPathValue.Result">
<short>
Value in the configuration storage for the specified value type.
</short>
</element>
<element name="TConfigStorage.GetFullPathValue.APath">
<short>
Fully-qualified path to the value. Includes both the base path and the name for the item.
</short>
</element>
<element name="TConfigStorage.GetFullPathValue.ADefault">
<short>
Default value returned when APath is not found in the configuration storage.
</short>
</element>
<element name="TConfigStorage.SetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetFullPathValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetFullPathValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.DefValue">
<short/>
</element>
<element name="TConfigStorage.DeleteFullPath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeleteFullPath.APath">
<short/>
</element>
<element name="TConfigStorage.DeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigStorage.WriteProperty">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.WriteProperty.Path">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.Instance">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.PropInfo">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.DefInstance">
<short/>
</element>
<element name="TConfigStorage.WriteProperty.OnlyProperty">
<short/>
</element>
<element name="TConfigStorage.ReadProperty">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ReadProperty.Path">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.Instance">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.PropInfo">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.DefInstance">
<short/>
</element>
<element name="TConfigStorage.ReadProperty.OnlyProperty">
<short/>
</element>
<element name="TConfigStorage.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<remark>
Create has an empty implementation in TConfigStorage. Use one of the
descendent classes which re-implements the constructor as needed for its
storage mechanism.
</remark>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.Create.Filename">
<short>File name where configuration data is stored.</short>
</element>
<element name="TConfigStorage.Create.LoadFromDisk">
<short>
<b>True</b> to load values from the specified file if it exists. <b>False</b>
to create a new, empty storage.
</short>
</element>
<element name="TConfigStorage.Destroy">
<short>Destructor for the class instance.</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It
frees resources allocated for members in the class instance, and calls the
inherited destructor.
</p>
</descr>
<seealso>
<link id="#rtl.system.TObject.Destroy">TObject.Destroy</link>
</seealso>
</element>
<element name="TConfigStorage.Clear">
<short>
Clears the content in the configuration storage.
</short>
<descr>
<p>
<var>Clear</var> is an abstract virtual method in TConfigStorage. It is
implemented in descendent classes to provide a file- or memory-based
storage mechanism.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.GetValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.GetValue.Result">
<short/>
</element>
<element name="TConfigStorage.GetValue.APath">
<short/>
</element>
<element name="TConfigStorage.GetValue.ADefault">
<short/>
</element>
<element name="TConfigStorage.GetValue.ARect">
<short/>
</element>
<element name="TConfigStorage.GetValue.APoint">
<short/>
</element>
<element name="TConfigStorage.GetValue.List">
<short/>
</element>
<element name="TConfigStorage.SetValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.SetDeleteValue.APath">
<short/>
</element>
<element name="TConfigStorage.SetDeleteValue.AValue">
<short/>
</element>
<element name="TConfigStorage.SetDeleteValue.DefValue">
<short/>
</element>
<element name="TConfigStorage.DeletePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeletePath.APath">
<short/>
</element>
<element name="TConfigStorage.DeleteValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.DeleteValue.APath">
<short/>
</element>
<element name="TConfigStorage.CurrentBasePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ExtendPath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ExtendPath.Result">
<short/>
</element>
<element name="TConfigStorage.ExtendPath.APath">
<short/>
</element>
<element name="TConfigStorage.AppendBasePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.AppendBasePath.Path">
<short/>
</element>
<element name="TConfigStorage.UndoAppendBasePath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.WriteToDisk">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.GetFilename">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.GetFilename.Result">
<short/>
</element>
<element name="TConfigStorage.WriteObject">
<short>
Stores property names and values in the specified object to the configuration
storage.
</short>
<descr>
<p>
<var>WriteObject</var> is a method used to store names and values from the
properties in the specified persistent object into the configuration storage.
</p>
<p>
<var>Path</var> contains the location in configuration storage where the
property values are stored. It provides a unique location for the values
stored in the method.
</p>
<p>
<var>Obj</var> is the <var>TPersistent</var> instance with the property
values stored in the method.
</p>
<p>
WriteObject calls <var>WriteProperty</var> for each of the properties
returned from the RTL <var>GetPropList</var> routine. Sub-paths representing
each of the published properties in the object are created by calling the
WriteProperty method.
</p>
<p>
WriteObject (and WriteProperty) rely on RTTI types and routines to get the
values from the persistent object. As such, only published properties can be
serialized; the FPC RTL does not provide RTTI type information for other
protected or public visibility at this time. The properties must have getter and setter routines (read and write specifiers); otherwise, they are omitted from the serialized values.
</p>
<p>
Use the <var>OnlyProperty</var> argument to specify the name for a single
property in Obj that should be written in the method. Otherwise, all
properties are stored.
</p>
<p>
Use <var>ReadObject</var> to read values from a given path into a persistent
object instance.
</p>
</descr>
<seealso>
<link id="TConfigStorage.WriteProperty"/>
<link id="TConfigStorage.ReadObject"/>
<link id="#rtl.classes.TPersistent">TPersistent</link>
<link id="#rtl.typinfo.GetPropList">GetPropList</link>
<link id="#rtl.typinfo.GetPropInfo">GetPropInfo</link>
<link id="#rtl.typinfo.TTypeData">TTypeData</link>
</seealso>
</element>
<element name="TConfigStorage.WriteObject.Path">
<short>
Path where property names and values from Obj are stored.
</short>
</element>
<element name="TConfigStorage.WriteObject.Obj">
<short>
Persistent object with properties stored in the method.
</short>
</element>
<element name="TConfigStorage.WriteObject.DefObject">
<short>
Persistent object with default values for the properties in Obj.
</short>
</element>
<element name="TConfigStorage.WriteObject.OnlyProperty">
<short>
Name for a single property that should be written in the method, instead of all properties.
</short>
</element>
<element name="TConfigStorage.ReadObject">
<short>
Reads names and values from the configuration storage into properties for the
specified object instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigStorage.ReadObject.Path">
<short>
Path where the property names and values read in the method are stored.
</short>
</element>
<element name="TConfigStorage.ReadObject.Obj">
<short>
Persistent object where the values read in the method are stored.
</short>
</element>
<element name="TConfigStorage.ReadObject.DefObject">
<short>
Persistent object with the default values for properties updated in the
method.
</short>
</element>
<element name="TConfigStorage.ReadObject.OnlyProperty">
<short>
Name for a single property value read and stored in Obj.
</short>
</element>
<element name="TConfigStorageClass">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode">
<short>
Implements a storage node used in a memory-based configuration storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Name">
<short>
Name for the node.
</short>
</element>
<element name="TConfigMemStorageNode.Value">
<short>
Value for the node.
</short>
</element>
<element name="TConfigMemStorageNode.Parent">
<short>
Parent node in the tree structure where the current node is stored.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Children">
<short>
Child nodes with names and values stored as sub-paths of the current node.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode.ClearChilds">
<short>
Frees storage nodes allocated in Children.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for the class instance. It initializes values in the Parent and Name properties to the arguments passed to the constructor.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorageNode.Create.AParent">
<short>
Node where the current node is stored as a child node.
</short>
</element>
<element name="TConfigMemStorageNode.Create.AName">
<short>
Name for the new storage node.
</short>
</element>
<element name="TConfigMemStorageNode.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
<var>Destroy</var> is the overridden destructor for the class instance. It
calls <var>ClearChilds</var> to remove all storage nodes allocated in
<var>Children</var>. It ensures the current class instance is removed from
the <var>Parent</var> node (when assigned).
</p>
<p>
Destroy calls the inherited destructor prior to exiting from the method.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorageModification">
<short>
Represents modification operations for configuration storage nodes.
</short>
<descr>
<p>
<var>TConfigMemStorageModification</var> is an enumerated type with values
that represent modification operations performed for nodes in a memory-based
configuration storage.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorageModification.cmsmSet">
<short>
Represents a set or write operation.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmGet">
<short>
Represents a get or read operation.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmDelete">
<short>
Represents a delete operation for a storage node.
</short>
</element>
<element name="TConfigMemStorageModification.cmsmDeleteValue">
<short>
Represents a delete operation for the value in a storage node.
</short>
</element>
<element name="ConfigMemStorageFormatVersion">
<short>
Current version for the storage format used in configuration storage classes.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage">
<short>
Implement a configuration storage class using in-memory storage for values in
the class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.CreateRoot">
<short>
Creates the root node used to store the values for the memory-based
configuration storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.CreateChilds">
<short>
Creates the tree structure used to store child nodes in the configuration
storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.CreateChilds.Node">
<short>
Memory-based storage node where the child nodes are stored.
</short>
</element>
<element name="TConfigMemStorage.Modify">
<short>
Stores a modified value to the specified path in the configuration storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.Modify.APath">
<short>
Path in the storage where the modified value is stored.
</short>
</element>
<element name="TConfigMemStorage.Modify.Mode">
<short>
Action performed in the modification.
</short>
</element>
<element name="TConfigMemStorage.Modify.AValue">
<short>
New value stored at the specified path in the storage.
</short>
</element>
<element name="TConfigMemStorage.DeleteFullPath">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.DeleteFullPath.APath">
<short/>
</element>
<element name="TConfigMemStorage.DeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.DeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.GetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.Result">
<short/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.ADefault">
<short/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.AValue">
<short/>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.DefValue">
<short/>
</element>
<element name="TConfigMemStorage.SetFullPathValue">
<short/>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SetFullPathValue.APath">
<short/>
</element>
<element name="TConfigMemStorage.SetFullPathValue.AValue">
<short/>
</element>
<element name="TConfigMemStorage.Root">
<short>
TConfigMemStorageNode instance with the storage nodes are the configuration
storage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFilename">
<short>
Re-implements the method used to get the file name where the configuration
items are stored. Not used in TConfigMemStorage.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFilename.Result">
<short>
Always returns an empty string ('') in TConfigMemStorage.
</short>
</element>
<element name="TConfigMemStorage.WriteToDisk">
<short>
Re-implements the method used to store the configuration items to disk.
</short>
<descr>
<p>
WriteToDisk raises an Exception with the message:
</p>
<code>
'TConfigMemStorage.WriteToDisk invalid operation'
</code>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorage.Destroy">
<short>
Destructor for the class instance.
</short>
<descr>
<p>
Frees resources allocate to the Root storage node in the class instance.
Calls the inherited destructor prior to exit.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorage.Clear">
<short>
Clears the storage nodes in the memory-based configuration storage.
</short>
<descr>
<p>
Free resources allocated to the Root storage node in the class instance.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorage.SaveToConfig">
<short>
Save the storage nodes to the specified path in another configuration
storage class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.SaveToConfig.Config">
<short/>
</element>
<element name="TConfigMemStorage.SaveToConfig.APath">
<short/>
</element>
<element name="TConfigMemStorage.LoadFromConfig">
<short>
Loads storage nodes from the specified path in another configuration storage
class instance.
</short>
<descr/>
<seealso/>
</element>
<element name="TConfigMemStorage.LoadFromConfig.Config">
<short/>
</element>
<element name="TConfigMemStorage.LoadFromConfig.APath">
<short/>
</element>
<element name="TConfigMemStorage.WriteDebugReport">
<short>
Generates the content in the Root node in a format suitable for debugger
output.
</short>
<descr/>
<seealso/>
</element>
<element name="LoadStringToStringTree">
<short>
Loads names and values in the specified path from a configuration storage
instance to the specified Tree.
</short>
<descr/>
<seealso/>
</element>
<element name="LoadStringToStringTree.Config">
<short>
Configuration storage instance with the names and values loaded into the tree.
</short>
</element>
<element name="LoadStringToStringTree.Path">
<short>
Path with the item names and values loaded from Config.
</short>
</element>
<element name="LoadStringToStringTree.Tree">
<short>
String map where the names and values for configuration items stored in the routine.
</short>
</element>
<element name="SaveStringToStringTree">
<short/>
<descr/>
<seealso/>
</element>
<element name="SaveStringToStringTree.Config">
<short/>
</element>
<element name="SaveStringToStringTree.Path">
<short/>
</element>
<element name="SaveStringToStringTree.Tree">
<short/>
</element>
<element name="CompareConfigMemStorageNames">
<short/>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNames.Result">
<short/>
</element>
<element name="CompareConfigMemStorageNames.p1">
<short/>
</element>
<element name="CompareConfigMemStorageNames.p2">
<short/>
</element>
<element name="CompareConfigMemStorageNodes">
<short/>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNodes.Result">
<short/>
</element>
<element name="CompareConfigMemStorageNodes.Node1">
<short/>
</element>
<element name="CompareConfigMemStorageNodes.Node2">
<short/>
</element>
<element name="ComparePCharWithConfigMemStorageNode">
<short/>
<descr/>
<seealso/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.Result">
<short/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.aPChar">
<short/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.ANode">
<short/>
</element>
</module>
<!-- LazConfigStorage -->
</package>
</fpdoc-descriptions>