Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [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]Expressions
  [Expand]Behaviors
  [Expand]Application Appearance
  [Expand]Filtering UI Context
  [Expand]High DPI Support
  [Expand]Scaffolding Wizard
  [Expand]Formatting Values
   HTML Text Formatting
  [Expand]Menus
  [Expand]Tooltip Management
  [Collapse]Saving and Restoring Layouts
    How to: Save Layout to a Stream
    Saving and Restoring Layout Basics
    How to: Save Layout to the System Registry
    Layout Options (XtraGrid, XtraPivotGrid)
    How to: Save Layout to 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]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

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.

How would you rate this topic?​​​​​​​