KB Article T931828
Visible to All Users

Save and Restore Layouts of DevExpress controls - WinForms Cheat Sheet

Other DevExpress WinForms Cheat Sheets


A contol's layout includes multiple settings: visibility, position, size of the control's visual elements, various control options (sort, group, summary and filter options), appearance settings (optionally), etc. You can save/restore the layout of DevExpress controls to/from an XML file, stream, or system registry.

To save/restore the layout of individual controls (components), use these controls' methods:

  • SaveLayoutToRegistry, SaveLayoutToStream, and SaveLayoutToXml
  • RestoreLayoutFromRegistry, RestoreLayoutFromStream, and RestoreLayoutFromXml

The following components allow you to save a form's state and layouts of multiple DevExpress controls that reside within this form:

  • Persistence Behavior - automatically saves layout information to a file or system registry when the Form.FormClosed event fires and restores a saved layout when the Form.Load event fires;
  • Workspace Manager - allows you to manually save layout information to a file, stream, or system registry. Supports multiple layouts (workspaces) and animation effects. WorkspaceManager also allows you to manage serialization/deserialization of properties in the PropertySerializing and PropertyDeserializing event handlers.

See the following documentation topic for more information: Save and Restore Layouts of DevExpress controls

DevExpress controls share the same principles to control customization. The approaches described below can be applicable to multiple controls, although text may not refer to these controls directly.

Examples

Save a control's layout to a stream

Use the SaveLayoutToStream and RestoreLayoutFromStream methods.

C#
System.IO.Stream str; //... // Save the layout to a new memory stream. str = new System.IO.MemoryStream(); gridControl1.FocusedView.SaveLayoutToStream(str); str.Seek(0, System.IO.SeekOrigin.Begin); // ... // Load the saved layout. gridControl1.FocusedView.RestoreLayoutFromStream(str); str.Seek(0, System.IO.SeekOrigin.Begin);
Save a control's layout to the system registry

Use the SaveLayoutToRegistry and RestoreLayoutFromRegistry methods:

C#
string regKey = "DevExpress\\XtraGrid\\Layouts\\MainLayout"; advBandedGridView1.SaveLayoutToRegistry(regKey); // ... advBandedGridView1.RestoreLayoutFromRegistry(regKey);
Save a control's layout to an XML file

Use the SaveLayoutToXml and RestoreLayoutFromXml methods.

C#
string fileName = "layout.xml"; treeList1.SaveLayoutToXml(fileName); // ... treeList1.RestoreLayoutFromXml(fileName);
Specify which settings to save/restore

DevExpress controls contain properties that specify which settings need to be saved/restored when you save/restore a control's layout.
These properties are typically called OptionsLayout and OptionsSerialization. Below are some examples:

Customize the layout after it has been restored

Use a control's LayoutUpgrade event to accomplish this task:

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

Note: the LayoutUpgrage event is raised only when the loaded layout version differs from the current version. Use the control's OptionsLayout.LayoutVersion property to assign a version number to a layout.

Examples of LayoutUpgrage events in DevExpress controls:

Prevent a layout from being loaded in certain cases (for example, if the loaded layout's version does not match the control's LayoutVersion)

Handle a control's BeforeLoadLayout event to prevent the layout from being loaded:

C#
gridView1.BeforeLoadLayout += (s, ea) => { GridView view = s as GridView; if (ea.PreviousVersion != view.OptionsLayout.LayoutVersion) ea.Allow = false; };

Examples of BeforeLoadLayout events in DevExpress controls:

Serialize a custom property of a DevExpress control's descendant

To serialize a custom property of a simple type (integer, string, etc.), mark this property with the XtraSerializableProperty attribute. Here is an example:

