Provides the base class for a storage container use to save and restore control or form properties.

propertystorage.pas contains classes and types used to define a storage container for property values: TCustomPropertyStorage. This is a base class and contains abstract virtual methods which must be implemented in a descendent class. For example: TControlPropertyStorage, TFormPropertyStorage, TIniPropStorage, TJSONPropStorage, and TXMLPropStorage.

This file is part of the Lazarus Component Library (LCL).

Represents operations performed for a property storage container.
The property is being saved.
The property is being restored.
Alias to the type used to store a property value.

When storevariant is defined, TStoredType is aliased to the Variant type. Otherwise, TStoredType is aliased to the AnsiString type.

TStoredType is the type used for the Value property in TStoredValue and in the TStoredValues collection. It is also used to implement the StoredValue property in TCustomPropertyStorage.

Type of an TStoredValue.OnSave and OnRestore notification handler.
Called before a property is saved, after a it has been restored.
Object for the event notification.
Contains the property value for the event.
A key/value pair representing a property value, with added Save/Restore features.
Gets the value for the DisplayName property in the collection item.

GetDisplayName is overridden in TStoredValue to use the value in the Name property (when assigned). If Name is an empty string (''), the inherited method is called to get the value for the property.

TCollectionItem.DisplayName
Value for the property.
Sets the value for the DisplayName property in the collection item.

SetDisplayName is overridden in TStoredValue to set the value for the DisplayName property. SetDisplayName ensures that a new value is not a duplicate of an existing DisplayName value in the TStoredValues. An Exception is raised when AValue is already used in the Collection.

SetDisplayName calls the inherited method prior to exit.

TCollectionItem.DisplayName TCollectionItem.Collection
New value for the property.
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry using ACollection as an argument. Create set the default Value for the collection item to an empty string ('').

TCollectionItem.Create TCollectionItem.Collection
Collection which owns the collection item.
Copies property values from the specified persistent object into the current class instance.

Assign is an overridden method in TStoredValue used to copy property values from the persistent object specified in Source into the current class instance. When Source is assigned and derived from TStoredValue, the following properties are copied:

- Values
- Name
- KeyString

No actions are performed in the method when Source is unassigned (Nil) or not derived from TStoredValue. It does not call the inherited method.

Persistent object with property values copied in the method.
Clears the content in the Value property.

Clear is a method used to remove the existing content in the Value property. The type used for the Value property is dependent on the storevariant compiler define. When defined, the Unassigned variant constant from the RTL is stored in the Value property. Otherwise, an empty string ('') is stored in the property.

Saves the value for the collection item to the storage container for the collection.

Save is a method used to save the Value for the collection item to the storage container for the Collection.

Save signals the OnSave event handler (when assigned) to get the actual value for the collection item used in the operation. The value is converted to a String type when the Value property is stored as a Variant type.

The KeyString property contains the key used to XOR-encode the value stored in the method. XOR encoding is not performed when KeyString is an empty string ('').

Save uses the StoredValues collection to access the storage container where the value is written. The WriteString method in the TCustomPropertyStorage container is called to store a key/value pair using the Name for the collection item and its value.

Use Restore to load a collection item value from the storage container for the collection.

Loads the value for the collection item from the storage container for the collection.

Restore is a method used to load the Value for the collection item for the storage container for the collection.

Restore uses the existing Value as the default value for the restore operation. It is converted to a String when Value is defined as a Variant type.

KeyString contains the key used to XOR encode / decode values written to and read from the storage container for the collection. XOR encoding / decoding is not used when KeyString is an empty string ('').

The default value is XOR encoded when needed. The StoredValues collection is used to access the Storage container and calls its ReadString method. The retrieved value is XOR decoded when needed.

Restore signals the OnRestore event handler (when assigned) to validate and/or modify the restored value.

The collection containing the collection item.

StoredValues is a read-only TStoredValues property with the collection which owns the collection item.

StoredValues is the TCollection descendant passes as an argument to the Create constructor cast to the TStoredValues type. It provides access to name/value pairs for the collection items, and the Storage container used to read and write collection item values in the Save and Restore methods.

The name for the collection item.

