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's available on Misc tab of the Component Palette.

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 - in this case the properties are stored in the folder of the executable with the name of the project and with extension .xml.
• 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 properyt 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.

See also

• TIniPropStorage
• TJsonPropStorage

StoredValues property

TINIPropStorage and TXMLPropStorage have a StoredValues property which stores some value (it's useful to use no other config file).

Some properties (as CheckGroup.Item[n].Checked) cannot be saved in SessionProperties of TForm, you need to do this manually. It's useful to save other setting information too.

Let's write a simple demo:

• Run Lazarus and start a new application;
• Drop a TXMLPropStorage and TCheckGroup component;
• Add one item in TCheckGroup (Item Test);
• Click in XMLPropStorage1 and access StoredValues property editor;
• Add a new value with name = item0_checked and value = -1 (True = -1);
• In the OnRestoreProperties event add this code:

CheckGroup1.Checked[0] := StrToBool(XMLPropStorage1.StoredValue['item0_checked']);

• In the OnSavingProperties event add this code:

XMLPropStorage1.StoredValue['item0_checked'] := BoolToStr(CheckGroup1.Checked[0]);

• Run the demo program, change checked property of TCheckGroup.Items[n] and close form. Your changes was saved? :)

You can change Key property of StoredValues.Items[n] if you're saving some information confidential (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 depeding 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

• TXMLPropStorage doc
• SessionProperties doc
• Hardware Access