Save and Restore Layouts
- 5 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, their sort, group, summary, and filter settings.
You can customize which properties need to be saved/restored and perform actions on layout loading.
Two dedicated DevExpress components allow you to save/restore the layout of all DevExpress controls within a form along with that form’s bounds and state. See the following sections for more information.
- Save & restore the form’s bounds and state and all child controls’ layouts
- Save & restore the layouts of individual controls
- Layout options
- Post-restore customization
- Cancel layout restore operations
Save & restore the form’s bounds and state and all child controls’ 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.
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.
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.
To save layouts of controls positioned within a form, handle the Form.FormClosing event. For controls residing within a UserControl, override the UserControl.Dispose method.
Layout options
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 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 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[0].Visible = false;
};
A control’s OptionsLayout.LayoutVersion property allows you to explicitly label different layout versions. The LayoutUpgrage event is raised only when the loaded layout version differs from the currently active one.
See Upgrading Layout for more information.
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;
};