Serialization in Windows Forms Docking Manager

27 Apr 20218 minutes to read

State persistence is the combined process of serialization and deserialization. Docking manager provides built-in state persistence functionality to save and load the layout. Layout of the dock panels hold the state, side, position, and visibility of each child. This layout information can be stored in isolated storage, an XML, or binary file.

Auto serialization

Docking manager supports AutoSave that allows to persist its state automatically. To enable this functionality, set the PersistState property to true. The default value of the PersistState property is false.

C#

this.dockingManager1.PersistState = true;

VB.NET

Me.dockingManager1.PersistState = True

Persisting dock state in default storage

Docking manager saves the dock state in an isolated storage format while WindowClosing.

Save state

To save the AutoPersist state of docking manager, call the SaveDockState function in its closing event.

Functions	Description
SaveDockState	Saves the current dock state to isolated storage.
SaveDockState(AppStateSerializer serializer)	Saves the current dock state information to the specified AppStateSerializer. Parameter is serializer that is an instance of AppStateSerializer class.
SaveDockState(AppStateSerializer serializer, Control ctrl)	Saves the dock state information for the specified dockable control. The parameters are serializer that is an instance of AppStateSerializer class, and control that indicates the docked control.

C#

this.dockingManager1.SaveDockState();

this.dockingManager1.SaveDockState(serializer);

this.dockingManager1.SaveDockState(serializer, this.listBox1);

VB.NET

Me.dockingManager1.SaveDockState()

Me.dockingManager1.SaveDockState(serializer)

Me.dockingManager1.SaveDockState(serializer, this.listBox1)

Load state

To load the AutoPersist state of the docking manager, call the LoadDockState function in its loaded event.

Functions	Description
LoadDockState	Reads the persisted dock state from the isolated storage.
LoadDockState(AppStateSerializer serializer)	Reads a previously serialized dock state using the AppStateSerializer object. The parameter is a serializer, which is an instance of AppStateSerializer class.
LoadDockState(AppStateSerializer serializer, Control ctrl)	Reads a previously serialized dock state for the specified dockable control and applies the new state. The parameters are serializer and control. Serializer is an instance of AppStateSerializer class, and control indicates the docked control.

C#

this.dockingManager1.LoadDockState();

this.dockingManager1.LoadDockState(serializer);

this.dockingManager1.LoadDockState(serializer, this.listBox1);

VB.NET

Me.dockingManager1.LoadDockState(serializer)

Me.dockingManager1.LoadDockState();

Me.dockingManager1.LoadDockState(serializer, this.listBox1)

Serialize dock state as XML

When the docking manager PersistState property is set, it saves the dock state into default persistence medium ‘IsolatedStorage’. To store the dock state to some other medium like XML, it can be done as follows:

C#

using Syncfusion.Runtime.Serialization;

// Persist the dock state into XML File named Dock1.xml. Use this line in the constructor of the control that hosts the docking layout. 

public form1()

{ 

AppStateSerializer.InitializeSingleton(SerializeMode.XMLFile,"Dock1"); 

}

VB.NET

Imports Syncfusion.Runtime.Serialization

' Persist the dock state into XML File named Dock1.xml. Use this line in the constructor of the control that hosts the docking layout. 

Private Sub New()

     AppStateSerializer.InitializeSingleton(SerializeMode.XMLFile, "Dock1")

End Sub()

Serialize dock state in memory stream

To persist docking information in a database, serialize the state into a memory stream. After serialized, the stream will be written in database. The field where the dock state will be saved is binary.

Storing State

C#

// Saving dock state to memory stream  

MemoryStream ms = new MemoryStream();

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.BinaryFmtStream, ms);

this.dockingManager1.SaveDockState(serializer);

serializer.PersistNow();

//Code to store the memory stream into database

VB.NET

' Saving dock state to memory stream  

Dim ms As MemoryStream = New MemoryStream()

Dim serializer As AppStateSerializer = New AppStateSerializer(SerializeMode.BinaryFmtStream, ms)

Me.dockingManager1.SaveDockState(serializer) 

