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
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);
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:
- Data Grid: ColumnView.OptionsLayout, WinExplorerView.OptionsLayout
- Tree List: TreeList.OptionsLayout
- Bars library: BarManager.OptionsLayout
- Application UI Manager: BaseView.OptionsLayout
- Docking: DockManager.SerializationOptions
- Form Layout Control: LayoutControl.OptionsSerialization
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:
- Data Grid: BaseView.LayoutUpgrade
- Tree List: TreeList.LayoutUpgrade
- Bars Library: BarManager.LayoutUpgrade
- Application UI Manager: BaseView.LayoutUpgrade
- Docking: DockManager.LayoutUpgrade
- Form Layout Control: LayoutControl.LayoutUpgrade
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:
- Data Grid: BaseView.BeforeLoadLayout
- Tree List: TreeList.BeforeLoadLayout
- Bars Library: BarManager.BeforeLoadLayout
- Docking: DockManager.BeforeLoadLayout
- Form Layout Control: LayoutControl.BeforeLoadLayout
- Scheduler: SchedulerControl.BeforeLoadLayout
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
Use Workspace Manager to save/restore a layout of controls. Handle the WorkspaceManager.PropertyDeserializing event to prevent a property from being restored.
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:
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.
- 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 be closed, save UserLookAndFeel.Default.SkinName and UserLookAndFeel.Default.ActiveSvgPaletteName property values.
- When your application starts, read the saved settings and pass them to the UserLookAndFeel.Default.SetSkinStyle method as parameters.
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.
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;
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.