<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<fpdoc-descriptions>
<package name="lazutils">
<!--
====================================================================
LazConfigStorage
====================================================================
-->
<module name="LazConfigStorage">
<short>
Defines various base classes for loading and saving configuration files.
</short>
<descr>
<p>
<file>lazconfigstorage.pas</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="LazStringUtils"/>

<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>
Defines the method used to resolve the specified node path prior to storing the 
specified value.
</short>
<descr>
<p>
<var>SetFullPathValue</var> is an overloaded abstract virtual method in 
<var>TConfigStorage</var>. It must be overridden in a descendent class to use 
the node notation required for the underlying storage mechanism.
</p>
<p>
SetFullPathValue is called from the SetValue method after ExtendPath has been 
called to include the CurrentBasePath value at the start of the node path in 
APath.
</p>
</descr>
<seealso>
<link id="TConfigStorage.SetFullPathValue"/>
<link id="TConfigStorage.SetValue"/>
<link id="TConfigStorage.ExtendPath"/>
<link id="TConfigStorage.CurrentBasePath"/>
<link id="TConfigMemStorage.SetFullPathValue"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>
<element name="TConfigStorage.SetFullPathValue.APath">
<short>
Path to the node where the specified value is stored.
</short>
</element>
<element name="TConfigStorage.SetFullPathValue.AValue">
<short>
Value stored in the specified node path. Overloaded variants allow AValue to be 
specified using as either a String, an Integer, or a Boolean type.
</short>
</element>

<element name="TConfigStorage.SetDeleteFullPathValue">
<short>
Defines the method used to delete the specified node path or to reset it to a 
default value.
</short>
<descr>
<p>
<var>SetDeleteFullPathValue</var> is an overloaded abstract virtual method in 
<var>TConfigStorage</var>. It must be overridden and implemented in a 
descendent class to use the node notation required for the underlying storage 
mechanism.
</p>
<p>
Overloaded variants of the method allow the AValue and DefValue arguments to be 
passed as either String, Integer, or Boolean types. Both arguments must use the 
same type. The arguments determine whether the node is removed or updated with 
a default value in the storage mechanism. When both arguments have the same 
value, the node at APath is deleted from the storage. Otherwise, the value in 
DefValue is stored for the specified node.
</p>
<p>
SetDeleteFullPathValue is called from the SetDeleteValue method after 
ExtendPath has been called to include the CurrentBasePath value at the start of 
the node path in APath.
</p>
</descr>
<seealso>
<link id="TConfigStorage.SetDeleteValue"/>
<link id="TConfigStorage.ExtendPath"/>
<link id="TConfigStorage.CurrentBasePath"/>
<link id="TConfigMemStorage.SetDeleteFullPathValue"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.APath">
<short>
Path to the node updated or removed in the method.
</short>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.AValue">
<short>
Value for the node to update or remove in the method. Causes the node to be 
deleted when its value matches DefValue.
</short>
</element>
<element name="TConfigStorage.SetDeleteFullPathValue.DefValue">
<short>
Default value stored in the node when AValue does not match DefValue.
</short>
</element>

<element name="TConfigStorage.DeleteFullPath">
<short>
Defines the method used to remove the node at the specified path from the 
configuration storage.
</short>
<descr>
<p>
<var>DeleteFullPath</var> is an abstract virtual method in 
<var>TConfigStorage</var>. It must be implemented in a descendent class to 
perform actions needed to remove the specified node from the storage mechanism 
for the class instance.
</p>
<p>
DeleteFullPath always physically removes the node at the specified path. Use 
SetDeleteFullPathValue to update or remove a node using a value and default 
value.
</p>
<p>
DeleteFullPath is used to implement the DeletePath method.
</p>
</descr>
<seealso>
<link id="TConfigMemStorage.DeleteFullPath"/>
</seealso>
</element>
<element name="TConfigStorage.DeleteFullPath.APath">
<short>
Path to the node deleted in the method.
</short>
</element>