serializer.PersistNow() 

'Code to store the memory stream into database

Retrieving State

C#

//Code to retrieve data(stream) from database

MemoryStream ms = new MemoryStream(val);

ms.Position = 0;

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.BinaryFmtStream, ms);

this.dockingManager1.LoadDockState(serializer);

VB.NET

'Code to retrieve data(stream) from database

Dim ms As MemoryStream = New MemoryStream(value)

ms.Position = 0

Dim serializer As AppStateSerializer = New AppStateSerializer(SerializeMode.BinaryFmtStream, ms)

Me.dockingManager1.LoadDockState(serializer)

Serialize dock state in binary format

C#

// To save

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.BinaryFile, "MyFile");

this.dockingManager1.SaveDockState(serializer);

serializer.PersistNow();


// To load

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.BinaryFile, "MyFile");

this.dockingManager1.LoadDockState(serializer);

VB.NET

' To save

Dim serializer As New AppStateSerializer(SerializeMode.BinaryFile, "MyFile")

Me.dockingManager1.SaveDockState(serializer)

serializer.PersistNow()


' To load

Dim serializer As New AppStateSerializer(SerializeMode.BinaryFile, "MyFile")

Me.dockingManager1.LoadDockState(serializer)

Serialization in isolated storage medium

C#

// To save

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.IsolatedStorage, "MyFile");

this.dockingManager1.SaveDockState(serializer);

serializer.PersistNow();


// To load

AppStateSerializer serializer = new AppStateSerializer(SerializeMode.IsolatedStorage, "MyFile");

this.dockingManager1.LoadDockState(serializer);

VB.NET

' To save

Dim serializer As New AppStateSerializer(SerializeMode.IsolatedStorage, "MyFile")

Me.dockingManager1.SaveDockState(serializer)

serializer.PersistNow()


' To load

Dim serializer As New AppStateSerializer(SerializeMode.IsolatedStorage, "MyFile")

Me.dockingManager1.LoadDockState(serializer)

Calling the GetSerializedControls function returns the serialized control collection enumerator in the specified serializer. This can be done using the following code.

Parameter	Description
Serializer	An instance of AppStateSerializer class.

C#

this.dockingManager1.GetSerializedControls(serializer);

Console.Write("Serialized controls :" + this.dockingManager1.GetSerializedControls(serializer));

VB.NET

Me.dockingManager1.GetSerializedControls(serializer)

Console.Write("Serialized controls :" + Me.dockingManager1.GetSerializedControls(serializer))

Serialization or de-serialization for a particular control

In the docking manager, you can perform serialization or de-serialization for a particular control by using its functions such as SaveDockState and LoadDockState.

C#

//Saves DockState for specific controls

this.dockingManager1.SaveDockState(serialize, this.panel1);

serialize.PersistNow();

//Loads the DockState for specific controls

this.dockingManager1.LoadDockState(serialize, this.panel1);

VB.NET

'Saves DockState for specific controls

Me.dockingManager1.SaveDockState(serialize, Me.panel1)

serialize.PersistNow()

'Loads the DockState for specific controls

Me.dockingManager1.LoadDockState(serialize, Me.panel1)

Restore to initial state

The LoadDesignerDockState function is used to restore the initial Windows Forms designer state of the docking window.

C#

this.dockingManager1.LoadDesignerDockState();

VB.NET

Me.dockingManager1.LoadDesignerDockState()

Serialize dynamically added children

By default, the docking manager cannot deserialize its saved layout properly, when its child collection is modified after the DockState is saved.

Since the docking manager state persistence feature is implemented in such a way that it matches the child collection of saved layout with current layout internally and loads properly when the children collection remains same. It results in improper layout when any child collection changes dynamically.

NOTE

Docking State persistence will be applied to active Docking Children. So it must to load dynamically added controls into DockingManager before applying Deserialization process.
Find the sample with serialization support in the following location.
C:\Users\<User>\AppData\Local\Syncfusion\EssentialStudio\Version Number\Windows\Tools.Windows\Samples\Docking Manager\StatePersistence