Save and Restore Layouts of DevExpress Controls
- 8 minutes to read
DevExpress controls allow you to save their layout information to data stores (XML file, stream and system registry) and then restore it. Different controls save different sets of options. Typically, the saved layout includes the visibility, position, and size of visual elements, and their sort, group, summary, and filter settings.
You can customize which properties need to be saved/restored and perform actions on layout loading.
Important
Deserializing layout settings from untrusted resources may create security issues. Review the following help topic for additional information: Safe Deserialization.
Save & restore the form’s bounds, state and all child control layouts
You can use the following components to save/restore a form’s bounds/state along with the layouts of all DevExpress controls that reside within this form.
- Persistence Behavior (part of the Behavior Feature) - Automatically saves the layout information to a file or the system registry when the Form.FormClosed event fires and restores the saved layout when the Form.Load event fires.
- Workspace Manager - Allows you to manually save the layout information to a file, stream or system registry. Supports multiple layouts (workspaces) and animation effects. Allows you to prevent serialization/deserialization of specific properties.
Save & restore the layouts of individual controls
DevExpress controls and components contain methods used to save/restore their layouts to/from a file/stream/system registry.
- SaveLayoutToRegistry, SaveLayoutToStream and SaveLayoutToXml
- RestoreLayoutFromRegistry, RestoreLayoutFromStream or RestoreLayoutFromXml
You cannot save multiple layouts to a single data store when using these methods. Use Workspace Manager to save multiple layouts to a single file, stream or system registry.
string fileName = "gridlayout.xml";
gridView1.SaveLayoutToXml(fileName);
// ...
gridView1.RestoreLayoutFromXml(fileName);
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);
string regKey = "DevExpress\\XtraGrid\\Layouts\\MainLayout";
advBandedGridView1.SaveLayoutToRegistry(regKey);
// ...
advBandedGridView1.RestoreLayoutFromRegistry(regKey);
When you save a layout to the system registry, you can define an absolute or relative registry key as a destination. For instance, when you specify the “Software\MyCompany\MyProject" destination, the actual path will be the “HKEY_CURRENT_USER\Software\MyCompany\MyProject" path.
When to call the “SaveLayoutTo…” and “RestoreLayoutFrom…” methods
You can handle the Form.Load/UserControl.Load events to restore control layouts.
Handle the Form.FormClosing event to save layouts of controls positioned within a form. For controls that reside within a UserControl, override the UserControl.Dispose method.
Layout Options
DevExpress controls contain settings to customize the layout save/restore operations. These settings allow you to specify:
- which properties are saved/restored;
Tip
If you use Workspace Manager to save/restore layouts, the following events allow you to prevent serialization/deserialization of specific properties: WorkspaceManager.PropertySerializing and WorkspaceManager.PropertyDeserializing.
- 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 exist in the loaded layout;
- the layout version.
The list below shows the objects used to access these layout-specific settings.
- BarManager.OptionsLayout
- BaseView.OptionsLayout (DocumentManager)
- ColumnView.OptionsLayout, WinExplorerView.OptionsLayout (GridControl)
- DockManager.SerializationOptions
- LayoutControl.OptionsSerialization
- NavBarControl.OptionsLayout
- PivotGridControl.OptionsLayout
- SchedulerControl.OptionsLayout
- TileControl.OptionsLayout
- TreeList.OptionsLayout
- VGridControlBase.OptionsLayout
For information on the options available in the Data Grid and Pivot Grid controls, see the following topic: Layout Options (XtraGrid, XtraPivotGrid).
The layout-specific settings the DevExpress controls expose affect all save/restore operations (when you use Persistence Behavior, Workspace Manager or call control.SaveLayoutTo… and control.RestoreLayoutFrom… default overloads).
The controls’ SaveLayoutTo… and RestoreLayoutFrom… methods have overloads with and without the options parameter. For instance, the overloads of the BaseView.SaveLayoutToXml and BaseView.RestoreLayoutFromXml methods are declared as follows.
public void SaveLayoutToXml(string xmlFile)
public void SaveLayoutToXml(string xmlFile, OptionsLayoutBase options)
public void RestoreLayoutFromXml(string xmlFile)
public void RestoreLayoutFromXml(string xmlFile, OptionsLayoutBase options)
The default overloads (without the options parameter) take into account the layout-specific settings exposed by the control. The overloads that have the options parameter take into account the specified settings and ignore the layout-specific settings exposed by the control.
DevExpress.Utils.OptionsLayoutGrid options = new DevExpress.Utils.OptionsLayoutGrid();
options.StoreAppearance = true;
gridView1.SaveLayoutToXml("gridlayout.xml", options);
//...
gridView1.RestoreLayoutFromXml("gridlayout.xml", options);
Post-restore customization
After a layout is restored, you can perform additional customization in a control’s LayoutUpgrade event handler. In the “Customize layout during restoration” demo, a Data Grid’s BaseView.LayoutUpgrade event is handled to hide the first column.
gridView1.LayoutUpgrade += (s, ea) => {
GridView view = s as GridView;
view.Columns["ID"].Visible = false;
};
A control’s OptionsLayout.LayoutVersion property allows you to explicitly label different layout versions. The LayoutUpgrade event is raised only when the loaded layout version differs from the currently active one.
See the following topic for more information: Upgrading Layout.
Cancel layout restore operations
You can handle a control’s BeforeLoadLayout event to prevent a layout from being loaded in certain cases. For instance, you can cancel the restore operation if the loaded layout’s version does not match the control’s LayoutVersion.
gridView1.BeforeLoadLayout += (s, ea) => {
GridView view = s as GridView;
if (ea.PreviousVersion != view.OptionsLayout.LayoutVersion)
ea.Allow = false;
};
Serialize a custom property of a DevExpress control’s descendant
To serialize a custom property of a simple type (for example, int and string), mark this property with the XtraSerializableProperty attribute:
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;
}
}
}
For information on how to serialize properties of complex types and collection properties, see the following KB article: How to serialize a custom property of the DevExpress control’s descendant
Prevent property serialization/deserialization
The Data Grid, TreeList, and Vertical Grid controls introduce events that allow you to save/resotre certain settings. These include:
PropertySerializingPropertyDeserializing
The following example demonstrates how to avoid serializing certain settings:
treeList.PropertySerializing += (s, e) => {
if(e.Owner is TreeListColumn && e.PropertyName == "Caption")
e.Allow = DefaultBoolean.False;
};
Use the Workspace Manager component to save/restore the layout of all controls and manage which individual properties need to be saved/restored. The component contains the WorkspaceManager.PropertySerializing and WorkspaceManager.PropertyDeserializing events to handle save/restore operations of individual properties of controls and components.
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";
}
}
Save/restore various settings (for example, the current skin)
The SaveLayout… methods, Workspace Manager and Persistence Behavior do not save settings other than control layout options.
You can use the standard Windows Forms Application Settings feature to save/restore any setting. It allows you to store and maintain custom application and user preferences on client computers.
For example, do the following to save and restore the active skin and skin palette.
- Double-click the “Settings.settings” file in the Visual Studio Solution Explorer and create two entries of the String type. Set the scope of both entries to “User”.
- When the application is about to close, save the UserLookAndFeel.Default.SkinName and UserLookAndFeel.Default.ActiveSvgPaletteName property values.
- When the application starts, read the saved settings and pass them to the UserLookAndFeel.Default.SetSkinStyle method as parameters.
public Form1() {
InitializeComponent();
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);
}
}
private void Form1_FormClosing(object sender, FormClosingEventArgs e) {
var settings = Properties.Settings.Default;
settings.SkinName = UserLookAndFeel.Default.SkinName;
settings.Palette = UserLookAndFeel.Default.ActiveSvgPaletteName;
settings.Save();
}
Cheat Sheets and Best Practices
Read the following quick-reference guide for additional information and examples:
Save and Restore Layouts of DevExpress Controls