<element name="TConfigStorage.DeleteFullPathValue">
<short>
Defines the method used to delete the node with the specified full path name 
from the configuration storage.
</short>
<descr>
<p>
<var>DeleteFullPathValue</var> is an abstract virtual method in 
<var>TConfigStorage</var> used to delete the node with the path name specified 
in <var>APath</var>. It must be implemented in a descendent class to access the 
storage mechanism for the derived class instance.
</p>
<p>
DeleteFullPathValue is used to implement the DeleteValue method.
</p>
</descr>
<seealso>
<link id="TConfigStorage.DeleteValue"/>
</seealso>
</element>
<element name="TConfigStorage.DeleteFullPathValue.APath">
<short>
Fully-qualified path name for the node deleted in the method.
</short>
</element>

<element name="TConfigStorage.WriteProperty">
<short>
Stores one or more property values from an RTTI-enabled persistent object to 
the specified path in the configuration storage.
</short>
<descr>
<p>
<var>WriteProperty</var> is based on the actions performed by the 
<var>TWriter</var> class in the FPC RTL. Is uses the RTTI property information 
passed in the PropInfo argument to access each of the properties in Instance. 
No actions are performed for a given property if it does not provide both a 
getter and a setter routine for the property value.
</p>
<p>
<var>APath</var> contains the fully-qualified path where value(s) are stored in 
the configuration storage.
</p>
<p>
<var>Instance</var> is the RTTI-enabled persistent object with the value(s) 
retrieved and written in the method.
</p>
<p>
<var>PropInfo</var> in a pointer to type information for the persistent object 
in Instance (and DefInstance). It is used to access each property, and to 
convert and store each value in the storage mechanism by calling the SetValue 
method.
</p>
<p>
<var>OnlyProperty</var> contains an optional name for a single property name 
stored in the method. When omitted (or set to an empty string), all of the 
properties in the type information are stored starting at the specified path 
using the Name for the property type as an identifier.
</p>
<p>
DefInstance is a persistent object which contains values to be treated as the 
default values for the corresponding properties in Instance. When a property 
has the same value in both Instance and DefInstance, it is deleted from the 
configuration storage. DefInstance can be <b>Nil</b> - but default property 
values cannot be determined when omitted.
</p>
<p>
WriteProperty handles values for the following type kinds in property type 
information:
</p>
<ul>
<li>tkInteger (including string identifiers for the value)</li>
<li>tkChar</li>
<li>tkEnumeration</li>
<li>tkSet (as comma-delimited identifiers in the set)</li>
<li>tkWChar</li>
<li>tkFloat</li>
<li>tkSString</li>
<li>tkLString</li>
<li>tkAString</li>
<li>tkBool</li>
</ul>
<p>
The following type kinds are <b>not</b> explicitly handled in the current LCL 
version:
</p>
<ul>
<li>tkWString</li>
<li>tkInt64</li>
<li>tkQWord</li>
</ul>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.WriteProperty.Path">
<short>
Path where property value(s) from the specified object are stored.
</short>
</element>
<element name="TConfigStorage.WriteProperty.Instance">
<short>
Persistent object with the property value(s) stored in the method.
</short>
</element>
<element name="TConfigStorage.WriteProperty.PropInfo">
<short>
Pointer to the RTTI property information processed in the method.
</short>
</element>
<element name="TConfigStorage.WriteProperty.DefInstance">
<short>
Persistent object with the default value(s) for properties processed in the 
method.
</short>
</element>
<element name="TConfigStorage.WriteProperty.OnlyProperty">
<short>
Specifies a single property name to the stored in the method. All properties in 
PropInfo are stored when omitted (or set to '').
</short>
</element>

