Infragistics® WPF 2016.1
About Saving and Loading Layouts

Topic Overview

Purpose

This topic explains how to save the xamTileManager™’s layout and later restore it using the Infragistics® Control Persistence Framework. Saving the layout using the framework allows the user to not have to reconfigure the application layout for each session.

In this topic

This document contains the following sections:

Required background

The following table lists the prerequisites required for this topic:

Background type Content
Concepts

You need to be familiar with the following concepts:

Topics

You need to first read the following topics:

Control Configuration Overview

The xamTileManager allows users to fully configure the layout by enabling moving and resizing of tiles and the ability to change the state of tiles at run time. Users may expect you to save and load their custom layouts between sessions so they are not forced to reconfigure the xamTileManager every time the application restarts. Infragistics Control Persistence Framework allows you to save and load the tile layout for the xamTileManager.

In order to save a tile's state information in a layout, you must name the tile or set xamTileManager's attached property SerializationId to a unique string value. If you set both the Name and the SerializationId property, the SerializationId property takes precedence. The xamTileManager offers several different ways to set a tile's serialization ID.

If you name a tile or supply a serialization ID but you do not want to save the tile, you can set its SaveInLayout property to False.

Control configuration chart

The table below lists the methods you can use to save and load xamTileManager’s layout.

Feature Details Static Methods
Saving Layouts Use the Save static method to save the xamTileManager’s tiles layout PersistenceManager.Save
Loading Layouts Use the Load static method to restore the xamTileManager’s tiles layout PersistenceManager.Load

Saving Layouts

Saving layouts details

In order to save the xamTileManager state and tile’s layout, you must invoke the static Save method of the PersistenceManager class. There is an overload of the Save method, which accepts a PersistenceSettings argument, which is used to configure what properties to save or exclude. The persistence methods return a MemoryStream object which you can then save to a persistent location.

Note: Depending on your application architecture you may choose different approaches on how to persist the MemoryStream (like XML file or database). Refer to the “Saving and Loading Layouts” sample to see how the layout is persisted in a byte array.

Saving layouts method settings

The Save methods are accessed through the PersistenceManager class.

In order to… Use this method: And set the following arguments…
Save layout with all properties PersistenceManager.Save object
Save layout and configure which properties are saved or ignored PersistenceManager.Save object, settings

Saving layout with all properties

The Saving Layout example demonstrates how to persist all control’s properties.

Arguments Types
object The DependencyObject, whose properties will be saved

Saving layout and configure which properties should be saved or ignored

The Including and Excluding Layout Properties During Save example demonstrates how to configure the persistence framework to ignore some properties when saving the state of a control.

Arguments Types
object The DependencyObject, whose properties will be saved
settings A PersistenceSettings object, which is describing the properties, which should be saved or ignored

Loading Layouts

Loading layouts details

In order to load the xamTileManager state and tile’s layout, you must invoke the static Load method of the PersistenceManager class. Additionally, there is an overload of the Load method that accepts an instance of the PersistenceSettings class as an argument. The PersistenceSettings instance is used to configure what properties to save or ignore in the layout. The data returned from the Save methods is supplied to the Load methods (as Stream objects) to restore the control’s state.

Loading layouts method settings

The Load methods are accessed through the PersistenceManager class.

In order to… Use this method: And set the following arguments…
Load layout with all properties PersistenceManager.Load object

Loading layout with all properties

The Loading Layout example demonstrates how to load all persisted control’s properties.

Arguments Types
object The DependencyObject, whose properties will be restored

Code Examples

Examples overview

The following table lists the code examples provided below.

Example Description

Saving layout

Shows how to save all properties of the specified control.

Including and excluding layout properties during save

Shows how to save control state and specify which properties should be ignored.

Loading layout

Shows how to restore all saved properties of the specified control.

Code Example: Saving Layout

Example description

The code below demonstrates how to Save control’s state using the Save method with the following parameters:

In Visual Basic:

Dim memoryStream As MemoryStream =
    PersistenceManager.Save(xamTileManager1)

In C#:

MemoryStream memoryStream =
    PersistenceManager.Save(xamTileManager1);

Code Example: Including and Excluding Layout Properties During Save

Example description

The code below demonstrates how to Save control’s state using the Save method with the following parameters:

In Visual Basic:

' create the Persistence Settings object
Dim settings As New PersistenceSettings()
' save all properties except those ignored
settings.SavePersistenceOptions =
    Persistence.Primitives.PersistenceOption.AllButIgnored
' add the "Left" property as ignored
Dim prop1 As New PropertyNamePersistenceInfo() With { _
    .PropertyName = "Left" _
}
settings.IgnorePropertySettings.Add(prop1)
' add the "Top" property as ignored
Dim prop2 As New PropertyNamePersistenceInfo() With { _
    .PropertyName = "Top" _
}
settings.IgnorePropertySettings.Add(prop2)
' save the control's properties in a memory stream
Dim memoryStream As MemoryStream =
    PersistenceManager.Save(xamTileManager1, settings)

In C#:

// create the Persistence Settings object
PersistenceSettings settings = new PersistenceSettings();
// save all properties except those ignored
settings.SavePersistenceOptions =
    Persistence.Primitives.PersistenceOption.AllButIgnored;
// add the "Left" property as ignored
PropertyNamePersistenceInfo prop1 = new PropertyNamePersistenceInfo
{
    PropertyName = "Left"
};
settings.IgnorePropertySettings.Add(prop1);
// add the "Top" property as ignored
PropertyNamePersistenceInfo prop2 = new PropertyNamePersistenceInfo
{
    PropertyName = "Top"
};
settings.IgnorePropertySettings.Add(prop2);
// save the control's properties in a memory stream
MemoryStream memoryStream =
    PersistenceManager.Save(xamTileManager1, settings);

Code Example: Loading Layout

Example description

The code below demonstrates how to load control’s state using the Load method with the following parameters:

In Visual Basic:

PersistenceManager.Load(xamTileManager1, memoryStream)

In C#:

PersistenceManager.Load(xamTileManager1, memoryStream);

Related Topics

Following are some other topics you may find useful.

About Tile Layout

Add Tiles to xamTileManager

Retrieve a Reference to a Tile

Change the State of a Tile

About Tile Templates

Binding xamTileManager to Data

Explicitly Arrange Tiles

Allow End Users to Close Tiles

Restrict a XamTile's Size

Modify Tile Behaviors in Normal Mode

Modify Tile Behaviors in Maximized Mode

About Animations

 

 


Copyright © 2008-2016 Infragistics, Inc. All rights reserved.

E-mail your feedback on this topic.