BaseView.LayoutUpgrade Event

Occurs when a layout is restored from storage (a stream, xml file or system registry) and its version differs from the version of the current View’s layout.

Namespace: DevExpress.XtraGrid.Views.Base

Assembly: DevExpress.XtraGrid.v24.1.dll

NuGet Packages: DevExpress.Win.Grid, DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Data")]
public event LayoutUpgradeEventHandler LayoutUpgrade

VB.NET

<DXCategory("Data")>
Public Event LayoutUpgrade As LayoutUpgradeEventHandler

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 View’s layout immediately after an earlier version of the View’s layout has been loaded from storage (a stream, xml file or system registry). For instance, the layout being loaded has overridden specific filtering or grouping 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 BaseView.OptionsLayout object.

Consider an example. When the first version of an application was released the version of the grid’s layout was not specified (it was set to an empty string, by default). While running this application an end-user hid specific columns and saved the layout, say, to an XML file. Then a new version of the application was designed (for instance, it added new columns and data could be grouped by any of these columns). 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 columns and restore grouping by these columns, if required.

If versions of the current layout and layout being loaded match, the LayoutUpgrade event will not be fired.

C#

gridView1.LayoutUpgrade += (s, ea) => {
    GridView view = s as GridView;
    view.Columns[0].Visible = false;
};

VB.NET

AddHandler GridView1.LayoutUpgrade, Sub(s, ea)
    Dim view As GridView = TryCast(s, GridView)
    view.Columns("ID").Visible = False
End Sub

The ColumnView.OptionsLayout property provides multiple settings which control how the layout is restored from the storage. It also specifies which settings should be stored when the layout is saved to storage.