Name is a String property with the name for the collection item. It is like the DisplayName property, but enforces uniqueness when setting a new value for the property. An Exception is raised when Name is already used in the Collection.

Name also provides the key used for name/value pairs stored in the storage container for the collection.

The value of the property (as a String or a Variant type).
XOR encoding key, empty for encoding is not used.

KeyString is a String property which contains the key used to XOR encode/decode the Value for the collection item. XOR encoding is performed in the Save method when the collection item is written to the storage container for the collection. XOR decoding is performed in the Restore method when the value is read from the storage container. XOR encoding/decoding is not performed when KeyString is an empty string ('').

Event handler signalled when the collection item value is saved.

OnSave is a TStoredValueEvent property with the event handler signalled when the Value for the collection item is saved to the storage container for the collection. Arguments passed to the event handler identify the collection item and the value for the collection item. The Value parameter is a variable argument and can be modified in the event handler as needed.

OnSave is signalled (when assigned) from the Save method, and occurs before the collection item value is XOR encoded (when needed) and written to the storage container for the collection.

Use OnRestore to perform actions needed when the collection item is retrieved from the storage container for the collection.

Event handler signalled when the collection item value is restored.

OnRestore is a TStoredValueEvent property with the event handler signalled when the Value for the collection item is restored from the storage container for the collection. Arguments passed to the event handler identify the collection item and the value for the collection item. The Value parameter is a variable argument and can be modified in the event handler as needed.

OnRestore is signalled (when assigned) from the Restore method, and occurs after the collection item value has been retrieved from the collection storage and XOR decoded (when needed). It has not been stored in the Value property when the event handler is signalled.

Use the OnSave event handler to perform actions needed when the Value is saved to the storage container for the collection.

Implements a collection for TStoredValue collection items.

TStoredValues is a TOwnedCollection descendant which implements an owned collection for TStoredValue collection items.

TStoredValues provides properties and methods used to access the TStoredValue collection items or their values. Use Items to read and write a collection item by its ordinal position in the collection. Use Values to read and write a collection item by its name. Use StoredValue to read and write the value for a collection item by its name.

The owner of the collection (passed as an argument to the constructor) is a TCustomPropertyStorage instance stored in the Storage property. It provides a container used to read and write name/value pairs which represent the items in the collection. Use RestoreValues and SaveValues methods to read and write the collection items using the Storage container for the collection.

TOwnedCollection
Constructor for the class instance.

Create is the constructor for the class instance, and calls the inherited constructor using AOwner as the owner for the class instance. When AOwner is derived from TCustomPropertyStorage, it is assigned as the value for the Storage property. TStoredValue is the class type used as the ItemClass for the collection.

TOwnedCollection.Create TCollection.ItemClass
TCustomPropertyStorage instance which is the owner and the Storage container for the class.
Gets the ordinal position in Items for the collection item with the specified name.

IndexOf iterates over the values in the Items property to locate the TStoredValue instance with a Name property that matches the value in AName. AnsiCompareText is called to perform a case-insensitive comparison which also ignores accents in the characters.

The return value contains the ordinal position in Items where the value in AName was located, or -1 when a collection item is not found using the specified name.

AnsiCompareText
Ordinal position for the collection item with the given name, or -1 when not found.
Name of the collection item to locate in the method.
Saves all of the collection items to the Storage container for the collection.

SaveValues is a method used to save all of the collection Items to the Storage container for the collection. It iterates over the values in Items and calls the Save method for each of the TStoredValue instances. See TStoredValue.Save for more details.

Use RestoreValues to load the values for the collection items from the Storage container.

Loads all of the values for the collection Items from the Storage container for the collection.

RestoreValues is a method used to load the values in the collection Items from the Storage container for the collection. RestoreValues iterates of the values in Items and calls the Restore method for each of the TStoredValue instances. See TStoredValue.Restore for more details.

Use SaveValues to save the values for all of the collection items to the Storage container for the collection.

Storage container used to Save and Restore the Values for the collection Items.

Storage is a TCustomPropertyStorage property with the storage container used to save and restore the values for the Items in the collection. Storage contains the value passed as the Owner argument to the Create constructor, or Nil when the parameter is not derived from TCustomPropertyStorage.

