TcxCustomGridView.StoreToStream(TStream,TcxGridStorageOptions,string,string) Method

Saves specified View data structure and user interaction information to a stream.

Declaration

procedure StoreToStream(AStream: TStream; AOptions: TcxGridStorageOptions = []; const ASaveViewName: string = ''; const AOwnerName: string = '');

Parameters

Name	Type	Description
AStream	TStream	The target stream.
AOptions	TcxGridStorageOptions	Optional. A set of flags that correspond to individual settings and states saved to the target stream (AStream). If this parameter is omitted, the procedure saves only view structure information.
ASaveViewName	string	Optional. Specifies the saved grid View name. Use this parameter if you need to apply a saved state to a different grid View.
AOwnerName	string	Optional. Specifies the parent form name for the TcxGrid control. Tip This parameter can be useful for MDI application projects.

Remarks

Call the StoreToStream procedure to save specified data layout and user interaction states to a stream. A subsequent RestoreFromStream call restores the saved grid View state from the stream.

Stored Information

View Structure | Data Layout

Grid View structure information includes the following:

• Grid View type and name.
• All grid View element settings available to end users for customization: position, dimensions, visibility, sort order, etc.

Important

After each StoreToStream procedure call, make sure that the grid View maps to the same underlying dataset fields before the corresponding RestoreFromStream call. Otherwise, errors may occur.

View and User Interaction States (Optional)

In addition to the base View Structure/Data Layout, the AOptions parameter available for StoreToStream and RestoreFromStream procedures allows you to store summaries, filter criteria, and a number of user interaction states (selection, focus, the scroll position, etc.).

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

gsoUseFilter | gsoUseSummary

Allow you to store filter criteria and summaries.

gsoUseDataViewState

The main flag required for all other user interaction flags listed below. These flags have no effect without gsoUseDataViewState.

Tip

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

gsoFocusedItem | gsoFocusedRecord | gsoFocusedView

Store the focus position. Require gsoUseDataViewState.

gsoSelected

Stores selection. Requires gsoUseDataViewState.

gsoTopRecord

Stores the grid View scroll position. Requires gsoUseDataViewState.

gsoExpanded

Stores the expanded status for all records. Requires gsoUseDataViewState.

gsoDetail

Stores the active detail grid View. Applicable only to master-detail grid View relationships. Requires gsoUseDataViewState.

Code Example: Store Grid View 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 filter state and summaries.

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
  if FileExists('GridConfig.dat') then
  begin
    AFileStream := TFileStream.Create('GridConfig.dat', fmOpenReadWrite);
    try
      // Restore the grid view layout structure along with selected records and the current focus position
      cxGrid1DBTableView1.RestoreFromStream(AFileStream, True, False,
       [gsoUseFilter, gsoUseSummary] + cxGridStoreAllDataViewStates)
    finally
      AFileStream.Free;
    end;
  end;
end;

procedure TMyForm.FormDestroy(Sender: TObject);
var
  AFileStream: TFileStream;
begin
  AFileStream := TFileStream.Create('GridConfig.dat', fmCreate or fmOpenReadWrite);
  try
   // Save the grid view layout structure along with selected records and the current focus position
   cxGrid1DBTableView1.StoreToStream(AFileStream,
     [gsoUseFilter, gsoUseSummary] + 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 "cxGridCustomView"  // Required to use cxGridCustomView.hpp declarations
#pragma link "cxGridDBTableView"  // Required to use cxGridDBTableView.hpp declarations
// ...

void __fastcall TMyForm::FormCreate(TObject *Sender)
{
  TFileStream *AFileStream;
  if(FileExists("GridConfig.dat"))
  {
    AFileStream = new TFileStream("GridConfig.dat", fmOpenReadWrite);
    try
    {
      // Restore the grid view layout structure along with selected records and the current focus position
      cxGrid1DBTableView1->RestoreFromStream(AFileStream, true, false,
        (TcxGridStorageOptions() << gsoUseFilter << gsoUseSummary) + cxGridStoreAllDataViewStates);
    }
    __finally
    {
      delete AFileStream;
    }
  }
}

void __fastcall TMyForm::FormDestroy(TObject *Sender)
{
  TFileStream *AFileStream = new TFileStream("GridConfig.dat", fmCreate | fmOpenReadWrite);
  try
  {
    // Save the grid view layout structure along with selected records and the current focus position
    cxGrid1DBTableView1->StoreToStream(AFileStream,
      (TcxGridStorageOptions() << gsoUseFilter << gsoUseSummary) + 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 StoreToStream and RestoreFromStream:

StoreToIniFile | RestoreFromIniFile

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

StoreToRegistry | RestoreFromRegistry

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

StoreToStorage | RestoreFromStorage

Allow you to store the grid View state (both data layout and user interaction states) in a custom data format.

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.