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.
- Drop a TXMLPropStorage component on form and set filename property, for example: session.xml
- Select form, go to Object Inspector and open editor window for the SessionProperties property of TForm.
- Add here properties of form and/or controls to be stored inside session.xml. It must be ";"-separated property names, also sub-properties dot-separated are allowed. Example: "Width;Height;Image1.Width".
- Compile the application.
Your application now will read selected property value from session.xml and apply it on runtime (like Width, Height, Left, Top for TForm).
TINIPropStorage component works the same way as TXMLPropStorage, except it stores the session information in an IniFile.
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 := StrToBool(XMLPropStorage1.StoredValue['item0_checked']);
- In the OnSavingProperties event add this code:
XMLPropStorage1.StoredValue['item0_checked'] := BoolToStr(CheckGroup1.Checked);
- 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.
Restorein the frame's constructor and
Savein 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;
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."