TCustomPropertyStorage is an ancestor class which contains abstract virtual methods; normally, one of the descendent classes which implement a specific storage mechanism is used as the Owner. For example: TControlPropertyStorage, TFormPropertyStorage, TIniPropStorage, TJSONPropStorage, and TXMLPropStorage.

Storage is used when the SaveValues or RestoreValues method is called. The TStoredValue instances in Items access the property when they call their Save or Restore methods.

Provides indexed access to the TStoredValue collection items by their ordinal position.

Items is an indexed TStoredValue property with the items for the collection. It re-implements the internal list to use the TStoredValue type as the ItemClass for the collection.

Values in Items are accessed by their ordinal position in the list of collection items. The Read access specifier ensures that the inherited property value is cast to the TStoredValue type. The Write access specifier ensures that the property value is cast to the TCollectionItem type used in the inherited method.

Items is the default property for the class instance.

Use the Values and StoredValue properties to access a collection item by its name.

Ordinal position for the collection item used as the property value.
Provides indexed access to a TStoredValue instance in the collection by its name.

Values is an indexed TStoredValue property which provides access to a collection item with the name specified in the Name argument. The IndexOf method is called to locate the entry in Items matching the specified Name. The property value is Nil if Items does not contain a TStoredValue instance with the value in Name.

When saving a new value for the property, the Assign method in the collection item is called to update the property values for the TStoredValue instance.

Use the StoredValue property to access the String or Variant value for the collection item by its name.

Name for the collection item to retrieve from the Items property.
Provides indexed access to the value for a collection item with the specified name.

StoredValue is an indexed TStoredType property which provides access to the value for a collection item with the name specified in the Name argument. TStoredType allows the value to be represented as either a String or Variant type. See TStoredType for more information.

The IndexOf method is called to locate the collection item with the specified Name. If a collection item is not found, the property value can be either an empty string ('') (when TStoredType is AnsiString) or Null (when TStoredType is a Variant).

When writing the value for the indexed property, a new collection item is created in Items if a TStoredValue entry does not already exist with the specified Name.

Use the Values property to access a collection item instance by its Name. Use the Items property to access a collection item by its ordinal position.

Name for the collection item with the property value.
Links a storage object to a property collection.

TPropertyStorageLink is a TPersistent descendant which implements a class used to link a storage container to the collection and values read from and written to the storage. Not very useful by itself, Load/Save depends on installed handlers.

Invokes the OnSave handler.
Invokes the OnLoad handler.
Destructor for the class instance.

Destroy is the overridden destructor for the class instance. It ensures that references used in the OnLoad, OnSave, and Storage properties are set to Nil. Destroy calls the inherited destructor prior to exiting from the method.

Contains a reference to the storage contain used in the link.
Path to the root where values are stored in the Storage container.
Event handler signalled when all of the property values are stored.
Event handler signalled when all of the property values are loaded.
Defines a container used to Save and Restore property values.

TCustomPropertyStorage is a TComponent descendant which defines a storage container used to save and restore property values. It has a StoredValues property that is a collection with items containing the Names and Values read and written using the storage container.

TCustomPropertyStorage is a base class; it includes abstract virtual methods which must be implemented in a descendant to use a particular storage medium or format. For example: TControlPropertyStorage, TFormPropertyStorage, TIniPropStorage, TJSONPropStorage, and TXMLPropStorage.

The list of linked property collections.
True when everything has been saved.
True when everything has been restored.
Establishes a connection to a property collection.
Drops the connection to a property collection.
Notifies all connected property collections.
Gets the value for the Root property.
Value for the property.
Gets the path needed to represent the section for the Root (Owner) component.

RootSection is a String function which builds the path in the storage container where the property values are located.

RootSection uses the value in the Root property to determine the return value for the method. When Root is assigned and derived from TComponent, its Name or ClassName property is prepended to the return value. Preference is given to the value in its Name property.

Preceding Owner components are also examined and prepended to the return value. The value is complete when an Owner does not exist, or is not derived from TComponent.

The return value represents the component hierarchy used to access the property values in the storage container. The value is used in the SaveProperties and RestoreProperties methods to load property values from the underlying storage mechanism.

