Save and Restore Layout
- 4 minutes to read
The Pivot Grid layout determines the position and appearance of its visual elements. You can modify a 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.
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.
New columns are fields in the control, old columns are fields in the saved layout.
If old and new fields have the same ID, the control applies the saved layout changes to the fields in the control.
If old and new fields have the different ID, the behavior is as follows:
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.
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.