<element name="TConfigStorage.ReadProperty">
<short>
Reads value(s) from a path in the configuration storage into the specified 
persistent object.
</short>
<descr>
<p>
<var>ReadProperty</var> is based on the actions performed by the 
<var>TReader</var> class in the FPC RTL. Is uses the RTTI property information 
passed in the <var>PropInfo</var> argument to store the property values in 
<var>Instance</var>. No actions are performed if the property information does 
not have both a getter and a setter routine for the property value.
</p>
<p>
<var>APath</var> contains the fully-qualified path where value(s) are stored in 
the configuration storage.
</p>
<p>
<var>Instance</var> is the RTTI-enabled persistent object where value(s) read 
from the configuration storage are stored in the method.
</p>
<p>
<var>PropInfo</var> in a pointer to type information for the persistent object 
in Instance (and DefInstance). It is used to access each property, and to 
convert and store each value from the storage mechanism using RTTI routines.
</p>
<p>
<var>OnlyProperty</var> contains an optional name for a single property name 
handled in the method. When omitted (or set to an empty string), all of the 
properties in the type information are read and stored in the properties 
starting at the specified path.
</p>
<p>
DefInstance is a persistent object which contains values to be treated as the 
default values for the corresponding properties in Instance. If DefInstance is 
not specified (or contains <b>Nil</b>), the Instance argument is assigned to 
DefInstance.
</p>
<p>
ReadProperty handles values for the following type kinds in property type 
information:
</p>
<ul>
<li>tkInteger (including integer which have a string identifier)</li>
<li>tkChar</li>
<li>tkEnumeration</li>
<li>tkSet</li>
<li>tkWChar</li>
<li>tkFloat</li>
<li>tkSString</li>
<li>tkLString</li>
<li>tkAString</li>
<li>tkBool</li>
</ul>
<p>
The following type kinds are <b>not</b> explicitly handled in the current LCL 
version:
</p>
<ul>
<li>tkWString</li>
<li>tkInt64</li>
<li>tkQWord</li>
</ul>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.ReadProperty.Path">
<short>
Path where property value(s) are stored in the configuration storage.
</short>
</element>
<element name="TConfigStorage.ReadProperty.Instance">
<short>
Persistent object where value(s) read from storage are stored in the method.
</short>
</element>
<element name="TConfigStorage.ReadProperty.PropInfo">
<short>
Pointer to the RTTI property information processed in the method.
</short>
</element>
<element name="TConfigStorage.ReadProperty.DefInstance">
<short>
Persistent object with the default value(s) for properties processed in the 
method.
</short>
</element>
<element name="TConfigStorage.ReadProperty.OnlyProperty">
<short>
Specifies a single property name to the stored in the method. All properties in 
PropInfo are stored when omitted (or set to '').
</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>
Gets the value stored at the specified path relative to the base path in the 
configuration storage.
</short>
<descr>
<p>
<var>GetValue</var> is an overloaded method in <var>TConfigStorage</var>. The 
overloaded variants allow the value read from the specified path in the 
configuration storage to be returned as one of the following types:
</p>
<ul>
<li>String</li>
<li>Integer</li>
<li>Boolean</li>
<li>TRect (returned in the output parameter)</li>
<li>TPoint  (returned in the output parameter)</li>
<li>TStrings  (returned in the output parameter)</li>
</ul>
<p>
<var>ADefault</var> contains the default value returned if a value is not found 
in the storage for the specified path. The argument uses the same type as the 
return value for the overloaded methods.
</p>
<p>
GetValue calls GetFullPathValue after using ExtendPath to insert the value 
CurrentBasePath at the start of the value in APath. The value in ADefault
is passed to GetFullPathValue as the default value.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.GetValue.Result">
<short>
Returns the value stored at the specified path.
</short>
</element>
<element name="TConfigStorage.GetValue.APath">
<short>
Path in the configuration storage relative to CurrentBasePath where the value 
is stored.
</short>
</element>
<element name="TConfigStorage.GetValue.ADefault">
<short>
Default value used when a value is not found at the specified path.
</short>
</element>
<element name="TConfigStorage.GetValue.ARect">
<short>
Returns the value read from the configuration storage as a TRect type.  
</short>
</element>
<element name="TConfigStorage.GetValue.APoint">
<short>
Returns the value read from the configuration storage as a TPoint type.  
</short>
</element>
<element name="TConfigStorage.GetValue.List">
<short>
Returns the value read from the configuration storage as a TStrings type.  
</short>
</element>