The Name or ClassName prefix for the Owner component, or an empty string when Root is not assigned.
Saves property values to the storage mechanism for the container.

SaveProperties is a method used to save property values from components and persistent objects to the storage mechanism for the container.

Existing values in the container are loaded on entry using the GetPropertyList and FinishPropertyList methods. A temporary TPropsStorage instance is created and configured to use the RootSection, Root, and Owner for the component instance. Its OnWriteString and OnEraseSection event handlers are set to the DoWriteString and DoEraseSections methods (respectively).

SaveProperties calls the StoreObjectsProps method in TPropsStorage to store the component and property names and values using the storage format for the container.

Some of the methods called in SaveProperties are declared as abstract virtual methods in TCustomPropertyStorage, like: GetPropertyList, FinishPropertyList, DoWriteString, and DoEraseSections. They must be implemented in a descendent class to use a specific storage format in its container.
TPropsStorage
Restores property values from the storage mechanism for the container.

RestoreProperties is a method used to load property values stored in the container, and apply the values to the origin components / persistent object instances. Properties names and the corresponding object instances are loaded using the GetPropertyList and FinishPropertyList methods.

A temporary TPropsStorage instance is created and configured to use RootSection and DoReadString from the class instance. The LoadObjectsProps method is called to get the property values and apply them to the object instances for the property list.

Some of the methods called in RestoreProperties are declared as abstract virtual methods in TCustomPropertyStorage, like: GetPropertyList, FinishPropertyList, and DoReadString. They must be implemented in a descendent class to use the specific storage format for its container.
TPropsStorage
Builds a list with the object(s) and properties stored in the container.

GetPropertyList is an abstract virtual method in TCustomPropertyStorage. It specifies the method used to populate the TStringList instance in List with the component / object properties stored in the container. The Names in the List argument contain the component and property names for the value. The Objects in the List argument contain a reference to the component instance that is the origin for the property value.

GetPropertyList must be implemented in a descendent class to ensure that the component and property names or values are valid for the storage format in the container.

GetPropertyList is used in the implementation of the SaveProperties and RestoreProperties methods.

TControlPropertyStorage
TStringList instance where names and the components / objects instance for the property values are stored.
Updates the specified list to include a reference to the object instance for each of the properties in the storage container.

FinishPropertyList ensures that a valid object reference exists for each of the property names loaded into the List argument using the GetPropertyList method. It ensures that the Objects property in List contains a valid reference to a TComponent instance for each of the component and property names in List.

Root identifies the initial component / object instance examined in the method. property named and values in List are relative to the component hierarchy starting at Root.

The ParseStoredItem routine from the RTL rttiutils unit is called to parse each of the values in the Names property in List into separate component and property names. If the value cannot be parsed into valid component and property names, the entry in List is deleted. If the component name is not the same as the value for Root, or one of its children, the value is also deleted from List.

The FindComponent method is called to get the object instance with the property value for a given component name. The references is stored in the Objects property for the corresponding component / property name.

FinishPropertyList is used in the implementation of the SaveProperties and RestoreProperties methods.

TStringList instance with the component and property names examined in the method.
Reads an integer value, stored as a string.
Default OnReadString handler; must be overridden.
The previously stored string.
The default value, when no string was stored.
Default OnWriteString handler; must be overridden.
The name of the section.
The name (key) of the property.
The value string to store.
Writes an Integer value as a String.
Must be overridden
Constructor for the class instance.

Create is the overridden constructor for the class instance, and calls the inherited method on entry. Create allocates resources needed for member variables in the class instance, and sets the default value for the Active property to True.

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

Destroy is the overridden destructor for the class instance. It calls the FreeStorage method to free any items in the collection, and frees the TStoredValues instance in the StoredValues property. TPropertyStorageLink instances in the internal list are freed, and the list itself is also freed. Destroy calls the inherited method prior to exit.

Saves all linked property collections.

Uses SaveProperties and StoredValues.SaveValues to do the actual work. At least one of these should be implemented.

All linked property collections are notified when everything has been stored, or to actually store their values.

The OnSavingProperties handler is invoked before the properties are stored, OnSaveProperties afterwards.

Restores all linked property collections.

