[Expand]General Information
[Collapse]WinForms Controls
  .NET Core Support
 [Expand]What's Installed
 [Expand]Build an Application
 [Expand]Controls and Libraries
 [Collapse]Common Features
  [Expand]Data Binding Common Concepts
  [Expand]Data Source Wizard
  [Expand]Application Appearance and Skin Colors
  [Expand]Filtering UI Context
   Find Panel Syntax
  [Expand]Graphics Performance and High DPI
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML-inspired Text Formatting
  [Expand]Tooltip Management
  [Collapse]Save and Restore Layouts
    How to: Save a control's layout to a stream
    How to: Save a control's layout to the system registry
    Layout Options (XtraGrid, XtraPivotGrid)
    How to: Save a control's layout to a XML file
    Upgrading Layout
   Clipboard - Copy and Paste Operations. Data Formatting
   Version Compatibility: Default Property Values
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Office File API
[Expand]Report and Dashboard Server
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Upgrading Layout

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.

Expanded 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.

Expanded Layout Loading Specifics (XtraGrid, XtraPivotGrid)

Grid Control and PivotGrid 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.

Expanded See Also

Is this topic helpful?​​​​​​​