<element name="TConfigStorage.SetValue">
<short>
Stores a value at the specified path in the configuration storage.
</short>
<descr>
<p>
<var>SetValue</var> is an overloaded method in <var>TConfigStorage</var> used 
to store the value specified in the <var>AValue</var> argument to the node path 
in <var>APath</var>. The overloaded variants allow AValue to be specified using 
String, Integer, Boolean, TRect, or TPoint types.
</p>
<p>
APath contains the node path where the value is stored in the storage 
mechanism. SetValue calls the ExtendPath method to include the value in 
CurrentBasePath prior to the specified node path.
</p>
<p>
The SetFullPathValue method is called to store AValue to the underlying storage 
mechanism. Overloads for TRect and TPoint are decomposed and stored as the 
members values for the types. For TRect: Left, Top, Right, and Bottom are 
stored. For TPoint: X and Y are stored.
</p>
<p>
Use GetValue to read a stored value for a specified node path.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.SetValue.APath">
<short>
Node path (relative to CurrentBasePath) where the specified value is stored.
</short>
</element>
<element name="TConfigStorage.SetValue.AValue">
<short>
Value stored for the specified node path.
</short>
</element>

<element name="TConfigStorage.SetDeleteValue">
<short>
Updates the value for the specified node path, or deletes it when it contains a 
default value.
</short>
<descr>
<p>
<var>SetDeleteValue</var> is an overloaded method in <var>TConfigStorage</var>. 
The variants allow the method to be used to store a value using either a 
String, Integer, Boolean, TRect, or TPoint type in the <var>AValue</var> 
argument.
</p>
<p>
<var>APath</var> is the path to the node where the value is stored. It is 
specified with a value relative to the CurrentBasePath property. ExtendPath is 
called to insert CurrentBasePath at the start of the node path.
</p>
<p>
<var>DefValue</var> contains the value treated as the default value for the 
node path. The overloaded variants use the same type as specified in the AValue 
argument.
</p>
<p>
SetDeleteValue calls the SetDeleteFullPathValue method to update or remove the 
value at the specified path. When DefValue is equal to AValue, the node path in 
APath to be removed from the configuration storage.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.SetDeleteValue.APath">
<short>
Path to the node value updated or removed in the method.  
</short>
</element>
<element name="TConfigStorage.SetDeleteValue.AValue">
<short>
Value stored in the specified node.
</short>
</element>
<element name="TConfigStorage.SetDeleteValue.DefValue">
<short>
Default value which triggers removal of the node when it is the same as AValue.
</short>
</element>

<element name="TConfigStorage.DeletePath">
<short>
Removes the configuration storage node with the specified path.
</short>
<descr>
<p>
Calls ExtendPath to resolve APath to the CurrentBasePath for the storage. Calls 
DeleteFullPath to remove the resolved path to the storage node.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.DeletePath.APath">
<short>
Path to the node removed in the method.
</short>
</element>

<element name="TConfigStorage.DeleteValue">
<short>
Deletes the value stored for the specified path.
</short>
<descr>
<p>
Calls ExtendPath to resolve APath to the CurrentBasePath for the storage. Calls 
DeleteFullPathValue to remove value for the resolved node path.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.DeleteValue.APath">
<short>
Relative path to the node removed in the method.
</short>
</element>

<element name="TConfigStorage.CurrentBasePath">
<short>
Contains the base node path where values are read or written in the storage 
mechanism.
</short>
<descr>
<p>
<var>CurrentBasePath</var> is a read-only <var>String</var> property. Its value 
is updated when the AppendBasePath and UndoAppendBasePath methods are called in 
the class instance. The value is used when the ExtendPath method is called to 
resolve a relative node path to its location in the storage mechanism.
</p>
</descr>
<seealso/>
</element>

<element name="TConfigStorage.ExtendPath">
<short>
Resolves a relative node path to the current base path for the storage 
mechanism.
</short>  
<descr>
<p>
Inserts the value in CurrentBasePath as a prefix for the value in APath.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.ExtendPath.Result">
<short>
Path to a node after it has been resolved to CurrentBasePath.
</short>
</element>
<element name="TConfigStorage.ExtendPath.APath">
<short>
Relative node path extended with the value in CurrentBasePath.
</short>
</element>

<element name="TConfigStorage.AppendBasePath">
<short>
Appends the specified relative path to the existing value in CurrentBasePath.
</short>  
<descr>
<p>
<var>AppendBasePath</var> is a method used to append the relative path 
specified for a node in Path to the value in the CurrentBasePath property. 
AppendBasePath ensures that a trailing path delimiter ('/') is appended to the 
value in CurrentBasePath when it not empty and does not already include the 
delimiter.
</p>
<p>
Use UndoAppendBasePath to remove a path node from the value in CurrentBasePath.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigStorage.AppendBasePath.Path">
<short>
Relative path added to the value in CurrentBasePath.
</short>
</element>

