PivotGridControl.LayoutUpgrade Event
Occurs when a layout is restored from a data store (a stream, xml file or the system registry) and its version is different than that of the control’s current layout version.
Namespace: DevExpress.XtraPivotGrid
Assembly: DevExpress.XtraPivotGrid.v20.2.dll
NuGet Package: DevExpress.Win.PivotGrid
Declaration
Event Data
The LayoutUpgrade event's data class is LayoutUpgradeEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| NewHiddenItems | Returns an array of items that exist in the current control but do not exist in the layout being loaded. These items are hidden. This property is in effect for the LayoutControl. |
| PreviousVersion | Returns the textual representation of the previous layout version. |
Remarks
This event lets you customize the control’s layout immediately after an earlier version of the control’s layout has been loaded from a data store (a stream, xml file or the system registry). For instance, the layout being loaded has overridden specific filtering or sorting settings of the new layout. So the LayoutUpgrade event can be handled to restore layout settings specific to the new layout.
To enable the LayoutUpgrade event to be called you need to assign different versions to different layouts via the OptionsLayoutBase.LayoutVersion property of the PivotGridControl.OptionsLayout object.
Consider an example. When the first version of an application was released the version of the control’s layout was not specified (it was set to an empty string, by default). While running this application an end-user hid specific fields and saved the layout, say, to an XML file. Then a new version of the application was designed (for instance, it added new fields and data could be filtered against any of these fields). At design time the new layout in the new application should be assigned a specific version (say, “1.1”). In this case, when an end-user runs the new application and loads the previously saved layout from the XML file the LayoutUpgrade event will be fired since the versions of the current layout (“1.1”) and the layout being loaded (“”) won’t match. In the LayoutUpgrade event handler you can specify the positions of the newly added fields and restore the filter settings of these fields, if required.
If the versions of the current layout and the layout being loaded match, the LayoutUpgrade event will not fire.
The PivotGridControl.OptionsLayout property provides multiple settings which control how the layout is restored from the data store. It also specifies which settings should be stored when the layout is saved to the data store.
The PivotGridControl.BeforeLoadLayout event can be handled to prevent a layout from being loaded from a data store.