Edit this page

Save/Load Layout

This feature is available with R2 2016 Service pack 1 version of Telerik UI for WPF controls.

RadLayoutControl supports saving and loading the state of the layout. You can do this using the SaveToXmlString() and LoadFromXamlString() methods of RadLayoutControl. The control is serialized into an XML string and it is deserialized from one.

In order to serialize a layout you will need to set the RadLayoutControl.SerializationId attached property on the RadLayoutControl and all layout groups and UIElements that you want to save.

The SerializationIds must be unique. If there are elements with matching SerializationIds , this might lead to multiple operations performed on a single UI element resulting to an ArgumentException with the following error message: "Element is already the child of another element".

Example 1: Setting SerializationId in XAML

<telerik:RadLayoutControl telerik:RadLayoutControl.SerializationId="myLayoutControlID" />

If an element doesn't have SerializationId property set, it will not be saved in the serialized XML file. So, it will be removed from the layout when the XML file loads.

Saving the layout

The layout can be saved via the SaveToXmlString() method.

Example 2: Saving the layout

string serializationString = this.layoutControl.SaveToXmlString();

The groups that are generated automatically at runtime are also serialized, but their SerializationId is not set. If you want the serialization/deserialization to work properly you will need to manually set the SerializationId in the ElementSaving event of RadLayoutControl.

Example 3: Setting SerializationId in code

private void layoutControl_ElementSaving(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementSavingEventArgs e)
{
    string serializationId = RadLayoutControl.GetSerializationId(e.Element);
    if (String.IsNullOrEmpty(serializationId))
    {
        serializationId = Guid.NewGuid().ToString();
        RadLayoutControl.SetSerializationId(e.Element, serializationId);
    }
}

Loading the layout

The layout can be saved via the LoadFromXmlString() method.

Example 4: Loading the layout

this.layoutControl.LoadFromXmlString(serializationString);

List of default saved properties

The serialization process automatically saves the following common properties of RadLayoutControl, all UIElements and layout groups that participate in the layout.

  • Width
  • Height
  • MinWidth
  • MinHeight
  • HorizontalAlignment
  • VerticalAlignment
  • RadLayoutControl.SerializationId

The serialization saves the Orientation and IsAutoGenerated properties of RadLayoutControl and all layout groups. There are few additional properties specific for the different layout groups that are saved. You can find them in the following list.

  • RadLayoutControl
    • IsInEditMode
  • LayoutControlExpanderGroup
    • Header
    • IsExpanded
    • IsExpandable
  • LayoutControlTabGroupItem
    • Header
    • Content
    • IsSelected

The Header and Content properties are serialized if they contain an object of type FrameworkElement or a layout group. You can nest layout groups inside other layout groups placed in the Header or Content property and the control will successfully save/load the hierarchy. If the value of the Header/Content property is not FrameworkElement or a layout group, it will be saved as a string.

You can see how to save custom properties or replace the value of a serialized/deserialized property in the Save custom properties section of this article.

Events

RadLayoutControl exposes several events relevant to the serialization process. They are fired for each saved element from the layout.

  • ElementSaving: This event occurs when an element saving operation starts. It can be used to cancel the saving process. The event arguments are of type LayoutElementSavingEventArgs and expose the following properties:

    • Cancel: A bool property that gets or sets whether the serialization should be canceled.
    • Element: A property of type FrameworkElement that gets the element that is currently being saved.
    • Info: A property of type SerializationInfo that gets the information that is saved. At this point the serialization info is empty.
  • ElementSaved: This event occurs when the saving operation is complete and the element is saved. The event arguments are of type LayoutElementSerializationEventArgs and expose the following properties:

    • Element: A property of type FrameworkElement that gets the saved element.
    • Info: A property of type SerializationInfo that gets the information that is saved.
  • ElementLoading: This event occurs when an element loading operation starts. It can be used to cancel the loading process. The event arguments are of type LayoutElementLoadingEventArgs and expose the following properties:

    • Cancel: A bool property that gets or sets whether the deserialization should be canceled.
    • Element: A property of type FrameworkElement that gets the element that is currently being loaded.
    • Info: A property of type SerializationInfo that gets the information that is loaded.
  • ElementLoaded: This event occurs when the loading operation is complete and the element is loaded. The event arguments are of type LayoutElementSerializationEventArgs and expose the following properties:

    • Element: A property of type FrameworkElement that gets the loaded element.
    • Info: A property of type SerializationInfo that gets the information that is loaded.

Saving and loading custom properties

You can use the ElementSaving or the ElementSaved events to save a custom property. And then ElementLoading or ElementLoaded to load it.

Example 5: Saving custom property

