TConfigStorage 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.

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.

For example:

Values can be specified using one of the native Pascal data types supported in the class, like:

• String
• Integer
• Boolean
• TStrings
• TRect
• TPoint
• TPersistent

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.

Do not create instances of TConfigStorage. Use of the descendent classes like TConfigMemStorage or TXMLConfigStorage.

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.

GetFullPathValue is an abstract virtual method in TConfigStorage. It is implemented in a descendent class to use the storage mechanism for the class instance.

SetFullPathValue is an overloaded abstract virtual method in TConfigStorage. It must be overridden in a descendent class to use the node notation required for the underlying storage mechanism.

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.

SetDeleteFullPathValue is an overloaded abstract virtual method in TConfigStorage. It must be overridden and implemented in a descendent class to use the node notation required for the underlying storage mechanism.

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.

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.

DeleteFullPath is an abstract virtual method in TConfigStorage. 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.

DeleteFullPath always physically removes the node at the specified path. Use SetDeleteFullPathValue to update or remove a node using a value and default value.

DeleteFullPath is used to implement the DeletePath method.

DeleteFullPathValue is an abstract virtual method in TConfigStorage used to delete the node with the path name specified in APath. It must be implemented in a descendent class to access the storage mechanism for the derived class instance.

DeleteFullPathValue is used to implement the DeleteValue method.

WriteProperty is based on the actions performed by the TWriter 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.

APath contains the fully-qualified path where value(s) are stored in the configuration storage.

Instance is the RTTI-enabled persistent object with the value(s) retrieved and written in the method.

PropInfo 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.

OnlyProperty 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.

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 Nil - but default property values cannot be determined when omitted.

WriteProperty handles values for the following type kinds in property type information:

• tkInteger (including string identifiers for the value)
• tkChar
• tkEnumeration
• tkSet (as comma-delimited identifiers in the set)
• tkWChar
• tkFloat
• tkSString
• tkLString
• tkAString
• tkBool

The following type kinds are not explicitly handled in the current LCL version:

• tkWString
• tkInt64
• tkQWord

ReadProperty is based on the actions performed by the TReader class in the FPC RTL. Is uses the RTTI property information passed in the PropInfo argument to store the property values in Instance. No actions are performed if the property information does not have both a getter and a setter routine for the property value.

APath contains the fully-qualified path where value(s) are stored in the configuration storage.

Instance is the RTTI-enabled persistent object where value(s) read from the configuration storage are stored in the method.

PropInfo 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.

OnlyProperty 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.

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 Nil), the Instance argument is assigned to DefInstance.

ReadProperty handles values for the following type kinds in property type information:

• tkInteger (including integer which have a string identifier)
• tkChar
• tkEnumeration
• tkSet
• tkWChar
• tkFloat
• tkSString
• tkLString
• tkAString
• tkBool

The following type kinds are not explicitly handled in the current LCL version:

• tkWString
• tkInt64
• tkQWord

Destroy is the overridden destructor for the class instance. It frees resources allocated for members in the class instance, and calls the inherited destructor.

Clear is an abstract virtual method in TConfigStorage. It is implemented in descendent classes to provide a file- or memory-based storage mechanism.

GetValue is an overloaded method in TConfigStorage. The overloaded variants allow the value read from the specified path in the configuration storage to be returned as one of the following types:

• String
• Integer
• Boolean
• TRect (returned in the output parameter)
• TPoint (returned in the output parameter)
• TStrings (returned in the output parameter)

ADefault 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.

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.

SetValue is an overloaded method in TConfigStorage used to store the value specified in the AValue argument to the node path in APath. The overloaded variants allow AValue to be specified using String, Integer, Boolean, TRect, or TPoint types.

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.

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.

Use GetValue to read a stored value for a specified node path.

SetDeleteValue is an overloaded method in TConfigStorage. The variants allow the method to be used to store a value using either a String, Integer, Boolean, TRect, or TPoint type in the AValue argument.

APath 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.

DefValue 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.

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.

Calls ExtendPath to resolve APath to the CurrentBasePath for the storage. Calls DeleteFullPath to remove the resolved path to the storage node.

Calls ExtendPath to resolve APath to the CurrentBasePath for the storage. Calls DeleteFullPathValue to remove value for the resolved node path.

CurrentBasePath is a read-only String 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.

Inserts the value in CurrentBasePath as a prefix for the value in APath.

AppendBasePath 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.

Use UndoAppendBasePath to remove a path node from the value in CurrentBasePath.

WriteToDisk is an abstract virtual method in TConfigStorage. It must be implemented in a descendent class to perform actions needed to store values to the mechanism used in a derived class.

GetFileName is an abstract virtual String function in TConfigStorage. 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.

WriteObject is a method used to store names and values from the properties in the specified persistent object into the configuration storage.

Path contains the location in configuration storage where the property values are stored. It provides a unique location for the values stored in the method.

Obj is the TPersistent instance with the property values stored in the method.

WriteObject calls WriteProperty for each of the properties returned from the RTL GetPropList routine. Sub-paths representing each of the published properties in the object are created by calling the WriteProperty method.

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.

Use the OnlyProperty argument to specify the name for a single property in Obj that should be written in the method. Otherwise, all properties are stored.

Use ReadObject to read values from a given path into a persistent object instance.

TConfigStorageClass is the type used for the DefaultConfigClass variable in the Lazarus IDE.

Create is the constructor for the class instance. It initializes values in the Parent and Name properties to the arguments passed to the constructor.

Destroy is the overridden destructor for the class instance. It calls ClearChilds to remove all storage nodes allocated in Children. It ensures the current class instance is removed from the Parent node (when assigned).

Destroy calls the inherited destructor prior to exiting from the method.

TConfigMemStorageModification is an enumerated type with values that represent modification operations performed for nodes in a memory-based configuration storage.

DeleteFullPath is an overridden method in TConfigMemStorage. 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.

DeleteFullPath is called from the DeletePath method.

GetFullPathValue is an overloaded method in TConfigMemStorage. It implements the abstract virtual methods defined in the TConfigStorage ancestor. The variants allow the value in ADefault to specified as either a String, Integer, or Boolean type. Please note that TRect and TPoint are not handled in TConfigMemStorage.

SetDeleteFullPathValue is an overloaded overridden method in TConfigMemStorage. 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.

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.

SetFullPathValue is an overloaded method in TConfigStorage. It implements the abstract virtual method introduced in the TConfigStorage ancestor. The overloaded variants convert AValue to a String type (when needed) and stores the value in a memory-based configuration node with the fully-qualified path specified in APath.

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.

Root is a TConfigMemStorageNode 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.

WriteToDisk raises an Exception with the message:

Frees resources allocate to the Root storage node in the class instance. Calls the inherited destructor prior to exit.

Free resources allocated to the Root storage node in the class instance.

SaveStringToStringTree is a routine used to save values found in the specified Tree structure to a TConfigStorage instance under the specified path.