C#
public class MyGridColumn : GridColumn{ public MyGridColumn() : base() { } //... private int oldVisibleIndex = -1; [XtraSerializableProperty, XtraSerializablePropertyId(LayoutIdLayout)] public int OldVisibleIndex { get { return oldVisibleIndex; } set { if (value == -1) return; oldVisibleIndex = value; } } }

Refer to the following KB article for more information on how to process properties of complex types and collection properties: How to serialize a custom property of the DevExpress control's descendant

Prevent property value restoration

Use Workspace Manager to save/restore a layout of controls. Handle the WorkspaceManager.PropertyDeserializing event to prevent a property from being restored.

C#
void workspaceManager1_PropertyDeserializing(object sender, DevExpress.Utils.PropertyCancelEventArgs ea) { GridView view = ea.Component as GridView; if (view != null && view == gridView1) { ea.Cancel = ea.PropertyName == "MultiSelect"; } }
Reset a layout to its initial state

DevExpress components don't store their previous state anywhere. So, once the state is changed, there is no way to revert to the previous state automatically. To revert a control's layout to its initial state, save the default layout beforehand (when your application starts) and then restore the layout when required:

C#
string _defaultGridLayout = "default.xml"; private void Form1_Load(object sender, EventArgs e) { gridView1.SaveLayoutToXml(_defaultGridLayout); } private void RestoreDefaultLayout() { gridView1.RestoreLayoutFromXml(_defaultGridLayout); }
Save/restore various settings (for example, the current skin)

To save and restore additional settings (e.g., a currently applied skin, a control's size, etc), you can use the standard Windows Forms Application Settings feature. It will allow you to create, store, and maintain custom application and user preferences on client computers.

For example, to save and restore an active skin and skin palette, do the following.

C#
public Form1() { InitializeComponent(); RestoreCustomSettings(); } private void Form1_FormClosing(object sender, FormClosingEventArgs e) { SaveCustomSettings(); } void SaveCustomSettings() { var settings = Properties.Settings.Default; settings.SkinName = UserLookAndFeel.Default.SkinName; settings.Palette = UserLookAndFeel.Default.ActiveSvgPaletteName; settings.Save(); } void RestoreCustomSettings() { var settings = Properties.Settings.Default; if (!String.IsNullOrEmpty(settings.SkinName)) { if (!String.IsNullOrEmpty(settings.SkinName)) { UserLookAndFeel.Default.SetSkinStyle(settings.SkinName, settings.Palette); } else UserLookAndFeel.Default.SetSkinStyle(settings.SkinName); } }

To save and restore additional settings of a specific control, you can declare declare methods like SaveAdditionalSettings and RestoreAdditionalSettings. Invoke SaveAdditionalSettings after the SaveLayoutToXml method invocation and invoke RestoreAdditionalSettings after the RestoreLayoutFromXml method invocation.

If you decide to use the Workspace Manager to save and restore the layout of multiple controls (toolbars, grid, navigation bar, etc.), you can handle WorkspaceManager.AfterApplyWorkspace and restore additional settings from Windows Forms Application Settings in it. Handle WorkspaceSaved to save the settings to Windows Forms Application Settings.

Save/restore a detail View's layout in a master-detail Grid Control

Handle the GridContro.ViewRegistered and GridView.MasterRowExpanding events to access detail Views and restore their layouts. To save a detail View's layout, handle the View.Layout event.

C#
gridControl.ViewRegistered += GridControl_ViewRegistered; gridView.MasterRowExpanding += GridView_MasterRowExpanding; ... private void GridView_MasterRowExpanding(object sender, MasterRowCanExpandEventArgs e) { GridView view = sender as GridView; detailTag = view.GetDataSourceRowIndex(e.RowHandle); } //... int detailTag; private void GridControl_ViewRegistered(object sender, DevExpress.XtraGrid.ViewOperationEventArgs e) { GridView detailView = e.View as GridView; detailView.Tag = detailTag; string fp = GetPath(detailView); if (File.Exists(fp)) detailView.RestoreLayoutFromXml(fp); detailView.Layout += DetailView_Layout; detailView.Disposed += DetailView_Disposed; } private void DetailView_Disposed(object sender, EventArgs e) { GridView detailView = sender as GridView; detailView.Layout -= DetailView_Layout; detailView.Disposed -= DetailView_Disposed; } private void DetailView_Layout(object sender, EventArgs e) { GridView view = sender as GridView; view.SaveLayoutToXml(GetPath(view)); } private static string GetPath(GridView view) { return filePath + $"\\{view.Tag}{view.LevelName}.xml"; } ... static string filePath = System.IO.Directory.GetParent(System.IO.Directory.GetCurrentDirectory()).Parent.FullName;
How to save/restore a level which grouped Grid is expanded to

You can iterate through all group rows (see Accessing Rows in Code. Row Handles) when saving the Grid layout and check whether a group row is expanded using GetRowExpanded. To know when to stop iterating, you can use IsValidRowHandle. To get the group row level, use GetRowLevel:

C#
private void SaveGridLayout() { int maxGroupLevel = -1; int groupRowHandle = -1; int groupLevel = -1; while (gridView.IsValidRowHandle(groupRowHandle)) { if (gridView.GetRowExpanded(groupRowHandle)) { groupLevel = gridView.GetRowLevel(groupRowHandle); if (groupLevel > maxGroupLevel) maxGroupLevel = groupLevel; } groupRowHandle--; } // save maxGroupLevel gridView.SaveLayoutTo..; }

To expand all groups to a specific level when restoring the Grid layout, you can restore maxGroupLevel and expand all group rows using ExpandAllGroups. Then, collapse all groups deeper than maxGroupLevel using CollapseGroupLevel:

C#
private void RestoreGridLayout() { gridView.RestoreLayoutFrom...; int maxGroupLevel = -1; // restore maxGroupLevel gridView.ExpandAllGroups(); int groupLevel = gridView.GroupCount - 1; while (groupLevel > maxGroupLevel) { gridView.CollapseGroupLevel(groupLevel); groupLevel--; } }

To save and restore maxGroupLevel, you can use the standard Windows Forms Application Settings feature we described in the Save/restore various settings (for example, the current skin) example above.

Help us improve this article

Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.