Save and Restore Layout
- 3 minutes to read
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.
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.
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.
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… 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 PivotGridOptionsLayout.Columns.AddNewColumns and PivotGridOptionsLayout.Columns.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 |
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.