<element name="TConfigStorage.UndoAppendBasePath">
<short>
Removes the last node path from the value in CurrentBasePath.
</short>
<descr/>
<seealso/>
</element>

<element name="TConfigStorage.WriteToDisk">
<short>
Defines the method used to flush the values in the configuration storage to the 
underlying storage mechanism.
</short>
<descr>
<p>
<var>WriteToDisk</var> is an abstract virtual method in 
<var>TConfigStorage</var>. It must be implemented in a descendent class to 
perform actions needed to store values to the mechanism used in a derived class.
</p>
</descr>
<seealso>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage.WriteToDisk">TXMLConfigStorage.WriteToDisk</link>
</seealso>
</element>

<element name="TConfigStorage.GetFilename">
<short>
Defines the method used to get the file name where configuration data is stored.
</short>
<descr>
<p>
<var>GetFileName</var> is an abstract virtual <var>String</var> function in <var
>TConfigStorage</var>. It is used to retrieve the file name where configuration 
data is stored when the WriteToDisk method is called. It must be implemented in 
a descendent class which uses a file as the destination for the storage 
mechanism.
</p>
</descr>
<seealso>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage.GetFileName">TXMLConfigStorage.GetFileName</link>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage.WriteToDisk">TXMLConfigStorage.WriteToDisk</link>
</seealso>
</element>
<element name="TConfigStorage.GetFilename.Result">
<short>
Returns the file name where the configuration data is stored.
</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>
Class reference used to create new instances of TConfigStorage.
</short>
<descr>
<p>
TConfigStorageClass is the type used for the DefaultConfigClass variable in the 
Lazarus IDE.
</p> 
</descr>
</element>

<element name="TConfigMemStorageNode">
<short>
Implements a storage node used in a memory-based configuration storage.
</short>
<descr/>
<seealso>
<link id="TConfigMemStorageNode.Parent"/>
<link id="TConfigMemStorageNode.Children"/>
<link id="TConfigMemStorage.Root"/>
<link id="CompareConfigMemStorageNodes"/>
<link id="ComparePCharWithConfigMemStorageNode"/>
</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>
Implements the method used to remove the node at the specified path from the 
configuration storage.
</short>
<descr>
<p>
<var>DeleteFullPath</var> is an overridden method in 
<var>TConfigMemStorage</var>. It must be implemented in a descendent class to 
perform actions needed to remove the specified node from the storage mechanism 
for the class instance. It calls a private method used to search nodes in the 
memory-based storage for the specified node path. When found, the node is 
removed.
</p>
<p>
DeleteFullPath is called from the DeletePath method.
</p>
</descr>
<seealso>
<link id="TConfigStorage.DeletePath"/>
</seealso>
</element>
<element name="TConfigMemStorage.DeleteFullPath.APath">
<short>
Path to the node removed in the method.
</short>
</element>

<element name="TConfigMemStorage.DeleteFullPathValue">
<short>
Deletes the node with the specified full path name from the configuration 
storage.
</short>
<descr>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorage.DeleteFullPathValue.APath">
<short>
Fully-qualified path to the node removed in the method.
</short>
</element>

<element name="TConfigMemStorage.GetFullPathValue">
<short>
Gets the value from the specified node path with an optional default value when 
not found.
</short>
<descr>
<p>
<var>GetFullPathValue</var> is an overloaded method in 
<var>TConfigMemStorage</var>. It implements the abstract virtual methods 
defined in the TConfigStorage ancestor. The variants allow the value in 
<var>ADefault</var> to specified as either a String, Integer, or Boolean type. 
Please note that TRect and TPoint are not handled in TConfigMemStorage.
</p>
</descr>
<seealso/>
</element>
<element name="TConfigMemStorage.GetFullPathValue.Result">
<short>
Value stored in the specified node path.
</short>
</element>
<element name="TConfigMemStorage.GetFullPathValue.APath">
<short>
Path to the node where the value is stored.
</short>
</element>
<element name="TConfigMemStorage.GetFullPathValue.ADefault">
<short>
Default value returned when the specified node path is not found in the storage.
</short>
</element>

