TXMLPropStorage

│ Deutsch (de) │ English (en) │ español (es) │ français (fr) │ polski (pl) │ português (pt) │ русский (ru) │

TXMLPropStorage is a component to save and restore selected properties (either TForm or any control on it). It works with the TForm.SessionProperties property. It is available on the Misc tab of the Component Palette.

Basic Usage

• Drop a TXMLPropStorage component on the form and set the Filename property as needed, for example: session.xml. The FileName even can be left empty - see below.
• Select the form, go to the Object Inspector and select the property SessionProperties. There are two ways to enter here the properties to be stored:

1. Click on the ellipsis button '...' next to the property to open the SessionProperties editor. The components of the form are displayed in the left list "Components". Select the first component for which you want to store a property - the published properties of the selected component appear in the right list, "Properties". Select here the property to be stored and click "Add". Now the property is listed in the bottom listbox, "Selected Properties". Repeat with other properties of the selected component, and repeat with other components. If you changed your mind and want to removed one specific property from the "Selected Properties" list, select it and click "Delete". "Clear" deletes the entire "Selected Properties" list.
2. The selected properties are displayed as a semi-colon separated string in the SessionProperties line of the Object Inspector. Instead of using the SessionProperties editor you can also type here the names of the properties to be stored. Subproperties or properties of components on the form must be listed in dot-notation. Example: Width;Height;Image1.Width.

• Compile and run the application. Your application now will store the selected properties in the session file when the application terminates, and it will read them when it is restarted another time and it will apply them automatically at runtime.

The TINIPropStorage and TJsonPropStorage components work in the same way as TXMLPropStorage. The only difference is that they store the session information in an IniFile or a JSON file, respectively.

StoredValues property

TXMLPropStorage has a StoredValues property which allows to store non-published properties or other values; this can be useful to avoid an additional configuration file.

Let's write a simple demo which uses a TCheckGroup. It has a Checked[index] property with the information whether the item at the given index is checked or not. This property, however, is only public and thus is not seen by the automatic storage mechanism of the PropStorage components considering only published properties. By means of the StoredValues property of TXMLPropStorage, however, this can be done manually:

• Run Lazarus and start a new application.
• Drop a TXMLPropStorage and TCheckGroup component.
• Add some items to the TCheckGroup.
• Click in XMLPropStorage1 and access the StoredValues node in the object tree above the object inspector.
• Right-click on this node and select "Add item" to add new value with an arbitrary, but unique Name (e.g. CheckGroup1.Item0_Checked) and the corresponding initial <tt<Value = true. Repeat accordingly with the other items.
• In the OnRestoreProperties event add this code:

  CheckGroup1.Checked[0] := StrToBool(XMLPropStorage1.StoredValue['CheckGroup1.Item0_Checked']);
  CheckGroup1.Checked[1] := StrToBool(XMLPropStorage1.StoredValue['CheckGroup1.Item1_Checked']);

• In the OnSavingProperties event add this code (do NOT use the OnSaveProperties!):

  XMLPropStorage1.StoredValue['CheckGroup1.Item0_Checked'] := BoolToStr(CheckGroup1.Checked[0], true);
  XMLPropStorage1.StoredValue['CheckGroup1.Item1_Checked'] := BoolToStr(CheckGroup1.Checked[1], true);

• Run the demo program, change the checked properties of the CheckGroup, close the form and re-open it. Your changes are saved and restored!

You can set a value for the KeyString property of StoredValue[n] if you're saving some confidental information (it uses XOREncode and XORDecode functions of RTL on saving and restoring routines).

Property Storage on Frames

The TXMLPropStorage works only on forms by default. To use it on frames, some manual coding has to be done.

• Place a TXMLPropStorage on the frame.
• Set the property RootNodePath to something like TApplication/Frame1. Without setting this property, TXMLPropStorage won't find the saved values upon loading. If you want to reuse the frame multiple times and save the diffrent settings, you should set this in the frame's constructor depending on the situation.
• Set the property SessionProperties of the frame in the frames constructor.
• Call Restore in the frame's constructor and Save in the frame's destructor.

constructor TFrame1.Create(TheOwner: TComponent);
begin
  inherited Create(TheOwner);
  SessionProperties := 'Panel1.Width;Panel3.Width';
  XMLPropStorage1.RootNodePath := 'TApplication/Frame1'; // if the frame is used multiple times and shall not share their settings, set an individual value for each instance
  XMLPropStorage1.Restore;
end;

destructor TFrame1.Destroy;
begin
  XMLPropStorage1.Save;
  inherited Destroy;
end;

Notes

TXMLPropStorage has a default handler if you don't set a FileName.

• Under Windows the settings will be saved in the application directory as PROGRAMNAME.xml.
• Under Unix/Linux/macOS it will be saved in the home directory of the current user as .PROGRAMNAME

It is therefore a very good idea to leave the filename blank for unix programs meant to be run by normal users.

According to bug report 13949, note 28856: "The StoredValues[] array can only be used during the OnRestoreProperties or OnSaveProperties events. Outside these events, the values will not be stored." and "If you want to save/load values that are not published properties of a component or control, you should save them in a OnSaveProperties event, and load them using the OnRestoreProperties event."

See also

• TINIPropStorage
• TJsonPropStorage
• TXMLPropStorage doc
• SessionProperties doc