Storage Library - Usage
The TrsStorage component creates a tree-like structure and saves it into the memory. This structure can contain data of various types. The TrsStorage data organization is very similar to the Windows registry data organization. Sections and Keys are the basic elements of the tree-like structure. Each Section has a name and can contain an unlimited number of Sub-sections and Keys. Each Key has a name and a value. Each Section name (as well as each Key name) is unique within a parent section.
The initial value of the Active property of TrsStorage is set True. In this case, if a TrsStorage component is linked to any of the TrsStorageData components, the data will be loaded from an external source. If the Active property is set True in the DesignTime mode, the appropriate properties of a corresponding TrsStorage component allow for automatic data loading when the user application is running. The TrsStorage.Save call method allows for data saving. The TrsStorage.Options value is set soSaveOnClose (the default value) to provide automated data saving. After this, the data will be saved automatically at Active=False or after the program termination.
Working with sections
RootSection is the basic property of TrsStorage. It allows the user to know or set the current Section. The use of TrsStorage is based on the current Section. For example, the SectionAdd method allows the user to add a Sub-section to the current Section. The SectionDelete method deletes a Sub-section from the current Section. The SectionExist function returns True if the current Section has a corresponding Sub-section. The SectionList method fills up the TStrings class with a list of Sub-sections of the current Section. The ChangeDownRootSection and ChangeUpRootSection methods also allow the user to change the current Section. An attempt to set a non-existing Section as the current Section results in automatic creation of this Section.
Working with Keys
After the current Section is set, it is possible to use the Keys of this Section. The KeyDelete, KeyExist, KeyList, and KeyCount methods are used for this purpose. Assignment of a value to a Key results in automatic creation of this Key. The ReadXXX and WriteXXX methods (where XXX can be Boolean, Buffer, Component, Currency, DateTime, Float, Int64, Integer, Persistent, Point, Stream or String) are used to read/write the value of a Key. The default value is used as a parameter in ReadXXX functions: it will be returned if a Key does not exist. In addition, the Values property allows one to return the Key value. In this case, the Key value is returned as a variant-type variable. A variant-type variable is also used for Key value assignment.
The TrsIniData component is used for data exchange between a TrsStorage component and an .ini file. The file name is set in the FileName property. The following service options of the Options property are available:
- doAutoName - Allows to use exe file name for name of ini file. The ini file name specified in FileName is ignored.
- doAutoPath - Allows to search for an ini file in the folder containing the current exe file. The directory specified in the FileName is ignored.
FileName:=''; Options:=[doAuthoPath,doAutoName] - the folder with the exe file, the name of the exe file, the file name extension is ini (the default value).
FileName:='.dat'; Options:=[doAutoPath,doAutoName] - the folder with the exe file, the name of the exe file, the file name extension is dat.
FileName:='demo.dat'; Options:=[doAutoPath] - the folder with the exe file, the name of the exe file, the file name is 'demo.dat'.
The TrsBinData component is similar to TrsIniData, except for the following: the data exchange takes place between TrsStorage and a special format file. This format was designed exclusively for the Storage Library and it allows for fast data reading/writing. The default file name extension for this file is 'bin'.
The TrsRegData component is designed for the data exchange between the TrsStorage component and the Windows registry. The RootKey property sets the root key in the registry, and the RootPath property sets the registry key where the data will be stored, for example:
RootKey := rkLocalMachine;
RootPath := 'software\companyname\productname\version';
The TrsXMLData component is similar to TrsIniData, excepting the following points: the data exchange takes place between TrsStorage and an XML file. The default file name extension of this file is 'xml'.
The TrsPropSaver component is designed for automated storage of published properties of other components, located on the same form as TrsPropSaver. In addition, TrsPropSaver allows for saving the position and state of this form, user data and unpublished properties of other components. All data from a component of TrsPropSaver are stored in a section of TrsStorage. The section name is set in TrsPropSaver.RootSection. If several TrsPropSaver components are in use in an application, RootSection of each TrsPropSaver component has to be unique. The TrsPropSaver is controlled with a dialog box, in DesignTime mode. This dialog box allows the user to select published properties of other components which have to be saved, to create user properties whose values will be read/written via the TrsPropSaver events. If the TrsCustomProperties component settings are correct, one can select custom properties to be obtained via TrsCustomProperties components. In this dialog box, user and custom properties are shown in different colors.
The user properties are in green, the name is set manually. While the data are loading and the program is running, the OnSetUserProperty event takes place. The OnGetUserProperty event takes place before the data storage. The handlers of these events have to contain a program code designed for the user properties use.
The custom properties are shown in blue. The events related to getting and setting the custom properties are in the TrsCustomProperties component. Thus, the same code, designed for unpublished properties processing, is used in all TrsPropSaver components.
The TrsCustomProperties component is designed for unification of use of unpublished properties in all TrsPropSaver components. To develop a handler for unpublished properties, the following properties must be set:
- The PropClass property for which the handler has to be developed;
- The PropName property which is visualized in the "property selection" dialog (TrsPropSaver component);
- The InDescendants property which determines whether it is possible to use this property in descendants from PropClass;
- The handlers of the OnGetProperty and OnSetProperty events also must be developed.