Uses RestoreProperties and StoredValues.RestoreValues to do the actual work. At least one of these should be implemented.

All linked property collections are notified, when everything has been restored, or to actually restore the values.

The OnRestoringProperties handler is invoked before the properties are restored, OnRestoreProperties afterwards.

Ensures that the storage mechanism for the container is available.

StorageNeeded is a method used to ensure that the underlying storage mechanism for the container has been allocated and configured. StorageNeeded has an empty implementation in TCustomPropertyStorage. It must be overridden in a descendent class to use the format and access mechanism needed.

The ReadOnly argument indicates whether write access is enabled for the storage. In general, the Save method requires write access and the Restore method does not.

Frees resources allocated for the underlying storage mechanism.

FreeStorage is a method used to free resources allocated for the underlying storage mechanism for the container in StorageNeeded. FreeStorage has an empty implementation in TCustomPropertyStorage, and must be overridden in a descendent class.

Reads an Boolean value, stored as a string.
Value read in the method.
Identifier for the value read in the method.
Default value used when the specified identifier is not found.
Reads an String value from the RootSection.
String value read in the method.
Identifier for the value read in the method.
Default value used when the specified identifier is not found.
Reads an integer value, stored as a string, from the RootSection.
Value read in the method.
Identifier for the value read in the method.
Default value used when the identifier is not found.
Reads an TRect instance stored as a String value.
Identifier for the value read in the method.
TRect instance where the value is stored.
Default value used when the specified identifier is not found.
Reads a list of strings, stored with a Count value.
The name of the list property.
The list to which the strings are added.
A list of default values, used when nothing was stored yet.
Writes a String to the RootSection.
Identifier for the value.
String value written in the method.
Writes an integer into the RootSection.
Identifier for the value.
Integer value written in the method.
Writes a Boolean value to the RootSection.
Identifier for the value.
Boolean value written in the method.
Writes an TRect instance to the RootSection.
Identifier used for the rectangle values.
TRect instance written in the method.
Writes a list of strings into the RootSection.
Identifier used for the string values.
TStrings instance with the values written in the method.
Removes all sections that are descendants of the specified root section.
Provides indexed access to the value for a collection item by its name.

StoredValue is an indexed TStoredType property which provides indexed access to the value for a collection item by the name specified in AName. Read and write access is redirected to the StoredValue property in the StoredValues collection.

Name of the collection item with the value for the property.
Path where values in the storage container are rooted.
Indicates whether the container is Active and allows access to its storage.

Active is a Boolean property which indicates if the container can access its underlying storage mechanism. In TCustomPropertyStorage, the default value for the property is True.

Active is used in the Save and Restore methods, and controls whether the corresponding actions can be performed using the collection items and storage for the container.

Collection with the names and values for properties handled for the container.

StoredValues is a TStoredValues property with the collection of names and values for properties handled by the storage container. StoredValues is used in the Save and Restore methods when the collection items are read or written using the underlying storage mechamism for the container. It is also used to read or write the value for the indexed StoreValue property.

Event handler signalled when the Save method is started.

OnSavingProperties is a TNotifyEvent property with the event handler signalled when the Save method is started. It is signalled (when assigned) after the StorageNeeded method has been called, and before collection values in StoredValues are written using SaveProperties.

Event handler signalled when the Save method is completed.

OnSaveProperties is a TNotifyEvent property with the event handler signalled when the Save method is completed. It is signalled (when assigned) after the OnSavingProperties event handler. Values for collection items in StoredValues have already been written using SaveProperties when the event handler is called.

Event handler signalled when the Restore method is started.

OnRestoringProperties is a TNotifyEvent property with the event handler signalled when the Restore method is started. It is signalled (when assigned) after the StorageNeeded method has been called , and before values for the collection items are read and applied using StoredValues and RestoreProperties.

TNotifyEvent
Event handler signalled when the Restore method is completed.

OnRestoreProperties is a TNotifyEvent property with the event handler signalled when the Restore method is completed. OnRestoreProperties is signalled (when assigned) after the OnRestoringProperties event handler has been signalled, after property values have been read using RestoreProperties, and after the values have been loaded in the StoredValues collection.

TNotifyEvent