TcxCustomTreeList.RestoreFromIniFile(string,Boolean,Boolean,string) Method

Restores TreeList-specific information from an INI file.

Declaration

procedure RestoreFromIniFile(const AStorageName: string; AChildrenCreating: Boolean = False; AChildrenDeleting: Boolean = False; const ARestoreTreeListName: string = '');

Parameters

Name	Type
AStorageName	string
AChildrenCreating	Boolean
AChildrenDeleting	Boolean
ARestoreTreeListName	string

Remarks

Use the RestoreFromIniFile method to restore TreeList-specific information from an INI file. Restoring the TreeList structure can be useful after changes have been applied to the TreeList control. Before restoring the TreeList structure, ensure that the control contains all columns connected to dataset fields at the time when data was saved to the INI file.

Stored structure information includes: instance names, band and column settings. Stored elements’ (bands and columns) settings specify the position and visibility of elements, captions, sort order, data binding, etc.

The AStorageName parameter specifies the INI file path and name.

The AChildrenCreating parameter determines whether non-existent TreeList elements (bands and columns) present within an INI file are created within the control. On the contrary, the AChildrenDeleting parameter determines whether existing TreeList elements not present within the INI file are deleted when restoring.

The ARestoreTreeListName parameter corresponds to the ASaveTreeListName parameter of the storing procedure.

If ASaveTreeListName is set to an empty string, the storing procedure saves the current tree list’s name to a data store. Use this mode to store settings of a tree list, and then restore them in the same tree list. Columns are also saved by their names. If multiple columns with unassigned names are saved, only the settings of the last unnamed column will be persisted.

If the ASaveTreeListName parameter of the storing procedure specifies a non-empty string, the current tree list’s name is ignored and TreeList settings are stored under the specified name. This mode allows you to save settings of one tree list and then apply them to (restore in) another tree list. To enable this mode, you have to set the ARestoreTreeListName parameter to the same value as ASaveTreeListName in the storing procedure.

In this mode, columns are stored by their IDs. ID is a unique zero-based identifier that is assigned to a column when it’s created at runtime. The ID of the first column is 0, the ID of the second one is 1, etc. When a column is deleted, a newly created column might get the ID of the deleted column. So, the IDs of columns won’t be reused within the current state of the tree list, but may be reused within the lifetime of the tree list. This is a limitation unique to these IDs.

The restoring procedure recognizes columns by their IDs, i.e. if the data store contains settings for columns with IDs equal to 0, 1, and 4, for instance, they are applied to the columns in the current tree list with the same IDs (0, 1,and 4). Non-existing columns are created/deleted based on the AChildrenCreating and AChildrenDeleting parameter values. Note that the tree list, to which settings are applied, must be connected to the same dataset as the original tree list.

Note

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