wpf-7391-common-concepts-save-and-restore-layouts.md
DevExpress WPF Controls allow you to save (serialize) their layouts to an XML file/Stream and then restore (deserialize) them.
DevExpress WPF Controls use the DXSerializer class to save/restore their layouts. This class contains events that you can use to customize the serialization/deserialization processes. Refer to the following section for more information on how to cancel layout restoration, restore items from a collection, and more: Advanced Scenarios.
Define unique Names for a control (and each of its parts) whose layout you want to save/restore. The DXSerializer uses these names to identify elements during the save/restore operation.
Call the control’s SaveLayoutTo * method to save its layout.
To restore a control’s layout saved to an XML file , call the control’s RestoreLayoutFromXML method. To restore a control’s layout saved to a Stream, call the control’s RestoreLayoutFromStream method.
View Example: Save Grid Layout and Restore It from a Memory Stream
View Example: Use the Layout Upgrade Event to Upgrade a Layout from One Version to Another
Note
The serialization mechanism does not save properties that are not set locally and have default values. This mechanism resets all serializable properties to their default values before the restore layout operation.
|
Control
|
Save Layout Methods
|
Restore Layout Methods
|
Documentation Topic (Control Specifics)
|
Uses DXSerializer
| | --- | --- | --- | --- | --- | |
Bars
|
|
RestoreLayoutFromStream(Stream)
|
Saving and Restoring a Bar Layout
|
| |
|
| |
Charts
|
|
|
Save and Load the Chart Layout
|
| |
|
| |
LayoutControlBase and its descendants (FlowLayoutControl, TileLayoutControl, LayoutControl, DataLayoutControl)
|
|
|
|
| |
DockLayoutManager
|
|
RestoreLayoutFromStream(Stream)
|
Save and Restore the Layout of Dock Panels and Controls
|
| |
|
| |
DXTabControl
|
|
RestoreLayoutFromStream(Stream)
|
|
| |
|
| |
GridControl/TreeListControl/GanttControl
|
|
RestoreLayoutFromStream(Stream)
|
|
| |
|
| |
PivotGridControl
|
|
RestoreLayoutFromStream(Stream)
|
|
| |
RestoreLayoutFromStreamAsync(Stream)
| |
|
| |
RestoreLayoutFromXmlAsync(String)
| |
RibbonControl
|
|
|
|
| |
|
| |
ThemedWindow
|
|
RestoreLayoutFromStream(Stream)
|
|
| |
|
|
Note
If a control uses the DXSerializer class to save/restore its layout, you can use the DXSerializer’s events to customize the control’s serialization/deserialization.
Refer to the following section for more information on how use these events to cancel layout restoration, restore items from a collection, and more: Advanced Scenarios.
The WriteToXML(XmlWriter) and ReadFromXML(XmlReader) methods of the LayoutControlBase and its descendants do not use the DXSerializer class. Use the DXSerializer to customize serialization/deserialization of these controls (for example, cancel layout restoration, restore items from a collection, and so on).
Each control saves its layout to a separate XML file/Stream.
Use the DXSerializer to save/restore layouts of a container (Window, View, UserControl, Control) and its child serializable[1] DevExpress WPF Controls to an XML file/Stream.
The DXSerializer saves/restores layouts of controls that exist in the application’s visual tree. Because of that, it does not save/restore contents of the unopened DXTabControl/LayoutGroup tabs.
To save/restore layouts of serializable[1] DevExpress WPF Controls that are placed into a DXTabControl/LayoutGroup tab, set the tab’s DXTabControl.TabContentCacheMode/LayoutGroup.TabContentCacheMode property to TabContentCacheMode.CacheAllTabs. In this case, the tab loads its contents to a visual tree when the control is loaded.
View Example: Serialize DockLayoutManager When TabbedDocumentUIService Is Used
Choose the target object whose layout you want to save/restore. It can be any parent container (Window, View, UserControl) that stores a serializable[1] DevExpress WPF Control.
If your target object contains multiple serializable[1] child objects of the same type, specify unique SerializationIDs (within the container) for each of these objects.
Call any DXSerializer.Serialize method. Serialize methods save layouts of visual DevExpress controls to a single XML file/Stream.
Call any DXSerializer.Serialize method. These methods save the layout of visual DevExpress controls to a single XML file/Stream.
The following code saves the layout of the window and its child GridControls to an XML file:
<Window . . .
xmlns:dx="http://schemas.devexpress.com/winfx/2008/xaml/core"
x:Name="mainWindow">
<Grid>
<dxg:GridControl dx:DXSerializer.SerializationID="gridControl1">
<!--...-->
</dxg:GridControl>
<dxg:GridControl dx:DXSerializer.SerializationID="gridControl2">
<!--...-->
</dxg:GridControl>
</Grid>
</Window>
using DevExpress.Xpf.Core.Serialization;
private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e) {
DXSerializer.Serialize(mainWindow, "Layout.xml");
}
Imports DevExpress.Xpf.Core.Serialization
Private Sub Window_Closing(ByVal sender As Object, ByVal e As RoutedEventArgs)
DXSerializer.Serialize(mainWindow, "Layout.xml");
End Sub
To restore a saved layout, you should use the DXSerializer.Deserialize method that corresponds to the saved layout structure (an XML file or a Stream).
For example, if you saved a control’s layout to a Stream (with the DXSerializer.Serialize(DependencyObject,String) method), you should call the DXSerializer.Deserialize(DependencyObject,String) method to restore the saved layout from that Stream.
The following code restores layouts of the mainWindow and its child GridControls that you saved in the previous section:
using DevExpress.Xpf.Core.Serialization;
private void Window_Loaded(object sender, RoutedEventArgs e) {
DXSerializer.Deserialize(mainWindow, "Layout.xml");
}
Imports DevExpress.Xpf.Core.Serialization
Private Sub Window_Loaded(ByVal sender As Object, ByVal e As RoutedEventArgs)
DXSerializer.Deserialize(mainWindow, "Layout.xml");
End Sub
To save/restore an application layout in MVVM applications, you can use the LayoutSerializationService and CurrentWindowSerializationBehavior classes.
These classes are based on the DXSerializer and you can use its events to customize a layout’s save/restore processes.
Section : Advanced Scenarios
Call the SaveApplicationThemeName/UpdateApplicationThemeName methods to save/restore the theme applied to your application, respectively.
The following code sample saves the applied theme on application exit and restores it on application startup:
public partial class App : Application {
protected override void OnStartup(StartupEventArgs e) {
base.OnStartup(e);
DevExpress.Xpf.Core.ApplicationThemeHelper.UpdateApplicationThemeName();
}
protected override void OnExit(ExitEventArgs e) {
base.OnExit(e);
DevExpress.Xpf.Core.ApplicationThemeHelper.SaveApplicationThemeName();
}
private void OnAppStartup_UpdateThemeName(object sender, StartupEventArgs e) {
DevExpress.Xpf.Core.ApplicationThemeHelper.UpdateApplicationThemeName();
}
}
Partial Public Class App
Inherits Application
Protected Overrides Sub OnStartup(ByVal e As StartupEventArgs)
MyBase.OnStartup(e)
DevExpress.Xpf.Core.ApplicationThemeHelper.UpdateApplicationThemeName()
End Sub
Protected Overrides Sub OnExit(ByVal e As ExitEventArgs)
MyBase.OnExit(e)
DevExpress.Xpf.Core.ApplicationThemeHelper.SaveApplicationThemeName()
End Sub
Private Sub OnAppStartup_UpdateThemeName(ByVal sender As Object, ByVal e As StartupEventArgs)
DevExpress.Xpf.Core.ApplicationThemeHelper.UpdateApplicationThemeName()
End Sub
End Class
The serialization mechanism caches property descriptors, attributes, and so on when you restore the control layout for the first time. As a result, the first restore action takes more time than subsequent actions. Execute the first restore operation asynchronously on application startup to avoid this behavior:
public partial class App : Application {
protected override void OnStartup(StartupEventArgs e) {
base.OnStartup(e);
Dispatcher.BeginInvoke(
new Action(() => {
GridControl grid = new GridControl();
grid.View = new TableView();
grid.RestoreLayoutFromXml("Layout.xml");
}),
DispatcherPriority.ApplicationIdle
);
}
}
Public Partial Class App
Inherits Application
Protected Overrides Sub OnStartup(ByVal e As StartupEventArgs)
MyBase.OnStartup(e)
Dispatcher.BeginInvoke(New Action(Function()
Dim grid As GridControl = New GridControl()
grid.View = New TableView()
grid.RestoreLayoutFromXml("Layout.xml")
End Function), DispatcherPriority.ApplicationIdle)
End Sub
End Class
You can use the DXSerializer‘s events to perform the following actions:
Topic : DXSerializer Events - Advanced Scenarios
Footnotes