TcxCustomGridView.RestoreDataViewStateFromStream(TStream,TcxGridStorageOptions) Method

Restores the previously saved data view state from a stream.

Declaration

procedure RestoreDataViewStateFromStream(AStream: TStream; AOptions: TcxGridStorageOptions); virtual;

Parameters

Name	Type	Description
AStream	TStream	The source stream that contains previously saved data view state information at the current position.
AOptions	TcxGridStorageOptions	A set of flags that correspond to individual user interaction states restored from the source stream (AStream).

Remarks

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

View and User Interaction States

Pass a set of all required flags^[1] as the AOptions parameter to store/restore corresponding grid View states:

gsoFocusedItem | gsoFocusedRecord | gsoFocusedView

Store/restore the focus position.

gsoSelected

Stores/restores selection.

gsoTopRecord

Stores/restores the grid View scroll position.

gsoExpanded

Stores/restores the expanded status for all records.

gsoDetail

Stores/restores the active detail grid View. Applicable only to master-detail grid View relationships.

Note

gsoUseFilter, gsoUseSummary, and gsoUseDataViewState flags have no effect on StoreDataViewState/RestoreDataViewState and StoreDataViewStateToStream/RestoreDataViewStateFromStream procedure calls.

Use these flags in StoreToIniFile/RestoreFromIniFile, StoreToRegistry/RestoreFromRegistry, StoreToStorage/RestoreFromStorage, StoreToStream/RestoreFromStream calls instead.

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 (GridLayout.dat and GridUserInteraction.dat).

Delphi

uses
  System.SysUtils,  // Declares the FileExists function
  cxGrid,  // Declares the TcxGrid control
  cxGridCustomView,  // Declares the TcxCustomGridView class and related types
  cxGridDBTableView;  // Declares the TcxGridDBTableView class
// ...

procedure TMyForm.FormCreate(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  // Restore the grid View data layout
  if FileExists('GridLayout.dat') then
  begin
    AFileStream := TFileStream.Create('GridLayout.dat', fmOpenReadWrite);
    try
      cxGrid1DBTableView1.RestoreFromStream(AFileStream);
    finally
      AFileStream.Free;
    end;
  end;
  // Restore grid View user interaction states
  if FileExists('GridUserInteraction.dat') then
  begin
    AFileStream := TFileStream.Create('GridUserInteraction.dat', fmOpenReadWrite);
    try
      cxGrid1DBTableView1.RestoreDataViewStateFromStream(AFileStream, cxGridStoreAllDataViewStates);
    finally
      AFileStream.Free;
    end;
  end;
end;

procedure TMyForm.FormDestroy(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  // Store the grid View data layout
  AFileStream := TFileStream.Create('GridLayout.dat', fmCreate or fmOpenReadWrite);
  try
    cxGrid1DBTableView1.StoreToStream(AFileStream);
  finally
    AFileStream.Free;
  end;
  // Store grid View user interaction states
  AFileStream := TFileStream.Create('GridUserInteraction.dat', fmCreate or fmOpenReadWrite);
  try
    cxGrid1DBTableView1.StoreDataViewStateToStream(AFileStream, cxGridStoreAllDataViewStates);
  finally
    AFileStream.Free;
  end;
end;

C++

#include "System.SysUtils.hpp"  // Declares the FileExists function
#include "cxGrid.hpp"  // Declares the TcxGrid control
#include "cxGridCustomView.hpp"  // Declares the TcxCustomGridView class and related types
#include "cxGridDBTableView.hpp"  // Declares the TcxGridDBTableView class

// Add the following linker directives to the corresponding CPP source file:
#pragma link "cxGrid"  // Required to use cxGrid.hpp declarations
#pragma link "cxCustomGridView"  // Required to use cxGridCustomView.hpp declarations
#pragma link "cxGridDBTableView"  // Required to use cxGridDBTableView.hpp declarations

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TFileStream *AFileStream;
  // Restore the grid View data layout
  if(FileExists("GridLayout.dat"))
  {
    AFileStream = new TFileStream("GridLayout.dat", fmOpenReadWrite);
    try
    {
      cxGrid1DBTableView1->RestoreFromStream(AFileStream);
    }
    __finally
    {
      delete AFileStream;
    }
  }
  // Restore grid View user interaction states
  if(FileExists("GridUserInteraction.dat"))
  {
    AFileStream = new TFileStream("GridUserInteraction.dat", fmOpenReadWrite);
    try
    {
      cxGrid1DBTableView1->RestoreDataViewStateFromStream(AFileStream, cxGridStoreAllDataViewStates);
    }
    __finally
    {
      delete AFileStream;
    }
  }
}

void __fastcall TMyForm::FormDestroy(TObject *Sender)
{
  TFileStream *AFileStream;
  // Store the grid View data layout
  AFileStream = new TFileStream("GridLayout.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxGrid1DBTableView1->StoreToStream(AFileStream);
  }
  __finally
  {
    delete AFileStream;
  }
  AFileStream = new TFileStream("GridUserInteraction.dat", fmCreate | fmOpenReadWrite);
  try
  {
    cxGrid1DBTableView1->StoreDataViewStateToStream(AFileStream, cxGridStoreAllDataViewStates);
  }
  __finally
  {
    delete AFileStream;
  }
}

Other View State Store/Restore Methods

Alternatively, you can store grid View data layout and user interaction states in an INI file, system registry, or custom storage. The TcxCustomGridView class implements the following Store~/Restore~ method pairs in addition to StoreDataViewStateToStream and RestoreDataViewStateFromStream:

StoreToIniFile | RestoreFromIniFile

Allow you to store the grid View state (both data layout and user interaction states) between sessions in an INI file.

StoreToRegistry | RestoreFromRegistry

Allow you to store the grid View state (both data layout and user interaction states) between sessions in the system registry.

StoreToStorage | RestoreFromStorage

Allow you to store the grid View state between sessions in a custom storage.

StoreToStream | RestoreFromStream

Allow you to store grid View 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 cxGridStoreAllDataViewStates constant if you need to store all user interaction states for the grid View as demonstrated in the code example in this topic.