<element name="TConfigMemStorage.SetDeleteFullPathValue">
<short>
Implements the method used to delete the specified node path or to reset it to 
a default value.
</short>
<descr>
<p>
<var>SetDeleteFullPathValue</var> is an overloaded overridden method in 
<var>TConfigMemStorage</var>. Overloaded variants of the method allow the 
AValue and DefValue arguments to be passed as either String, Integer, or 
Boolean types. Both arguments must use the same type. The arguments determine 
whether the node is removed or updated with a default value in the storage 
mechanism. When both arguments have the same value, the node at APath is 
deleted from the storage. Otherwise, the value in DefValue is stored for the 
specified node.
</p>
<p>
SetDeleteFullPathValue is called from the SetDeleteValue method after 
ExtendPath has been called to include the CurrentBasePath value at the start of 
the node path in APath.
</p>
</descr>
<seealso>
<link id="TConfigStorage.SetDeleteFullPathValue"/>
<link id="TConfigStorage.ExtendPath"/>
<link id="TConfigStorage.CurrentBasePath"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.APath">
<short>
Path to the node updated or removed in the method.
</short>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.AValue">
<short>
Value for the node to update or remove in the method. Causes the node to be 
deleted when its value matches DefValue.
</short>
</element>
<element name="TConfigMemStorage.SetDeleteFullPathValue.DefValue">
<short>
Default value stored in the node when AValue does not match DefValue.
</short>
</element>

<element name="TConfigMemStorage.SetFullPathValue">
<short>
Implements the method used to resolve the specified node path prior to storing 
the specified value.
</short>
<descr>
<p>
<var>SetFullPathValue</var> is an overloaded method in 
<var>TConfigStorage</var>. It implements the abstract virtual method introduced 
in the TConfigStorage ancestor. The overloaded variants convert 
<var>AValue</var> to a String type (when needed) and stores the value in a 
memory-based configuration node with the fully-qualified path specified in 
<var>APath</var>.
</p>
<p>
SetFullPathValue is called from the SetValue method after ExtendPath has been 
called to include the CurrentBasePath value at the start of the node path in 
APath.
</p>
</descr>
<seealso>
<link id="TConfigStorage.SetValue"/>
<link id="TConfigStorage.SetFullPathValue"/>
<link id="TConfigStorage.CurrentBasePath"/>
<link id="TConfigStorage.ExtendPath"/>
<link id="#lcl.xmlpropstorage.TXMLConfigStorage">TXMLConfigStorage</link>
</seealso>
</element>
<element name="TConfigMemStorage.SetFullPathValue.APath">
<short>
Resolved path to the node where the specified value is stored.
</short>
</element>
<element name="TConfigMemStorage.SetFullPathValue.AValue">
<short>
Value stored in the specified node path. Overloaded variants allow AValue to be 
specified using as either a String, an Integer, or a Boolean type.
</short>
</element>

<element name="TConfigMemStorage.Root">
<short>
TConfigMemStorageNode instance with the root node for the configuration 
storage.
</short>
<descr>
<p>
<var>Root</var> is a <var>TConfigMemStorageNode</var> member with the root node 
for the storage. The node is created (when needed) when a value is stored to 
the memory-based configuration storage, and freed when the class instance is 
destroyed. Nodes in the storage are accessed starting at the Root node, and 
navigated by accessing the child nodes recursively. The node path reflects the 
hierarchy of nodes accessed to reach a specific node.
</p>
</descr>
<seealso>
<link id="TConfigMemStorageNode"/>
</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>
Configuration storage instance where values are stored.  
</short>
</element>
<element name="TConfigMemStorage.SaveToConfig.APath">
<short>
Path to the location in Config where values in the current class instance are 
stored.
</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>
Configuration storage instance with the values loaded into the current class.
</short>
</element>
<element name="TConfigMemStorage.LoadFromConfig.APath">
<short>
Path to the values in Config which are loaded in the method.
</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 at the specified path in 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>
Not used in the current LCL version.  
</short>
<descr>
<p>
<var>SaveStringToStringTree</var> is a routine used to save values found in the 
specified Tree structure to a TConfigStorage instance under the specified path.
</p>
</descr>
<seealso/>
</element>
<element name="SaveStringToStringTree.Config">
<short>
Configuration storage where the value(s) in Tree are stored.
</short>
</element>
<element name="SaveStringToStringTree.Path">
<short>
Path to the node in Config where the value(s) in Tree are stored.
</short>
</element>
<element name="SaveStringToStringTree.Tree">
<short>
String map enumerator with the values stored in the routine.
</short>
</element>

