Skip to main content
BuyLog In
WinForms Controls
Search in…
Docs > Controls and Libraries > Pivot Grid > Layout > Save and Restore Layout
All docs
V24.2
WinForms Controls
.NET Support and Migration
Prerequisites
What's New
What's Installed
Build an Application
Redistribution and Deployment
Controls and Libraries
Forms and User Controls
Messages, Notifications, and Dialogs
Editors and Simple Controls
Ribbon, Bars and Menu
Application UI Manager
Docking Library
Data Grid
Vertical Grid
Property Grid
Pivot Grid
Getting Started
Fundamentals
Binding to Data
Asynchronous Mode
Data Shaping
Data Analysis
Layout
Field Location and Order
Data Cell Layout
Field Value Layout
Field Groups
Expand and Collapse Fields
Customization Form
Best Fit
Save and Restore Layout
Focus and Navigation
Printing and Exporting
Appearance
Design-Time Features
Miscellaneous
UI Elements
End-User Capabilities
Examples
Tree List
Gantt Control
Chart Control
Diagrams
Gauges
Map Control
Scheduler
Spreadsheet
Rich Text Editor
Spell Checker
Form Layout Managers
Navigation Controls
Printing-Exporting
PDF Viewer
Reporting
Office File API
Snap
TreeMap Control
Sunburst Control
Sankey Diagram Control
Heatmap Control
Icon and Image Library
AI-powered Extensions
Common Features
Security Considerations
Data Access Security
Hybrid & Enterprise Development
UI Templates
Desktop & Web App UI Framework (Powered by EF Core)
Get More Help
API Reference
Download CHM

Save and Restore Layout

  • 11 minutes to read

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.

Save and Restore Layout at Design Time

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.

PivotGrid Designer - LayoutPage_1

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.

Save and Restore Layout in Code

The Pivot Grid control has API methods to save a control layout and restore it from the following data stores:

  • XML file
  • Windows Registry
  • Stream

The following list illustrates methods that you can use to save and restore the Pivot Grid’s layout:

PivotGridControl.SaveLayoutToRegistry
Saves a Pivot Grid Control’s layout to the specified system registry path, using the specified settings.
PivotGridControl.SaveLayoutToStream
Saves a Pivot Grid Control’s layout to the specified stream, using the specified settings.
PivotGridControl.SaveLayoutToXml
Saves a Pivot Grid Control’s layout to the specified XML file, using the specified settings.
PivotGridControl.RestoreLayoutFromRegistry
Restores the Pivot Grid Control’s layout stored at the specified system registry path, using the specified settings.
PivotGridControl.RestoreLayoutFromStream
Restores a Pivot Grid Control’s layout from the specified stream, using the specified settings.
PivotGridControl.RestoreLayoutFromXml
Restores a Pivot Grid Control’s layout using the specified settings from the specified XML file.

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.SaveCollapsedStateToFile
Saves the collapsed state of field values to the specified file.
PivotGridControl.SaveCollapsedStateToStream
Saves the collapsed state of field values to the specified stream.
PivotGridControl.LoadCollapsedStateFromFile
Restores the collapsed state of field values from the specified file.
PivotGridControl.LoadCollapsedStateFromStream
Restores the collapsed state of field values from the specified stream.

Layout Options

The SaveLayoutTo… or RestoreLayoutFrom… methods without the options parameter save or restore only a subset of the control’s settings. These settings include:

  • Visibility state, position and size of the fields.
  • Data settings (grouping, sorting, filtering settings and summaries).
  • All settings grouped within the control’s PivotGridControl.OptionsView object.

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.

Manage Fields in Restored Layout

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:

Manage layout 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.

    Remove old columns

    using System.Windows.Forms;

namespace WinPivotUpgradeLayout {
    public partial class Form1 : Form {
        MemoryStream layoutStream = new MemoryStream();
        public Form1() {
            pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = true;
            pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = true;
        }        

        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);
            }
        }
    }
}

  • If both properties are false, the Pivot Grid restores the fields from the layout and removes the fields from the control.

    Restore saved fields

    // ...
pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = false;
pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = false;
// ...

  • If AddNewColumns is true and RemoveOldColumns is false, the Pivot Grid restores the fields from the layout and keeps the fields in the control.

    Restore all fields

    // ...
pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = true;
pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = false;
// ...

  • If AddNewColumns is false and RemoveOldColumns is true, the Pivot Grid removes the fields from the layout and control.

    Remove all fields

    // ...
pivotGridControlNew.OptionsLayout.Columns.AddNewColumns = false;
pivotGridControlNew.OptionsLayout.Columns.RemoveOldColumns = true;
// ...

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.

Upgrade Layout

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:

Layout upgrade example 

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);
            };
        }
    }
}

Example: Save and Restore Pivot Grid Layout with the Row and Column State

This example demonstrates how to restore the Pivot Grid layout and row/column state.

View Example

Save and restore layout example

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();
            }
        }
    }
}

Example: Update Pivot Grid Layout on Restore

The example below shows how to manage Pivot Grid layout on restore.

The example contains two Pivot Grid controls with the following fields:

Manage layout example

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:

The following image shows the resulting layout when you save the pivotGridControlOld layout and restore it to pivotGridControlNew:

Upgrade Pivot Grid Layout

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);
            };
        }
    }
}
See Also