[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
  [Collapse]Behaviors
    File and Folder Browser Behaviors
    Persistence Behavior
    Indicator Behaviors
    Stub Glyph Behavior
    Banner Behavior
    Breadcrumb Behavior
    Drag-and-Drop Behavior
    Magnifier Behavior
    Pager Navigation Behavior
    Scrollbar Annotation Behavior
    Snap Window Behavior
  [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]Menus
  [Expand]Tooltip Management
  [Expand]Save and Restore Layouts
   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]Reporting
[Expand]Report and Dashboard Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

Persistence Behavior

Use PersistenceBehavior to automatically save and restore a form’s bounds and its state to/from a file or the system registry. Along with the form-related information, it can optionally save/restore the layout of all DevExpress controls/components that reside within this form.

You can also bind PersistenceBehavior to an individual serializable DevExpress control/component to automatically save/restore only its layout.

Note

Use Workspace Manager to manually save/restore the layout of DevExpress controls/components, and the form's bounds and state when necessary. The Workspace Manager provides additional features:

  • maintain multiple layouts (workspaces);
  • animation effects when you apply workspaces.

The following animation illustrates a form with attached PersistenceBehavior.

Expanded Save&restore the form's bounds and state and its child controls' layouts to a file/system registry

  1. Drop the BehaviorManager component on the form. Invoke the Behavior Editor from the smart tag menu and add PersistenceBehavior.

  2. Ensure the Target property is set to the form.
  3. Optionally set the StoreChildLayouts setting to True to save/restore the layouts of all serializable DevExpress components within this form.

    Examples of serializable components are BarManager, DockManager, GridControl, TreeList, VGridControl, LayoutControl, GaugeControl, DocumentManager.

    Tip

    You can disable layout (de)serialization for an individual component with the static PersistenceBehavior.SetSerializationEnabled method. Call this method before the layout is saved/restored (typically, in the form's constructor). See an example below.

  4. Use the Storage property to specify the storage type (the system registry or a XML file).
  5. Set the Path property to a target system registry key or the path to a target XML file.

    If you leave this property set to an empty string, PersistenceBehavior will store the layout in the current directory. The file's name will be generated based on the target component's name or its type name (if the name is empty).

When you need to create PersistenceBehavior in code, do so in the form's constructor after the InitializeComponent method call. The following code shows how to create PersistenceBehavior in code to save/restore the layout of the form and DevExpress controls in this form. The example excludes a GaugeControl from (de)serialization.

Binding to Form Specifics

PersistenceBehavior bound to a form saves the layout when the Form.FormClosed event fires, and it restores the saved layout when the Form.Load event fires.

Ensure safe layout deserialization

If you create DevExpress controls/components at design time, call the controls' ForceInitialize methods (e.g., BarManager.ForceInitialize, DockManager.ForceInitialize and GridControl.ForceInitialize) before you restore control layouts during form initialization. These methods finish control initialization and ensure you can safely modify their settings (e.g., by loading a layout). The following example calls the RibbonControl.ForceInitialize method before the Form.Load event by overriding the form's OnLoad method.

Expanded Save&restore a specific control's (component's) layout

You can save/restore a specific control's layout using the SaveLayoutTo... and RestoreLayoutFrom... methods the control provides. You can also use PersistenceBehavior for the same purpose.

  1. Create PersistenceBehavior as demonstrated above.
  2. Instead of setting its Target property to a form, set it to a specific control/component.

Target controls and components include: DockManager, GridControl, TreeList, VGridControl, LayoutControl, DocumentManager's Views, etc.

Binding to Control specifics

When bound to a control, PersistenceBehavior handles the Control.HandleCreated and Control.HandleDestroyed events to automatically restore/save the control's layout.

Binding to Component specifics

When bound to a component (e.g., DockManager, DocumentManager's Views), PersistenceBehavior saves/restores the layout when the owner form is closed and loaded (the Form.FormClosing and Form.Load events, respectively). If you set the PersistenceBehavior.StoreChildLayouts to True, PersistenceBehavios saves/restores the layout of all serializable controls within the owner form.

Expanded Additional customization: layout (de)serialization options and deserialization events.

DevExpress controls provide settings to customize the layout save/restore operations. These settings allow you to specify:

  • which properties are saved/restored;
  • whether or not new items are retained after you load an old layout;
  • whether or not to discard the items that do not exist in the control, but still exist in the loaded layout
  • the layout version.

The list below shows the objects used to access the layout-aware settings.

When you load a layout, you can perform additional layout customization by handling the LayoutUpgrade deserialization events.

To prevent a layout from being loaded, you can handle the BeforeLoadLayout events.

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