Upgrading Layout
- 3 minutes to read
This topic describes issues that you may encounter while loading a layout from a data store in XtraGrid, XtraPivotGrid, XtraBars, XtraVerticalGrid, Tree List and XtraNavBar controls.
Controlling Layout Loading
Let’s consider the following situation. Assume that you have developed and deployed an application that uses a DevExpress .NET control (XtraGrid, XtraPivotGrid, XtraBars, etc.). The application allows an end-user to customize the layout and save it between application runs. The layout is automatically saved to an XML file when the application closes and loaded when the application starts. So the layout preferences of an end-user are stored in an XML file.
The application evolves and new features are implemented. For instance, new columns (in XtraGrid) and new groups (in XtraNavBar) are added as existing columns are removed, etc. When an end-user starts a new version of the application, the existing layout preferences are automatically loaded from the XML file, thus overriding the layout that was supplied with the new version of the application. As a result, new columns/groups, etc., can be hidden after the layout has been loaded.
To resolve this issue, controls provide two events.
LayoutUpgrade
This event can be handled to customize the control’s layout after a layout has been loaded from a data store and applied to the control.
Note that the LayoutUpgrade event fires only if versions of the layout being loaded and the current control’s layout do not match. Versions can be assigned to the control’s layout via the control’s LayoutVersion property. When the layout is saved, its version is also saved along with all the required layout settings.
When a layout is loaded from a data store, its version is compared with the version of the current layout. If the versions do not match, the LayoutUpgrade event is raised. Otherwise, the event doesn’t fire.
You can handle the LayoutUpgrade to perform necessary customization steps after the layout has been loaded. For instance, you can display the columns that have been added in the new version of the application at a specific position or hide some other columns.
BeforeLoadLayout
This event occurs before a layout being loaded from a data store is applied to a control. By handling this event, it is possible to prevent the layout from being applied. The restoring of the layout can be cancelled, for instance, if the versions do not match.
Layout Loading Specifics (Data Grid, Pivot Grid, TreeList, Vertical Grid)
WinForms Data Grid, Pivot Grid, TreeList, and Vertical Grid controls provide options that control how a layout is saved to/restored from a data store. These options are grouped within the OptionsLayout property. These include options that specify whether or not to save the control’s appearance and data-aware settings, visual options, etc. In addition, there are options that specify what to do with the columns/fields that exist in the layout being loaded, but not in the current control.
By default, the columns that exist in the current control, but not in the layout being loaded, are retained. Also, the columns that exist in the layout being loaded, but not in the current control’s layout, are destroyed.
To change this behavior use the OptionsColumnLayout.AddNewColumns and OptionsColumnLayout.RemoveOldColumns properties of the OptionsLayout object (for the TreeList control, use the AddNewColumns and RemoveOldColumns properties).