[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications, and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Property Grid
  [Collapse]Pivot Grid
   [Expand]Getting Started
   [Expand]Fundamentals
   [Expand]Binding to Data
   [Expand]Data Shaping
   [Expand]Data Analysis
   [Collapse]Layout
     Field Location and Order
     Data Cell Layout
     Field Groups
    [Expand]Customization Form
     Best Fit
     Save and Restore Layout
   [Expand]Focus and Navigation
   [Expand]Printing and Exporting
   [Expand]Appearance
   [Expand]Design-Time Features
   [Expand]Miscellaneous
   [Expand]UI Elements
   [Expand]End-User Capabilities
   [Expand]Examples
   [Expand]Member Tables
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Expand]Scheduler
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
  [Expand]Sunburst Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Save and Restore Layout

The Pivot Grid layout determines the position and appearance of its visual elements. You can modify a Pivot Grid layout with the PivotGrid Designer, and also in code, with API properties and methods. You can save the layout to an XML file, a system registry path or to a stream, and subsequently restore it.

This allows you to customize a Pivot Grid control layout, save it, and apply the same settings to other Pivot Grid controls.

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

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.

Expanded 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

These methods start with SaveLayoutTo... or RestoreLayoutFrom... respectively. Refer to the Member Table: Save and Restore Layout topic for the complete list of methods that you can use to save and restore the Pivot Grid's layout.

The following sample code saves a Pivot Grid Control's layout to a memory stream and then restores it.

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

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

The OptionsColumnLayout.AddNewColumns and OptionsColumnLayout.RemoveOldColumns settings determine the resulting combination of fields in the restored layout.

Consider the saved layout with two fields - OLD and COMMON. The PivotGridControl contains two fields - COMMON and NEW. The RestoreLayoutFrom... methods with a combination of AddNewColumns and RemoveOldColumns parameters result in different layouts as the following table illustrates:

AddNewColumns RemoveOldColumns Layout Fields
True True COMMON, NEW
False False OLD. COMMON
True False COMMON, OLD, NEW, COMMON
False True no fields

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

Expanded See Also

Is this topic helpful?​​​​​​​