private void layoutControl_ElementSaving(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementSavingEventArgs e)
{
    // save a custom property
    e.Info["Opacity"] = e.Element.Opacity;
}

private void layoutControl_ElementLoading(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementLoadingEventArgs e)
{
    // load and set the property
    var opacity = e.Info["Opacity"];
    e.Element.Opacity = double.Parse(opacity.ToString());
}


You can also use the serialization events to replace the value of any of the automatically saved/loaded properties.

Example 6: Replacing the value of a saved property

private void layoutControl_ElementSaved(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementSerializationEventArgs e)
{
    // replace the value of the VerticalAlignment property saved in the SerializationInfo object
    e.Info["VerticalAlignment"] = VerticalAlignment.Top;        
}

Note that you can use the Element property of the ElementLoading event arguments and replace it with another element. This could be useful in a scenario where the Element property is null.

Cancel saving and loading

You can use the ElementLoading and ElementSaving events to prevent the serialization/deserialization process.

Example 7: Cancel loading

private void layoutControl_ElementLoading(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementLoadingEventArgs e)
{   
    e.Cancel = true;
}

The elements in the RadLayoutControl are cleared before the ElementLoading event is invoked. If you cancel it the corresponding element (e.Element) won't be re-added in the visual tree.

Example 8: Cancel saving

private void layoutControl_ElementSaving(object sender, Telerik.Windows.Controls.LayoutControl.Serialization.LayoutElementSavingEventArgs e)
{
    e.Cancel = true;    
}


The serialization process saves only the state of element presented in the visual tree. If the deserialized element is removed from the tree, a new instance won't be created.

Generated XML string

This section demonstrate how the saved XML string is structured.

Saving the layout defined in Example 9 will generated the XML from Example 10. You can notice the LayoutControlGroup with x:Name="layoutControlGroup_3" was not serialized.

Example 9: LayoutControl defined in XAML

<telerik:RadLayoutControl x:Name="layoutControl" telerik:RadLayoutControl.SerializationId="myLayoutControlID">
    <Button Content="Button" telerik:RadLayoutControl.SerializationId="buttonID_1"/>
    <Border Background="Bisque" telerik:RadLayoutControl.SerializationId="buttonID_2"/>
    <telerik:LayoutControlGroup Orientation="Vertical" telerik:RadLayoutControl.SerializationId="layoutGroup_1">
        <TextBlock Text="TextBlock" Background="LightGray" TextAlignment="Center" VerticalAlignment="Center" telerik:RadLayoutControl.SerializationId="txtBlock_1" />
        <telerik:LayoutControlGroup Orientation="Vertical" VerticalAlignment="Center" Margin="2" telerik:RadLayoutControl.SerializationId="layoutGroup_2">
            <TextBlock Text="Text field:" Margin="5 0 5 0" telerik:RadLayoutControl.SerializationId="txtBlock_2" />
            <telerik:LayoutControlGroup Orientation="Vertical" VerticalAlignment="Center" Margin="2" >
                <TextBlock Text="Text field:" Margin="5 0 5 0"  />
            </telerik:LayoutControlGroup>
        </telerik:LayoutControlGroup>
    </telerik:LayoutControlGroup>
</telerik:RadLayoutControl>

Example 10: Generated XML string

<?xml version="1.0" encoding="utf-8"?>
<RadLayoutControl Type="Telerik.Windows.Controls.RadLayoutControl" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" SerializationId="myLayoutControlID" Orientation="Horizontal" IsAutoGenerated="false" IsInEditMode="false">
  <Items>
    <Button Type="System.Windows.Controls.Button" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" SerializationId="buttonID_1" />
    <Border Type="System.Windows.Controls.Border" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" SerializationId="buttonID_2" />
    <LayoutControlGroup Type="Telerik.Windows.Controls.LayoutControlGroup" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" SerializationId="layoutGroup_1" Orientation="Vertical" IsAutoGenerated="false">
      <Items>
        <TextBlock Type="System.Windows.Controls.TextBlock" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Center" SerializationId="txtBlock_1" />
        <LayoutControlGroup Type="Telerik.Windows.Controls.LayoutControlGroup" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Center" SerializationId="layoutGroup_2" Orientation="Vertical" IsAutoGenerated="false">
          <Items>
            <TextBlock Type="System.Windows.Controls.TextBlock" Width="NaN" Height="NaN" MinWidth="0" MinHeight="0" HorizontalAlignment="Stretch" VerticalAlignment="Stretch" SerializationId="txtBlock_2" />
          </Items>
        </LayoutControlGroup>
      </Items>
    </LayoutControlGroup>
  </Items>
</RadLayoutControl>

See Also

Was this article helpful? Yes No

Give article feedback

Tell us how we can improve this article

Dummy