TcxCustomTreeList.RestoreFromStream(TStream,Boolean,Boolean,string,TcxTreeListStorageOptions) Method
Restores a previously saved Tree List state from a stream.
Declaration
procedure RestoreFromStream(AStream: TStream; AChildrenCreating: Boolean = False; AChildrenDeleting: Boolean = False; const ARestoreTreeListName: string = ''; AOptions: TcxTreeListStorageOptions = []);
Parameters
Name | Type | Description |
---|---|---|
AStream | TStream | The source stream that contains previously saved Tree List state information at the current position. |
AChildrenCreating | Boolean | Optional. Specifies if the procedure creates missing Tree List structure elements (bands and columns):
If the current Tree List element structure matches the loaded state, the |
AChildrenDeleting | Boolean | Optional. Specifies if the procedure deletes redundant Tree List structure elements (bands and columns):
If the current Tree List element structure matches the loaded state, the |
ARestoreTreeListName | string | Optional. Specifies the restored Tree List name. This parameter allows you to apply a saved Tree List state to a different Tree List control. If the number of columns in the target control does not match the loaded structure, the |
AOptions | TcxTreeListStorageOptions | Optional. Specifies a set of individual user interaction states restored from the source stream ( If this parameter is omitted, the procedure loads only Tree List structure information, even if the source stream contains user interaction state information. |
Remarks
Call the StoreToStream procedure to save the current data layout and specified user interaction states to a stream. A subsequent RestoreFromStream
call restores the saved Tree List state from the stream.
Stored Information
Tree List Structure | Data Layout
Tree List structure information includes the following:
- Tree List name
- All Tree List element settings available to end users for customization: position, dimensions, visibility, sort order, captions, etc. You can use optional
AChildrenCreating
andAChildrenDeleting
parameters to update the current Tree List element structure according to the loaded state.
Important
After each StoreToStream procedure call, make sure that the Tree List control maps to the same underlying dataset fields before the corresponding RestoreFromStream
call. Otherwise, errors may occur.
Tree List User Interaction States (Optional)
In addition to the base Tree List Structure/Data Layout, the AOptions
parameter available for StoreToStream and RestoreFromStream
procedures allows you to store a number of user interaction states (selection, focus, scroll position, node expanded status, etc.)
Pass a set of all required flags as the AOptions
parameter to store/restore corresponding Tree List user interaction states:
- tsoUseDataViewState
The main flag required for all other user interaction flags listed below. These flags have no effect without tsoUseDataViewState.
Tip
Alternatively, you can use only the cxTreeListStoreAllDataViewStates constant if you need to store all user interaction states for the Tree List as demonstrated in the code example below.
- tsoFocusedItem | tsoFocusedRecord
- Store/restore the focus position.
- tsoSelected
- Stores/restores selection.
- tsoTopRecord
- Stores/restores the Tree List scroll position (the record at the top control border).
- tsoExpanded
- Stores/restores the expanded status for all nodes.
Code Example: Store Tree List State Between Sessions
The code example in this section demonstrates form OnDestroy and OnCreate event handlers. These handlers call StoreToStream and RestoreFromStream
procedures to save and restore user interaction states (selection, focus, scroll position, etc.) in addition to the Tree List structure/data layout.
uses
System.SysUtils, // Declares the FileExists function
cxTL, // Declares TcxTreeList, TcxCustomTreeList, and related types
// ...
procedure TMyForm.FormCreate(Sender: TObject);
var
AFileStream: TFileStream;
begin
if FileExists('TreeListConfig.dat') then
begin
AFileStream := TFileStream.Create('TreeListConfig.dat', fmOpenReadWrite);
try
cxTreeList1.RestoreFromStream(AFileStream, True, False, '', cxTreeListStoreAllDataViewStates);
finally
AFileStream.Free;
end;
end;
end;
procedure TMyForm.FormDestroy(Sender: TObject);
var
AFileStream: TFileStream;
begin
AFileStream := TFileStream.Create('TreeListConfig.dat', fmCreate or fmOpenReadWrite);
try
cxTreeList1.StoreToStream(AFileStream, '', cxTreeListStoreAllDataViewStates);
finally
AFileStream.Free;
end;
end;
Other Tree List Store/Restore Methods
Alternatively, you can store Tree List data layout and user interaction states in an INI file or the system registry. The TcxCustomTreeList class implements the following Store~
/Restore~
method pairs in addition to StoreToStream and RestoreFromStream
:
- StoreToIniFile | RestoreFromIniFile
- Allow you to store the Tree List state (both data layout and user interaction states) in an INI file.
- StoreToRegistry | RestoreFromRegistry
- Allow you to store the Tree List state (both data layout and user interaction states) in the system registry.
- StoreDataViewState | RestoreDataViewState
- Allow you to store user interaction states in memory during the same session.
- StoreDataViewStateToStream | RestoreDataViewStateFromStream
- Allow you to store only user interaction states in a separate stream.