windowsforms-1806-controls-and-libraries-pivot-grid-layout-save-and-restore-layout.md
DevExpress controls allow you to save their layout information to data stores (XML file, stream and system registry) and restore the layout later. Refer to the following article for information about the common concept: Save and Restore Layouts of DevExpress controls.
The Pivot Grid layout determines the position and appearance of its visual elements. You can modify the Pivot Grid layout in the PivotGrid Designer and in code.
The control saves the layout to an XML file, a system registry path, or to a stream, and subsequently restores it. You can customize and save the current Pivot Grid control’s layout and apply the same settings to other Pivot Grid controls. Pivot Grid uses a field’s Name property value to determine fields in a stored layout.
Important
Deserializing layout settings from untrusted resources may create security issues. Review the following help topic for additional information: Safe Deserialization.
The Layout page of the PivotGrid Designer allows you to modify, save, and restore the Pivot Grid control layout. See the Layout Page topic for details.
To restore the Pivot Grid’s layout from an existing XML file, click the Load Layout… button. To apply the created or loaded layout to the current Pivot Grid control, click the Apply button.
The Pivot Grid control has API methods to save a control layout and restore it from the following data stores:
The following list illustrates methods that you can use to save and restore the Pivot Grid’s layout:
PivotGridControl.SaveLayoutToRegistrySaves a Pivot Grid Control’s layout to a system registry path.PivotGridControl.SaveLayoutToStreamSaves a Pivot Grid Control’s layout to the specified stream.PivotGridControl.SaveLayoutToXmlSaves a Pivot Grid Control’s layout to an XML file.PivotGridControl.SaveLayoutToJsonSaves the Pivot Grid’s layout settings specified by the OptionsLayout property to a file in JSON format.PivotGridControl.RestoreLayoutFromRegistryRestores the layout stored at the specified system registry path.PivotGridControl.RestoreLayoutFromStreamRestores a Pivot Grid Control’s layout from the specified stream.PivotGridControl.RestoreLayoutFromXmlRestores a Pivot Grid Control’s layout from the specified XML file.PivotGridControl.RestoreLayoutFromJsonLoads the Pivot Grid’s layout settings specified by the OptionsLayout property from a file in JSON format.
Call the following methods to save and restore the collapsed field state in the Pivot Grid layout. Otherwise, the fields are saved and restored expanded.
PivotGridControl.SaveCollapsedStateToFileSaves the collapsed state of field values to the specified file.PivotGridControl.SaveCollapsedStateToStreamSaves the collapsed state of field values to the specified stream.PivotGridControl.LoadCollapsedStateFromFileRestores the collapsed state of field values from the specified file.PivotGridControl.LoadCollapsedStateFromStreamRestores the collapsed state of field values from the specified stream.
The SaveLayoutTo… or RestoreLayoutFrom… methods without the options parameter save or restore only a subset of the control’s settings. These settings include:
The SaveLayoutTo… or RestoreLayoutFrom… methods with the options parameter save or restore the specified settings. To create a parameter, instantiate the PivotGridOptionsLayout class and set the required properties. To save all settings, pass null ( Nothing in Visual Basic) or a static OptionsLayoutBase.FullLayout property as the options parameter.
Settings, such as appearance and format rules, are not saved/restored unless explicitly specified. Use the PivotGridControl.OptionsLayout property to specify the settings to save or restore.
The PivotGridOptionsLayout.Columns.AddNewColumns and PivotGridOptionsLayout.Columns.RemoveOldColumns settings determine the resulting combination of fields in the restored layout. New columns are fields in the control, old columns are fields in the saved layout. The field’s Name property determines fields in a stored layout.
When old and new fields have the same Name, the control applies the saved layout changes to the fields in the control.
When old and new fields have a different Name, the behavior is as follows:
For example, the image below displays two Pivot Grid controls with the following fields:
| pivotGridControlOld | pivotGridControlNew |
|---|---|
Field: Extended Price | |
Name: fieldExtendedPrice | Field: Extended Price Avg |
Name: fieldExtendedPriceNew | |
Field: Product Name | |
Name: fieldProductName | Field: Category Name |
Name: fieldCategoryName | |
Field: Order Date | |
Name: fieldQuarter | Field: Year |
Name: fieldYear |
If both properties are true, the Pivot Grid removes the fields from the saved layout and keeps the fields in the control.
If both properties are false, the Pivot Grid restores the fields from the layout and removes the fields from the control.
If AddNewColumns is true and RemoveOldColumns is false, the Pivot Grid restores the fields from the layout and keeps the fields in the control.
If AddNewColumns is false and RemoveOldColumns is true, the Pivot Grid removes the fields from the layout and control.
Use the OptionsLayoutBase.FullLayout property to clear all the fields and restore all fields from the layout.
For field groups, use the PivotGridOptionsLayout.AddNewGroups property.
When a layout is restored and its version differs from the current Pivot Grid layout version, the PivotGridControl.LayoutUpgrade event occurs.
The current layout version is specified with the OptionsLayoutBase.LayoutVersion property. You can handle the LayoutUpgrade event and use this property and the PivotLayoutUpgradeEventArgs.PreviousVersion value to decide whether to overwrite the current layout.
When you load or restore a layout, the PivotGridControl.BeforeLoadLayout event occurs. You can handle this event and set the LayoutAllowEventArgs.Allow property to false to cancel loading.
The following example handles LayoutUpgrade to add the Quantity field to the data area of pivotGridControlNew:
using System.Windows.Forms;
namespace WinPivotUpgradeLayout {
public partial class Form1 : Form {
MemoryStream layoutStream = new MemoryStream();
public Form1() {
InitializeComponent();
sqlDataSource1.Fill();
sqlDataSource1.FillAsync();
pivotGridControlOld.OptionsLayout.LayoutVersion = "1.0";
pivotGridControlNew.OptionsLayout.LayoutVersion = "2.0";
}
private void simpleButton1_Click(object sender, EventArgs e) {
pivotGridControlOld.SaveLayoutToStream(layoutStream);
}
private void simpleButton2_Click(object sender, EventArgs e) {
if (layoutStream.Length > 0) {
layoutStream.Seek(0, SeekOrigin.Begin);
pivotGridControlNew.RestoreLayoutFromStream(layoutStream);
}
}
private void pivotGridControlNew_LayoutUpgrade(object sender, DevExpress.Utils.LayoutUpgradeEventArgs e) {
if (e.PreviousVersion == "1.0") {
var newField = new PivotGridField() {
FieldName = "Quantity",
Caption = "Quantity",
Name = "fieldQuantity",
Area = DevExpress.XtraPivotGrid.PivotArea.DataArea
};
pivotGridControlNew.Fields.Add(newField);
};
}
}
}
Imports System.Windows.Forms
Namespace WinPivotUpgradeLayout
Partial Public Class Form1
Inherits Form
Private layoutStream As New MemoryStream()
Public Sub New()
InitializeComponent()
sqlDataSource1.Fill()
sqlDataSource1.FillAsync()c
pivotGridControlOld.OptionsLayout.LayoutVersion = "1.0"
pivotGridControlNew.OptionsLayout.LayoutVersion = "2.0"
End Sub
Private Sub simpleButton1_Click(ByVal sender As Object, ByVal e As EventArgs)
pivotGridControlOld.SaveLayoutToStream(layoutStream)
End Sub
Private Sub simpleButton2_Click(ByVal sender As Object, ByVal e As EventArgs)
If layoutStream.Length > 0 Then
layoutStream.Seek(0, SeekOrigin.Begin)
pivotGridControlNew.RestoreLayoutFromStream(layoutStream)
End If
End Sub
Private Sub pivotGridControlNew_LayoutUpgrade(ByVal sender As Object, ByVal e As DevExpress.Utils.LayoutUpgradeEventArgs)
If e.PreviousVersion = "1.0" Then
Dim newField = New PivotGridField() With {
.FieldName = "Quantity",
.Caption = "Quantity",
.Name = "fieldQuantity",
.Area = DevExpress.XtraPivotGrid.PivotArea.DataArea
}
pivotGridControlNew.Fields.Add(newField)
End If
End Sub
End Class
End Namespace
This example demonstrates how to restore the Pivot Grid layout and row/column state.
The Save button uses the PivotGridControl.SaveLayoutToStream and PivotGridControl.SaveCollapsedStateToStream methods to save the layout and field values’ collapsed state to memory streams.
The Load button uses the PivotGridControl.RestoreLayoutFromStream and PivotGridControl.LoadCollapsedStateFromStream methods to restore the saved layout and column/row state.
The Clear button clears the field collection.
using System;
using System.IO;
using System.Windows.Forms;
using DevExpress.Utils;
namespace XtraPivotGrid_RestoreLayoutExample {
public partial class Form1 : DevExpress.XtraEditors.XtraForm {
MemoryStream layoutStream = new MemoryStream();
MemoryStream collapseStateStream = new MemoryStream();
public Form1() {
InitializeComponent();
btnClear.Enabled = false;
}
private void Form1_Load(object sender, EventArgs e) {
excelDataSource1.FileName = "SalesPerson.xlsx";
excelDataSource1.Fill();
pivotGridControl1.DataSource = excelDataSource1;
}
private void btnSave_Click(object sender, EventArgs e) {
if (pivotGridControl1.Fields.Count > 0) {
layoutStream.Dispose();
layoutStream = new MemoryStream();
pivotGridControl1.SaveLayoutToStream(layoutStream, OptionsLayoutBase.FullLayout);
collapseStateStream.Dispose();
collapseStateStream = new MemoryStream();
pivotGridControl1.SaveCollapsedStateToStream(collapseStateStream);
btnClear.Enabled = true;
}
}
private void btnLoad_Click(object sender, EventArgs e) {
if (layoutStream.Length > 0 && collapseStateStream.Length > 0) {
layoutStream.Seek(0, SeekOrigin.Begin);
pivotGridControl1.RestoreLayoutFromStream(layoutStream, OptionsLayoutBase.FullLayout);
collapseStateStream.Seek(0, SeekOrigin.Begin);
pivotGridControl1.LoadCollapsedStateFromStream(collapseStateStream);
}
}
private void btnClear_Click(object sender, EventArgs e) {
if (layoutStream.Length > 0 && collapseStateStream.Length > 0) {
pivotGridControl1.Fields.Clear();
}
}
}
}
Imports System
Imports System.IO
Imports System.Windows.Forms
Imports DevExpress.Utils
Namespace XtraPivotGrid_RestoreLayoutExample
Partial Public Class Form1
Inherits DevExpress.XtraEditors.XtraForm
Private layoutStream As New MemoryStream()
Private collapseStateStream As New MemoryStream()
Public Sub New()
InitializeComponent()
btnClear.Enabled = False
End Sub
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles Me.Load
excelDataSource1.FileName = "SalesPerson.xlsx"
excelDataSource1.Fill()
pivotGridControl1.DataSource = excelDataSource1
End Sub
Private Sub btnSave_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnSave.Click
If pivotGridControl1.Fields.Count > 0 Then
layoutStream.Dispose()
layoutStream = New MemoryStream()
pivotGridControl1.SaveLayoutToStream(layoutStream, OptionsLayoutBase.FullLayout)
collapseStateStream.Dispose()
collapseStateStream = New MemoryStream()
pivotGridControl1.SaveCollapsedStateToStream(collapseStateStream)
btnClear.Enabled = True
End If
End Sub
Private Sub btnLoad_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnLoad.Click
If layoutStream.Length > 0 AndAlso collapseStateStream.Length > 0 Then
layoutStream.Seek(0, SeekOrigin.Begin)
pivotGridControl1.RestoreLayoutFromStream(layoutStream, OptionsLayoutBase.FullLayout)
collapseStateStream.Seek(0, SeekOrigin.Begin)
pivotGridControl1.LoadCollapsedStateFromStream(collapseStateStream)
End If
End Sub
Private Sub btnClear_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnClear.Click
If layoutStream.Length > 0 AndAlso collapseStateStream.Length > 0 Then
pivotGridControl1.Fields.Clear()
End If
End Sub
End Class
End Namespace
The example below shows how to manage Pivot Grid layout on restore.
The example contains two Pivot Grid controls with the following fields:
The SaveLayout button uses the PivotGridControl.SaveLayoutToStream method to save the pivotGridControlOld layout to memory streams.
The RestoreLayout button uses the PivotGridControl.RestoreLayoutFromStream method to restore the saved layout to pivotGridControlNew.
The following options allows you to combine fields from different Pivot Grid controls on restore:
PivotGridOptionsLayout.Columns.AddNewColumns set to true keeps the field in the pivotGridControlNew control when you restore the layout.
PivotGridOptionsLayout.Columns.RemoveOldColumns set to false adds fields from pivotGridControlOld to pivotGridControlNew.
PivotGridOptionsLayout.AddNewGroups set to true keeps the Year-Quarter group of the pivotGridControlNew when you restore the layout.
PivotGridControl.LayoutUpgrade event adds the “Quantity” field to pivotGridControlNew‘s data area when you restore the layout.
The following image shows the resulting layout when you save the pivotGridControlOld layout and restore it to pivotGridControlNew:
using DevExpress.Utils;
using DevExpress.XtraPivotGrid;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.IO;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
namespace WinPivotUpgradeLayout{
public partial class Form1 : Form{
MemoryStream layoutStream = new MemoryStream();
public Form1(){
InitializeComponent();
// Fill the SqlDataSource
sqlDataSource1.Fill();
// Fill the SqlDataSource asynchronously
sqlDataSource1.FillAsync();
pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = true;
pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = false;
pivotGridControlNew.OptionsLayout.AddNewGroups = true;
pivotGridControlOld.OptionsLayout.LayoutVersion = "1.0";
pivotGridControlNew.OptionsLayout.LayoutVersion = "2.0";
}
private void Form1_Load(object sender, EventArgs e){
PivotGridField fieldProductName = pivotGridControlOld.Fields["fieldProductName"];
pivotGridControlOld.BeginUpdate();
try{
fieldProductName.FilterValues.Clear();
fieldProductName.FilterValues.Add("Chai");
fieldProductName.FilterValues.Add("Chang");
fieldProductName.FilterValues.Add("Chartreuse verte");
fieldProductName.FilterValues.Add("Aniseed Syrup");
fieldProductName.FilterValues.Add("Genen Shouyu");
fieldProductName.FilterValues.Add("Gula Malacca");
fieldProductName.FilterValues.FilterType = DevExpress.XtraPivotGrid.PivotFilterType.Included;
}
finally{
pivotGridControlOld.EndUpdate();
}
}
private void simpleButton1_Click(object sender, EventArgs e){
pivotGridControlOld.SaveLayoutToStream(layoutStream);
}
private void simpleButton2_Click(object sender, EventArgs e){
if (layoutStream.Length > 0) {
layoutStream.Seek(0, SeekOrigin.Begin);
pivotGridControlNew.RestoreLayoutFromStream(layoutStream);
}
}
private void pivotGridControlNew_LayoutUpgrade(object sender, DevExpress.Utils.LayoutUpgradeEventArgs e){
if (e.PreviousVersion == "1.0"){
var newField = new PivotGridField(){
FieldName = "Quantity",
Caption = "Quantity",
Name = "fieldQuantity",
Area = DevExpress.XtraPivotGrid.PivotArea.DataArea
};
pivotGridControlNew.Fields.Add(newField);
};
}
}
}
Imports DevExpress.Utils
Imports DevExpress.XtraPivotGrid
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.IO
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms
Namespace WinPivotUpgradeLayout
Partial Public Class Form1
Inherits Form
Private layoutStream As New MemoryStream()
Public Sub New()
InitializeComponent()
' Fill the SqlDataSource
sqlDataSource1.Fill()
' Fill the SqlDataSource asynchronously
sqlDataSource1.FillAsync()
pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = True
pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = False
pivotGridControlNew.OptionsLayout.AddNewGroups = True
pivotGridControlOld.OptionsLayout.LayoutVersion = "1.0"
pivotGridControlNew.OptionsLayout.LayoutVersion = "2.0"
End Sub
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
Dim fieldProductName As PivotGridField = pivotGridControlOld.Fields("fieldProductName")
pivotGridControlOld.BeginUpdate()
Try
fieldProductName.FilterValues.Clear()
fieldProductName.FilterValues.Add("Chai")
fieldProductName.FilterValues.Add("Chang")
fieldProductName.FilterValues.Add("Chartreuse verte")
fieldProductName.FilterValues.Add("Aniseed Syrup")
fieldProductName.FilterValues.Add("Genen Shouyu")
fieldProductName.FilterValues.Add("Gula Malacca")
fieldProductName.FilterValues.FilterType = DevExpress.XtraPivotGrid.PivotFilterType.Included
Finally
pivotGridControlOld.EndUpdate()
End Try
End Sub
Private Sub simpleButton1_Click(ByVal sender As Object, ByVal e As EventArgs)
pivotGridControlOld.SaveLayoutToStream(layoutStream)
End Sub
Private Sub simpleButton2_Click(ByVal sender As Object, ByVal e As EventArgs)
If layoutStream.Length > 0 Then
layoutStream.Seek(0, SeekOrigin.Begin)
pivotGridControlNew.RestoreLayoutFromStream(layoutStream)
End If
End Sub
Private Sub pivotGridControlNew_LayoutUpgrade(ByVal sender As Object, ByVal e As DevExpress.Utils.LayoutUpgradeEventArgs)
If e.PreviousVersion = "1.0" Then
Dim newField = New PivotGridField() With {
.FieldName = "Quantity",
.Caption = "Quantity",
.Name = "fieldQuantity",
.Area = DevExpress.XtraPivotGrid.PivotArea.DataArea
}
pivotGridControlNew.Fields.Add(newField)
End If
End Sub
End Class
End Namespace
See Also
Save and Restore Layouts of DevExpress Controls