Using the cxPropertiesStore component
- 6 minutes to read
When writing a complex application with a large number of settings, you may need to restore component properties. The ExpressQuantumGrid Suite provides the cxPropertiesStore component implementing this functionality.
By default, the cxPropertiesStore component allows restoring settings upon application creation and saving settings upon application shutdown. Of course, you can perform saving/restoring whenever you like. This topic covers all aspects of the cxPropertiesStore functionality.
Let’s consider the use of cxPropertiesStore. This topic contains two examples of using cxPropertiesStore – at design time and via code. The cxPropertiesStore will be used to save/restore cxGrid properties.
Perform the following steps to follow the examples of this topic. Create an empty application. Place a cxGrid component on a form. Create a table view and bind it to the Films table from the VideoCatalodDB.mdb demo database. Setup the grid control as described in the table view tutorial. Next, add another level with an associated table view, name them lvFilmsCheck and tvFilmsCheck and repeat the tutorial steps for the new view. Place the cxPropertiesStore component on the form and name it cxStore. The result is shown by the following screenshot:
- DESIGN TIME USAGE
This chapter shows how to use cxPropertiesStore at design time and describes its default functionality. This implies that the settings are saved when the application is closed and restored when it is restarted. The example will operate on the settings of the tvFilms view and the tvFilmsCOLOR & tvFilmsYEAR columns.
Double-click on the cxPropertiesStore component’s icon. This invokes the PropertiesStore Editor:
The editor displays a tree structure of all the components residing on the form containing the cxPropertiesStore. The Editor buttons’ functions are listed below:
| Button | Function |
|---|---|
 |
Groups the Editor tree by components. |
 |
Groups the Editor tree by properties. |
 |
Restores the last saved selection. The current Properties/components grouping option is saved when the dialog is closed (by pressing the OK button). |
 |
Selects all components/properties within the tree. |
 |
Clears all selected rows. |
 |
Inverts row selections. If you need to select most items, select just the ones you don’t need and then click on this button. |
Click the plus sign next to the cxGrid component and examine the properties available:
You can select all the component’s properties you want to save/restore by right-clicking the component name within the tree. The following image demonstrates how to select all the properties of the tvFilmsYEAR and tvFilmsCOLOR columns:
Also, you can select individual component properties by right-clicking these property names within the tree. The following image demonstrates how to select the tvFilms view options:
Having selected the required components and their properties, you need to specify the StorageType and StorageName property values. For the purposes of this example, set the StorageType property value to stRegistry and the StorageName property value to “View Storage”:
This tells the cxPropertiesStore component to store settings within the registry in the View Storage key.
Ensure that the Active property of the cxPropertiesStore component is set to True. Otherwise, cxPropertiesStore will not save/restore the selected settings automatically.
Run the application. Ungroup the tvFilms and tvFilmsCheck views by dragging the Release Year column header to the column panel.
Close the application and run it again. Runtime changes are restored for the tvFilms view and its columns. The tvFilmsCheck view appears with the design time settings, because its properties were not selected for saving.
The following screenshot demonstrates the View Storage registry key structure:
Another way of selecting the properties for saving/restoring is by using the Components property. Select the cxPropertiesStore component. Invoke the Object Inspector and click the ellipsis button next to the Components property. This invokes the Components collection editor:
This collection contains references to all components, which you have previously selected. Select the first component reference (corresponding to the tvFilms view) and switch to the Object Inspector. Click the ellipsis button next to the Properties property. This displays the list of properties selected for saving/restoring:
Go to the “OptionsCustomize” line and add the ColumnGrouping options name, by changing the line to “OptionsCustomize.ColumnGrouping”:
The following screenshot demonstrates the result of saving after this change:
As you can see, now only the ColumnGrouping option value is saved instead of the whole OptionsCustomize set.
You can also save/restore properties at design time. For this purpose, select the required properties via the cxPropertiesStore editor. Then right-click the cxPropertiesStore component and choose the Save or Restore item from the context menu:
The StorageType and StorageName properties specify the storage used for design time saving/restoring.
- USING VIA CODE
This chapter describes how to use cxPropertiesStore by code and this approach provides more flexibility. There are two features of cxPropertiesStore only available when writing code:
Saving/restoring individual components from the Components collection.
Saving/restoring individual Components items from a storage, different from the one specified by the StorageType and StorageName properties.
The code below handles the OnCreate event of the form to save the properties of a footer summary item. It selects the Column, Kind and Format properties of the first footer summary item for saving. The Active property must be set to False before saving is performed. This disables the default functionality of the cxPropertiesStore component. Saving is implemented Call the StoreToIniFile method to save the required item of the Components collection. Note that this method saves footer summary item properties to an INI file, though the StorageName and StorageType properties of the cxStore component specify a registry key as a storage. The RestoreButtonClick event handler restores the footer summary item settings by calling the RestoreFromIniFile method:
var
PSComponent: TcxPropertiesStoreComponent;
//...
procedure TForm1.FormCreate(Sender: TObject);
begin
//disabling the default functionality of the cxPropertiesStore component
cxGridStore.Active := False;
//adding an item to the Components collection
PSComponent := TcxPropertiesStoreComponent(cxGridStore.Components.Add);
with PSComponent do
begin
//setting a table view for saving
Component := tvFilms;
//selecting the Column, Kind and Format property values of the first footer summary item for saving
Properties.Add('DataController.Summary.FooterSummaryItems.0.Column');
Properties.Add('DataController.Summary.FooterSummaryItems.0.Kind');
Properties.Add('DataController.Summary.FooterSummaryItems.0.Format');
//saving the selected properties to an INI file (note that design time settings designate the registry key as a storage). The storage file is recreated upon saving
StoreToIniFile('c:\store.ini', True);
end;
end;
//...
procedure TForm1.RestoreButtonClick(Sender: TObject);
begin
//restoring the footer summary item settings without involving any other Components collection items
PSComponent.RestoreFromIniFile('c:\store.ini');
end;
//...
The result of the code execution (store.ini file contents) is demonstrated below:
[tvFilms: TcxPropertiesStoreComponent]
=
DataController.Summary.FooterSummaryItems.0.Column=tvFilmsRUNTIME
DataController.Summary.FooterSummaryItems.0.Kind=skMax
DataController.Summary.FooterSummaryItems.0.Format=MAX=0 minutes