TcxCustomGridView.RestoreFromIniFile(string,Boolean,Boolean,TcxGridStorageOptions,string,string) Method

Restores View-specific information from an INI file.

Declaration

procedure RestoreFromIniFile(const AStorageName: string; AChildrenCreating: Boolean = True; AChildrenDeleting: Boolean = False; AOptions: TcxGridStorageOptions = [gsoUseFilter, gsoUseSummary]; const ARestoreViewName: string = ''; const AOwnerName: string = '');

Parameters

Name	Type
AStorageName	string
AChildrenCreating	Boolean
AChildrenDeleting	Boolean
AOptions	TcxGridStorageOptions
ARestoreViewName	string
AOwnerName	string

Remarks

Use the RestoreFromIniFile method to restore the View-specific information from an INI file. Restoring the View structure can be useful after changes have been applied to a View. Before restoring the View structure, ensure that the View is connected to a data set containing fields assigned to the same View items as saved in the INI file. Use the StoreToIniFile method to save View settings to an INI file.

View structure information includes:

• View class and instance names;

• View element settings. These settings include only those settings that can be adjusted by end-users: the position, size, and visibility within a View, sort order, etc.

The AStorageName parameter specifies the path and name of the INI file.

The AChildrenCreating parameter determines whether non-existent View elements that are present within an INI file are created within the View (this is done by default). On the contrary, the AChildrenDeleting parameter determines whether existing View elements that are not present within the INI file are deleted during restoring. Affected View elements include:

• Bands, columns, and summary items in Table Views and Banded Table Views;

• Card rows in Card Views;

• Data items, layout groups, and auxiliary layout elements (empty regions, separators, and labels) in Layout Views;

• Data groups and series in Chart Views.

The AOptions parameter includes a set of options controlling whether the current filter and/or summaries should be restored. By default, summaries and filter settings are restored from the INI file. Although the restore procedure allows you to recreate columns which have been deleted or which were not present in the View, summaries and filter settings for these columns cannot be restored correctly.

The ARestoreViewName parameter corresponds to the ASaveViewName parameter of the store procedure.

If ASaveViewName is set to an empty string, the store procedure saves the current View name in the storage. Use this mode to store settings of a single View and then restore them in the same View. Items are also saved by their names. If multiple items with unassigned names are saved, only the settings of the last unnamed item will be persisted.

If the ASaveViewName parameter of the store procedure specifies a non-empty string, the current View name is ignored and the View settings are stored under the specified name. This mode allows you to save settings of one View and then apply them to (restore in) another View. To enable this mode, you have to set the ARestoreViewName parameter to the same value as ASaveViewName in the store procedure.

Items in this mode are stored by their IDs. ID is a unique identifier assigned to an item. When you run the program, all items within a View are assigned unique zero-based IDs that provide the unique identity of the items. The ID of the first item is 0, the ID of the second one is 1, etc. When an item is deleted, a newly created item might get the ID of the deleted item. Thus the IDs of items won’t be reused within the current state of the View, but may be reused within the lifetime of the View. This is a limit unique to these IDs.

The restore procedure recognizes View items by their IDs, i.e. if the storage contains settings for items with IDs equal to 0, 1, and 4, for instance, they are applied to the items in the current View with the same IDs (0, 1, and 4). Note that the View, to which settings are applied, must be connected to the same dataset as the original View.

AOwnerName specifies the form that owns the grid. Use this parameter when developing MDI applications.

To learn more, refer to the example.

To customize the list of the View’s properties which are restored from an INI file, handle the OnSetStoredPropertyValue event.

Note

You can handle the OnInitStoredObject event to properly initialize the object which corresponds to the re-created View element (provided that the RestoreFromIniFile method is called with True passed for the AChildrenCreating parameter) by re-associating its events with existing event handlers and assigning its properties.