Persisting Settings

Glossary Item Box

The settings of a grid and its elements can be persisted and re-applied using the SaveUserSettings and LoadUserSettings methods, respectively. By default, column widths, visibilities, positions, and fixed-column counts as well as grouping and sorting criteria are persisted; however, these settings can be modified when calling the SaveUserSettings and LoadUserSettings methods (see Table 1).

ShowTable 1: Persisted setting values

Value

Description

None

No settings are persisted.

ColumnWidths

Column widths are persisted.

ColumnPositions

Column positions are persisted.

ColumnVisibilities

Column visibilities are persisted.

FixedColumnCounts

Fixed-column counts are persisted.

Sorting

Sorting criteria are persisted.

Grouping

Grouping criteria are persisted.

CardsWidths

Card widths are persisted.

All

Column widths, visibilities, positions, and fixed-column counts as well as grouping and sorting criteria are persisted.

The SettingsRepository class represents the repository to which the settings of a grid and its elements are persisted when the SaveUserSettings method is called. This repository can then be serialized using an XmlSerializer (see Example 1) or persisted to the application settings (see Application Settings). When re-applying settings to a grid, a repository that contains the settings must be provided to the LoadUserSettings method.

Application Settings

Application settings provide a built-in way to store and load settings. In order to persist the settings of a grid and its elements in the application settings, a SettingsRespository must first be added to the Settings of the application:

  1. In the Solution Explorer, right-click on the project and select Properties from the menu.
  2. Click on the Settings tab to open the application settings.
  3. Provide a new Xceed.Wpf.DataGrid.Settings.SettingsRespository type to which the settings will be persisted to and read from (see Figure 1).  


Figure 1: Configuring application settings

Once the repository is added to the application settings, it must be loaded and saved in order to persist the settings it contains. This is usually done by calling the Reload method in the application's OnStartup override and Save method in the OnExit override (see Example 2).

Examples 

All examples in this topic assume that the grid is bound to the Orders table of the Northwind database, unless stated otherwise.

ShowExample 1: Persisting and loading settings using an XmlSerializer

The following example demonstrates how to persist and load settings using an XML serializer.

XAML Copy Code
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid">
  <Grid.Resources>
     <xcdg:DataGridCollectionViewSource x:Key="cvs_orders"
                                        Source="{Binding Source={x:Static Application.Current}, Path=Orders}" />
  </Grid.Resources>
  <DockPanel>
     <StackPanel Orientation="Horizontal"
                 DockPanel.Dock="Top">
        <Button Content="Save Settings"
                Click="SaveSettings" />
        <Button Content="Load Settings"
                Click="LoadSettings" />
     </StackPanel>
     <xcdg:DataGridControl x:Name="OrdersGrid"
        ItemsSource="{Binding Source={StaticResource cvs_orders}}">
     </xcdg:DataGridControl>
  </DockPanel>
</Grid>

The following code provides the implementation required to persist and load settings using the XmlSerializer class. 

VB.NET Copy Code
Private Sub SaveSettings( ByVal sender As Object, ByVal e As RoutedEventArgs )
  Dim settings As New SettingsRepository()
  Me.OrdersGrid.SaveUserSettings( settings, UserSettings.All )
  Dim serializer As New XmlSerializer( GetType( SettingsRepository ) )
  Using stream As New FileStream( "d:\settings.xml", FileMode.CreateNew )
    serializer.Serialize( stream, settings )
  End Using
End Sub
Private Sub LoadSettings( ByVal sender As Object, ByVal e As RoutedEventArgs )
  Dim settings As SettingsRespository
  Using stream As New FileStream( "d:\settings.xml", FileMode.Open )
    Dim serializer As New XmlSerializer( GetType( SettingsRepository ) )
    settings = TryCast( serializer.Deserialize( stream ), SettingsRepository )
  End Using
  Me.OrdersGrid.LoadUserSettings( settings, UserSettings.All )
