Example: TcxCustomGridView.OnGetStoredProperties, TcxCustomGridView.OnGetStoredPropertyValue, TcxCustomGridView.OnSetStoredPropertyValue, TcxCustomGridView.OnInitStoredObject
- 5 minutes to read
The ExpressQuantumGrid allows you to save the View’s layout to a number of external data stores and restore it later. This example shows how to persist the Banded Table View layout to an INI file.
The example assumes that a form contains a Banded Table View named BandedTableView. To save the View’s properties in an INI file, we will use the StoreToIniFile procedure using the default options. ‘BandedTableViewProperties.ini‘ is the file name specified for the INI file.
Later, the View’s properties will be restored from the BandedTableViewProperties.ini file using the following code.
The list of properties that will be saved in an external data store needs to be customized as only a few of the View’s properties are saved by default. Whenever the store procedure (StoreToIniFile, StoreToRegistry, StoreToStorage, or StoreToStream) is called a list of the properties that will be saved is created. When the list is complete (it contains all the View properties that are saved by default), the OnGetStoredProperties event is fired.
At this point you can easily customize the list, if required. For instance, let us add the properties which control the appearance of the indicator panel in a View, the Indicator and IndicatorWidth. In addition to that, we will prevent the saving of unwanted properties, in this case a property which controls the visibility of the footer panel and is named ‘Footer‘.
Let us add the OnGetStoredProperties event handling procedure and name it ‘GetStoredProperties‘. The names of properties to be stored are contained in a list passed as the AProperties parameter. Adjust the list as shown below.
procedure TForm1.GetStoredProperties(Sender: TcxCustomGridView; AProperties: TStrings);
begin
AProperties.Add('Indicator');
AProperties.Add('IndicatorWidth');
AProperties.Delete(AProperties.IndexOf('Footer'));
end;
The properties to save in the INI file have been specified, but the actual View to which the Indicator and IndicatorWidth properties correspond has not been. Now it is time to define the link between them. To accomplish this, handle the OnGetStoredPropertyValue event, which is fired when the property’s values are stored in an external data store (an INI file in this case).
Let us add the handling procedure for this event and name it ‘GetStoredPropertyValue‘. In the following code we assign the actual properties’ values to the stored properties according to their names. Nothing needs to be done here for the Footer stored property as we previously removed it from the list of the properties that will be saved.
procedure TForm1.GetStoredPropertyValue(Sender: TcxCustomGridView;
const AName: String; var AValue: Variant);
begin
if AName = 'Indicator' then
if Sender is TcxGridTableView then
begin
AValue := TcxGridTableView(Sender).OptionsView.Indicator;
Exit;
end;
if AName = 'IndicatorWidth' then
if Sender is TcxGridTableView then
begin
AValue := TcxGridTableView(Sender).OptionsView.IndicatorWidth;
Exit;
end;
end;
As a result, the BandedTableViewProperties.ini file will contain only the View properties (names and values) that we specified. To restore these properties with the values stored in an external data store (a file in this case), we have to perform the reverse operation, i.e. initialize the View’s properties with the stored property’s values. When the restoration is started, the OnSetStoredPropertyValue event is fired for the View. Add a handling procedure for this event and name it ‘SetStoredPropertyValue‘. In the following code we reassign the stored properties’ values to the actual View properties according to their names, thus restoring them.
procedure TForm1.SetStoredPropertyValue(Sender: TcxCustomGridView;
const AName: String; const AValue: Variant);
begin
if AName = 'Indicator' then
if Sender is TcxGridTableView then
begin
TcxGridTableView(Sender).OptionsView.Indicator := AValue;
Exit;
end;
if AName = 'IndicatorWidth' then
if Sender is TcxGridTableView then
begin
TcxGridTableView(Sender).OptionsView.IndicatorWidth := AValue;
Exit;
end;
end;
Since the View store process includes storing the complete set of the View properties along with the properties of the grid View elements (columns, Card View rows, bands) which are owned by the View, appropriate events are also fired for these elements thus enabling you to completely customize the entire storing process.
In order to tweak the storing of the grid column or card row properties, use the following events: Item.OnGetStoredProperties, Item.OnGetStoredPropertyValue and Item.OnSetStoredPropertyValue.
For band properties in Banded Table Views use the following events:
Band.OnGetStoredProperties, Band.OnGetStoredPropertyValue and Band.OnSetStoredPropertyValue.
The property storing and restoring customization process for columns and bands is similar to the customization process for a View.
Important
When a grid View element such as a band, column or card row is restored from an external data store within the View where the object that corresponds to the element is destroyed, the element is re-created and thus the object requires that its events are re-associated with existing event handlers. This can be accomplished by handling the OnInitStoredObject event.
The following code represents the OnInitStoredObject event handler and demonstrates how to re-associate the events of all the columns (no specific identification is made) whose property storing and restoring is customized by handling the Item.OnGetStoredProperties, Item.OnGetStoredPropertyValue and Item.OnSetStoredPropertyValue events with existing event handlers (the colGetStoredProperties, colGetStoredPropertyValue and colSetStoredPropertyValue procedures, respectively).
procedure TForm1.InitStoredObject(Sender: TcxCustomGridView; AObject: TObject);
begin
if AObject is TcxGridBandedColumn then
with TcxGridBandedColumn(AObject) do
begin
OnGetStoredProperties := colGetStoredProperties;
OnGetStoredPropertyValue := colGetStoredPropertyValue;
OnSetStoredPropertyValue := colSetStoredPropertyValue;
end;
end;