TcxCustomTreeList.StoreToStream(TStream,string,TcxTreeListStorageOptions) Method

Saves specified Tree List structure and user interaction information to a stream.

Declaration

procedure StoreToStream(AStream: TStream; const ASaveTreeListName: string = ''; AOptions: TcxTreeListStorageOptions = []);

Parameters

Name	Type	Description
AStream	TStream	The target stream.
ASaveTreeListName	string	Optional. Specifies the saved Tree List name. Use this parameter if you need to apply a saved state to a different Tree List control.
AOptions	TcxTreeListStorageOptions	Optional. Specifies a set of individual user interaction states saved to the target stream (AStream). If this parameter is omitted, the procedure saves only Tree List structure 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.

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 the focus position.

tsoSelected

Stores selection.

tsoTopRecord

Stores the Tree List scroll position (the record at the top control border).

tsoExpanded

Stores 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.

Delphi

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;

C++

#include "System.SysUtils.hpp"  // Declares the FileExists function
#include "cxTL.hpp"  // Declares TcxTreeList, TcxCustomTreeList, and related types

// Add the following linker directive to the corresponding CPP source file:
#pragma link "cxTL"  // Required to use cxTL.hpp declarations

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TFileStream *AFileStream;
  if(FileExists("TreeListConfig.dat"))
  {
    AFileStream = new TFileStream("TreeListConfig.dat", fmOpenReadWrite);
    try
    {
      cxTreeList1->RestoreFromStream(AFileStream, true, false, "", cxTreeListStoreAllDataViewStates);
    }
    __finally
    {
      delete AFileStream;
    }
  }
}

void __fastcall TMyForm::FormDestroy(TObject *Sender)
{
  TFileStream *AFileStream = new TFileStream("TreeListConfig.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxTreeList1->StoreToStream(AFileStream, "", cxTreeListStoreAllDataViewStates);
  }
  __finally
  {
    delete AFileStream;
  }
}

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.