vcl-cxgridcustomview-dot-tcxcustomgridview-dot-restorefromstream-x28-system-dot-classes-dot-tstream-system-dot-boolean-system-dot-boolean-cxgridcustomview-dot-tcxgridstorageoptions-system-dot-string-system-dot-string-x29.md
Restores previously saved grid View state information from a stream.
procedure RestoreFromStream(AStream: TStream; AChildrenCreating: Boolean = True; AChildrenDeleting: Boolean = False; AOptions: TcxGridStorageOptions = [gsoUseFilter, gsoUseSummary]; const ARestoreViewName: string = ''; const AOwnerName: string = '');
| Name | Type | Description |
|---|---|---|
| AStream | TStream |
The source stream that contains previously saved grid View state information at the current position.
| | AChildrenCreating | Boolean |
Optional. Specifies if the procedure creates missing grid View elements (columns, bands, series, etc.):
True
Default. The procedure creates additional grid View elements to match the loaded structure state.
Tip
You can handle the OnInitStoredObject event to initialize created data items.
FalseThe procedure does not create any elements if the current structure contains fewer elements compared to the loaded structure state. |
| AChildrenDeleting | Boolean |
Optional. Specifies if the procedure deletes redundant grid View elements (columns, bands, series, etc.):
False Default. The procedure does not delete any elements if the current structure contains more elements than the loaded structure state.TrueThe procedure deletes all elements that do not match the loaded structure state.
If the current grid View structure matches the loaded state, the AChildrenDeleting parameter is ignored.
| | AOptions | TcxGridStorageOptions |
Optional. Specifies a set of individual user interaction states restored from the source stream (AStream).
If this parameter is omitted, the procedure loads only grid View structure information, even if the source stream contains user interaction state information.
| | ARestoreViewName | string |
Optional. Specifies the source 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.
|
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.
Grid View structure information includes the following:
AChildrenCreating and AChildrenDeleting parameters to update the current grid View data layout according to the loaded state.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.
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, scroll position, etc.).
Pass a set of all required flags as the AOptions parameter to store/restore corresponding grid View states:
gsoUseFilter | gsoUseSummaryAllow 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 | gsoFocusedViewStore/restore the focus position. Require gsoUseDataViewState.gsoSelectedStores/restores selection. Requires gsoUseDataViewState.gsoTopRecordStores/restores the grid View scroll position. Requires gsoUseDataViewState.gsoExpandedStores/restores the expanded status for all records. Requires gsoUseDataViewState.gsoDetailStores/restores the active detail grid View. Applicable only to master-detail grid View relationships. Requires gsoUseDataViewState.
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.
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;
#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;
}
}
Alternatively, you can store grid View data layout and user interaction states in an INI file, system registry, or a custom storage. The TcxCustomGridView class implements the following Store~/Restore~ method pairs:
StoreToIniFile | RestoreFromIniFileAllow you to store the grid View state (both data layout and user interaction states) in an INI file.StoreToRegistry | RestoreFromRegistryAllow you to store the grid View state (both data layout and user interaction states) in the system registry.StoreToStorage | RestoreFromStorageAllow you to store the grid View state (both data layout and user interaction states) in a custom data format.StoreDataViewState | RestoreDataViewStateAllow you to store user interaction states in memory during the same session.StoreDataViewStateToStream | RestoreDataViewStateFromStreamAllow you to store only user interaction states in a separate stream. See Also