Save and Restore Layout
- 5 minutes to read
A PivotGridControl layout contains settings that determine how its visual elements behave - their size, position within the control, sorting and grouping settings, etc. You can control a Pivot Grid layout both at design time (using the PivotGrid Designer) and runtime (using SaveLayoutTo… or RestoreLayoutFrom… methods). A layout can be saved to an XML file, a system registry path or to a stream, and then applied to any other Pivot Grid control. This allows you to customize a Pivot Grid control just once and then apply the saved settings to other pivot grids in other applications.
This topic consists of the following sections.
- Save and Restore Layout at Design Time
- Save and Restore Layout in Code
- Layout Options
- Upgrade Layout
Save and Restore Layout at Design Time
The Layout page of the PivotGrid Designer provides design-time capabilities to customize, save and restore the layouts of the Pivot Grid control.
To save a control’s layout to an XML file, follow the steps below.
- Click the Save Layout… button.
- In the invoked Save dialog, specify the required location of the XML file.
Once saved, the layout can be loaded and applied to other Pivot Grids. 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. If the changes have not yet been applied when switching to another PivotGrid Designer page or closing the designer, a warning dialog box is automatically invoked.
To learn more about the layout, see Layout.
Save and Restore Layout in Code
The Pivot Grid control provides methods to save a control layout to and then restore it from a data store. All these methods start with either SaveLayoutTo… or RestoreLayoutFrom…. You can save and restore a layout by:
- using a system registry path (e.g., PivotGridControl.SaveLayoutToRegistry, PivotGridControl.RestoreLayoutFromRegistry);
- using a stream (e.g., PivotGridControl.SaveLayoutToStream, PivotGridControl.RestoreLayoutFromStream);
- using an XML file (e.g., PivotGridControl.SaveLayoutToXml, PivotGridControl.RestoreLayoutFromXml).
See the following member table to find a complete list of methods you can use to save/restore the Pivot Grid’s layout: Member Table: Save and Restore Layout.
Important
For Pivot Grid control fields created at runtime, initialize their PivotGridFieldBase.Name properties manually to allow the control layout to be correctly saved and restored.
The following sample code saves a Pivot Grid Control’s layout to a memory stream and then restores it.
System.IO.Stream stream;
stream = new System.IO.MemoryStream();
pivotGridControl1.SaveLayoutToStream(stream);
stream.Seek(0, System.IO.SeekOrigin.Begin);
// ...
pivotGridControl1.RestoreLayoutFromStream(stream);
stream.Seek(0, System.IO.SeekOrigin.Begin);
Layout Options
The SaveLayoutTo… and RestoreLayoutFrom… methods have two overloads (with and without the options parameter of the OptionsLayoutBase type).
When calling the SaveLayoutTo… or RestoreLayoutFrom… method without the options parameter, only a subset of the control’s settings is saved/restored. By default, 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.
Certain options, such as appearance and format rules, are not saved/restored by default. To manually specify which options need to be saved/restored, use the control’s PivotGridControl.OptionsLayout property.
You can also use the SaveLayoutTo… and RestoreLayoutFrom… methods with the options parameter. Create an instance of the PivotGridOptionsLayout class, customize it, and pass it as a parameter. Only the options that are enabled in this object will be saved/restored. Specific options that have been disabled in the options parameter are not affected. To save all options, pass null (Nothing in Visual Basic) or a static OptionsLayoutBase.FullLayout property as the options parameter.
Upgrade Layout
The Pivot Grid allows you to control the upgrade of a layout while it is being loaded from a data store (a stream or string).
You can control the upgrade of the Pivot Grid layout by handling the PivotGridControl.LayoutUpgrade event. The event occurs when a layout is restored from a data store, and its version differs from the version of the current Pivot Grid layout. The layout version is specified using the OptionsLayoutBase.LayoutVersion property. Assign this property to distinguish between the versions of stored layouts and the current Pivot Grid layout. If the versions do not match, you can customize the control to prevent the current layout from being overwritten.
Use the LayoutUpgradeEventArgs.PreviousVersion property to get the version of the layout being restored. Depending on the result, you can implement the required routine that will upgrade the old layout.
You can also control the upgrade of the Pivot Grid layout by handling the PivotGridControl.BeforeLoadLayout event. Handling this event allows you to prevent the layout from being restored from storage and from being applied to the current control. To stop the layout from being restored, set the event parameter LayoutAllowEventArgs.Allow property to false.
Use the LayoutUpgradeEventArgs.PreviousVersion property to get the version of the layout being restored. This can be compared with the version of the current layout specified by the OptionsLayoutBase.LayoutVersion property. If the versions do not match, the layout restoration may be canceled.