<element name="DateAsCfgStrFormat">
<short>
Default locale-independent format used for date values in DateToCfgStr.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>

<element name="DateTimeAsCfgStrFormat">
<short>
Default locale-independent format used for date/time values.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>

<element name="DateToCfgStr">
<short>
Returns a string representation for TDateTime value using the specified format.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="DateToCfgStr.Result">
<short>
String with the date and/or time represented using the specified format.
</short>
</element>
<element name="DateToCfgStr.Date">
<short>
TDateTime value converted in the routine.
</short>
</element>
<element name="DateToCfgStr.AFormat">
<short>
Format for the date/time value. Default value is defined in the 
DateAsCfgStrFormat constant and represents the date part of the specified 
value.
</short>
</element>

<element name="CfgStrToDate">
<short>
Converts a string with a date/time value using the specified format to the 
TDateTime output value.
</short>
<descr/>
<version>
Added in LazUtils version 3.0.
</version>
<seealso/>
</element>
<element name="CfgStrToDate.Result">
<short>
<b>True</b> if the string was successfully converted to a TDateTIme value in 
the routine.
</short>
</element>
<element name="CfgStrToDate.s">
<short>
String with the date and/or time value converted in the routine.
</short>
</element>
<element name="CfgStrToDate.Date">
<short>
Returns the TDateTime value for the specified string, or an empty TDateTime 
value (0.0) when the routine returns <b>False</b>.
</short>
</element>
<element name="CfgStrToDate.AFormat">
<short>
Format used for the date/time value passed in the s argument.
</short>
</element>

<element name="CompareConfigMemStorageNames">
<short>
Compares the specified PChar values to determine the relative order for the 
memory node paths.
</short>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNames.Result">
<short>
Returns 0 if the arguments have the same value (or both are empty).
Returns -1 if p1 has a shorter path length than (comes before) p2.
Returns 1 if p1 has a longer path length than (comes after) p2.
</short>
</element>
<element name="CompareConfigMemStorageNames.p1">
<short>
Node path compared up to the first '/' or #0 character.  
</short>
</element>
<element name="CompareConfigMemStorageNames.p2">
<short>
Node path compared up to the first '/' or #0 character.  
</short>
</element>

<element name="CompareConfigMemStorageNodes">
<short>
Compares the names for the specified memory-based storage nodes to determine 
their relative order.
</short>
<descr/>
<seealso/>
</element>
<element name="CompareConfigMemStorageNodes.Result">
<short>
Returns 0 if the node names have the same value (or both are empty).
Returns -1 if Node1 has a node name shorter than (comes before) Node2.
Returns 1 if Node1 has a node name longer than (comes before) Node2.
</short>
</element>
<element name="CompareConfigMemStorageNodes.Node1">
<short>
Memory-based storage node compared in the routine.
</short>
</element>
<element name="CompareConfigMemStorageNodes.Node2">
<short>
Memory-based storage node compared in the routine.
</short>
</element>

<element name="ComparePCharWithConfigMemStorageNode">
<short>
Compares the specified string to the name for a the specified memory-based 
storage nodes to determine their relative order.
</short>
<descr/>
<seealso/>
</element>
<element name="ComparePCharWithConfigMemStorageNode.Result">
<short>
Returns 0 if the string and the node name have the same value (or both are empty).
Returns -1 if the string is shorter than (comes before) the node name in ANode.
Returns 1 if the string is longer than (comes after) the node name in ANode.
</short>
</element>
<element name="ComparePCharWithConfigMemStorageNode.aPChar">
<short>
Pointer to the null-terminated character values compared in the routine.
</short>
</element>
<element name="ComparePCharWithConfigMemStorageNode.ANode">
<short>
Memory-based storage node with the name compared in the routine.  
</short>
</element>

</module>
<!-- LazConfigStorage -->

</package>
</fpdoc-descriptions>