End Sub
C# Copy Code
private void SaveSettings( object sender, RoutedEventArgs e )
{
 SettingsRepository settings = new SettingsRepository();   
 this.OrdersGrid.SaveUserSettings( settings, UserSettings.All );
 XmlSerializer serializer = new XmlSerializer( typeof( SettingsRepository ) );
 using( FileStream stream = new FileStream( "d:\\settings.xml", FileMode.CreateNew ) )
 {
   serializer.Serialize( stream, settings );
 }
}
private void LoadSettings( object sender, RoutedEventArgs e )
{
 SettingsRepository settings;
 using( FileStream stream = new FileStream( "d:\\settings.xml", FileMode.Open ) )
 {
   XmlSerializer serializer = new XmlSerializer( typeof( SettingsRepository ) );
   settings = serializer.Deserialize( stream ) as SettingsRepository;
 }
 this.OrdersGrid.LoadUserSettings( settings, UserSettings.All );
}

ShowExample 2: Persisting and loading settings through the application settings

The following example demonstrates how to persist and load settings using the application settings. 

XAML Copy Code
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid">
  <Grid.Resources>
     <xcdg:DataGridCollectionViewSource x:Key="cvs_orders"
                                        Source="{Binding Source={x:Static Application.Current}, Path=Orders}" />
  </Grid.Resources>
  <DockPanel>
     <StackPanel Orientation="Horizontal"
                 DockPanel.Dock="Top">
        <Button Content="Save Settings"
                Click="SaveSettings" />
        <Button Content="Load Settings"
                Click="LoadSettings" />
     </StackPanel>
     <xcdg:DataGridControl x:Name="OrdersGrid"
        ItemsSource="{Binding Source={StaticResource cvs_orders}}">
     </xcdg:DataGridControl>
  </DockPanel>
</Grid>

The following code provides the implementation required to persist and load settings using the application settings.

VB.NET Copy Code
Private Sub SaveSettings( ByVal sender As Object, ByVal e As RoutedEventArgs )
  If Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings Is Nothing Then
    Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings = New SettingsRepository()
  End If
  Me.OrdersGrid.SaveUserSettings( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings, UserSettings.All )
End Sub
Private Sub LoadSettings( ByVal sender As Object, ByVal e As RoutedEventArgs )
  If Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings Is Nothing Then
    Return
  End If
  Me.OrdersGrid.LoadUserSettings( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings, UserSettings.All )
End Sub
C# Copy Code
private void SaveSettings( object sender, RoutedEventArgs e )
{
 if( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings == null )
 {
   Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings = new SettingsRepository();
 }
 this.OrdersGrid.SaveUserSettings( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings, UserSettings.All );
}
private void LoadSettings( object sender, RoutedEventArgs e )
{
 if( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings == null )
   return;
 this.OrdersGrid.LoadUserSettings( Xceed.Wpf.Documentation.Properties.Settings.Default.GridSettings, UserSettings.All );
}

In addition to persisting and load the grid-specific settings to and from the resources, the application settings themselves must also be persisted using the default setting's Reload and Save methods, which are usually called in the application's OnStartup and OnExit overrides, respectively.

VB.NET Copy Code
Protected Overrides Sub OnStartup( ByVal e As StartupEventArgs )
  Xceed.Wpf.DataGrid.Licenser.LicenseKey = "license_key"
  MyBase.OnStartup( e )
  Settings.Default.Reload()
End Sub
Protected Override Sub OnExit( ByVal e As ExitEventArgs )
  Settings.Default.Save()
  MyBase.OnExit( e )
End Sub
C# Copy Code
protected override void OnStartup( StartupEventArgs e )
{
  Xceed.Wpf.DataGrid.Licenser.LicenseKey = "license_key";
  base.OnStartup( e );  
  Settings.Default.Reload();
}
protected override void OnExit( ExitEventArgs e )
{  
  Settings.Default.Save();
  base.OnExit( e );
}