TcxCustomTreeList.RestoreDataViewStateFromStream(TStream,TcxTreeListStorageOptions) Method

Restores previously saved user interaction states from a stream.

Declaration

procedure RestoreDataViewStateFromStream(AStream: TStream; AOptions: TcxTreeListStorageOptions);

Parameters

Name	Type	Description
AStream	TStream	The source stream that contains previously saved user interaction states at the current position.
AOptions	TcxTreeListStorageOptions	Specifies a set of individual user interaction states restored from the source stream (AStream).

Remarks

Call the StoreDataViewStateToStream procedure to save specified user interaction states (selection, focus, node expanded status, etc.) to a stream separately from the base data structure/layout. A subsequent RestoreDataViewStateFromStream call restores saved user interaction states from the stream.

Tree List User Interaction States

Pass a set of all required flags^[1] as the AOptions parameter to restore corresponding Tree List user interaction states:

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.

Note

The tsoUseDataViewState flag has no effect on StoreDataViewState/RestoreDataViewState and StoreDataViewStateToStream/RestoreDataViewStateFromStream calls.

Use tsoUseDataViewState in StoreToIniFile/RestoreFromIniFile, StoreToRegistry/RestoreFromRegistry, and StoreToStream/RestoreFromStream calls to save/restore user interaction states in addition to the data layout.

Code Example: Store Data Layout and User Interaction States Separately

The code example in this section demonstrates form OnDestroy and OnCreate event handlers. These handlers call StoreDataViewStateToStream/RestoreDataViewStateFromStream and StoreToStream/RestoreFromStream procedure pairs to store the data layout and user interaction states (selection, focus, scroll position, etc.) in different files (TreeListLayout.dat and TreeListUserInteraction.dat).

Delphi

uses
  System.SysUtils,  // Declares the FileExists function
  cxTL;  // Declares TcxTreeList, TcxCustomTreeList, and related types
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  // Restore the Tree List data layout
  if FileExists('TreeListLayout.dat') then
  begin
    AFileStream := TFileStream.Create('TreeListLayout.dat', fmOpenReadWrite);
    try
      cxTreeList1.RestoreFromStream(AFileStream);
    finally
      AFileStream.Free;
    end;
  end;
  // Restore Tree List user interaction states
  if FileExists('TreeListUserInteraction.dat') then
  begin
    AFileStream := TFileStream.Create('TreeListUserInteraction.dat', fmOpenReadWrite);
    try
      cxTreeList1.RestoreDataViewStateFromStream(AFileStream, cxTreeListStoreAllDataViewStates);
    finally
      AFileStream.Free;
    end;
  end;
end;

procedure TMyForm.FormDestroy(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  // Store the Tree List data layout
  AFileStream := TFileStream.Create('TreeListLayout.dat', fmCreate or fmOpenReadWrite);
  try
    cxTreeList1.StoreToStream(AFileStream);
  finally
    AFileStream.Free;
  end;
  // Store Tree List user interaction states
  AFileStream := TFileStream.Create('TreeListUserInteraction.dat', fmCreate or fmOpenReadWrite);
  try
    cxTreeList1.StoreDataViewStateToStream(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;
  // Restore the Tree List data layout
  if(FileExists("TreeListLayout.dat"))
  {
    AFileStream = new TFileStream("TreeListLayout.dat", fmOpenReadWrite);
    try
    {
      cxTreeList1->RestoreFromStream(AFileStream);
    }
    __finally
    {
      delete AFileStream;
    }
  }
  // Restore Tree List user interaction states
  if(FileExists("TreeListUserInteraction.dat"))
  {
    AFileStream = new TFileStream("TreeListUserInteraction.dat", fmOpenReadWrite);
    try
    {
      cxTreeList1->RestoreDataViewStateFromStream(AFileStream, cxTreeListStoreAllDataViewStates);
    }
    __finally
    {
      delete AFileStream;
    }
  }
}

void __fastcall TMyForm::FormDestroy(TObject *Sender)
{
  TFileStream *AFileStream;
  // Store the Tree List data layout
  AFileStream = new TFileStream("TreeListLayout.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxTreeList1->StoreToStream(AFileStream);
  }
  __finally
  {
    delete AFileStream;
  }
  // Store Tree List user interaction states
  AFileStream = new TFileStream("TreeListUserInteraction.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxTreeList1->StoreDataViewStateToStream(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 StoreDataViewStateToStream and RestoreDataViewStateFromStream:

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.

StoreToStream | RestoreFromStream

Allow you to store the Tree List state (both data layout and user interaction states) in a stream.

StoreDataViewState | RestoreDataViewState

Allow you to store user interaction states in memory during the same session.

Footnotes

1. Alternatively, you can use only the cxTreeListStoreAllDataViewStates constant if you need to restore all user interaction states for the Tree List control.