Save and Restore Layout
- 4 minutes to read
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
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
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);
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.
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.
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.