Layout Options (Grid, Pivot Grid, TreeList, Vertical Grid)

• Sep 10, 2023
• 3 minutes to read

Grid Control and XtraPivotGrid allow you to control how their layouts are stored to and restored from data stores. This document describes methods that implement this functionality.

Layout Options

WinForms Data Grid, Pivot Grid, TreeList, and Vertical Grid controls provide methods to save control layout to and then restore it from a data store (an XML file, a stream or the system registry). All these methods start with either SaveLayoutTo... or RestoreLayoutFrom.... For instance, the BaseView.SaveLayoutToXml and BaseView.RestoreLayoutFromXml methods can be used to save/restore a Grid Control’s View using an XML file. The complete list of methods can be found in the following topics.

• Data Grid: Member Table – Save and Restore Layout
• Pivot Grid: Member Table – Save and Restore Layout
• TreeList: Member Table – Save and Restore Layout

The SaveLayoutTo... and RestoreLayoutFrom... methods have two overloads (with and without the options parameter of the OptionsLayoutBase type). For instance, the overloads of the BaseView.SaveLayoutToXml and BaseView.RestoreLayoutFromXml methods are declared as follows.

C#

public void SaveLayoutToXml(string xmlFile)
public void SaveLayoutToXml(string xmlFile, OptionsLayoutBase options)

public void RestoreLayoutFromXml(string xmlFile)
public void RestoreLayoutFromXml(string xmlFile, OptionsLayoutBase options)

When calling the SaveLayoutTo... or RestoreLayoutFrom... method without the options parameter, only a subset of the control’s settings is saved/restored. By default, these settings include:

• visibility state, position and size of the columns/bands/fields;
• sorting and grouping settings;
• current and most recently used (MRU) filters;
• summary information;
• all settings grouped within the control’s OptionsView object (for instance, ColumnView.OptionsView)

Options such as appearance, data binding, behavior, customization and selection are not saved/restored by default.

To manually specify which options need to be saved/restored, use the control’s OptionsLayout property (BaseView.OptionsLayout for Grid Control Views and PivotGridControl.OptionsLayout for XtraPivotGrid). The options provided by the OptionsLayout object are listed below.

Option	Default Value	Description
OptionsLayoutGrid.StoreVisualOptions	True	View options - ColumnView.OptionsView and PivotGridControl.OptionsView for Grid Control and XtraPivotGrid respectively.
OptionsLayoutGrid.StoreDataSettings	True	Grouping, sorting, filtering and summary settings.
OptionsLayoutGrid.StoreAppearance	False	Appearance settings.
OptionsLayoutGrid.StoreAllOptions	False	All options except for appearance settings and style conditions. These options include view settings, data binding, behavior options, end-user customization options, and selection settings.
OptionsColumnLayout.AddNewColumns	True	Specifies whether or not columns/bands/fields that exist in the current control’s layout, but not in the layout being loaded, should be retained. If this option is disabled, these columns/bands/fields will be discarded.
OptionsColumnLayout.RemoveOldColumns	True	Specifies whether or not columns/bands/fields that exist in the layout being loaded, but not in the current control’s layout, should be discarded. If this option is disabled, these columns/bands/fields will be added to the current control.
OptionsColumnLayout.StoreLayout	True	Position, width and visibility of columns/bands/fields.
OptionsColumnLayout.StoreAppearance	False	Appearance settings of columns and bands.
OptionsColumnLayout.StoreAllOptions	False	All band/column/field options.
PivotGridOptionsLayout.StoreLayoutOptions	False	Options specifying how a pivot grid layout is stored to or restored from a storage (for the XtraPivotGrid only).

You can also use the SaveLayoutTo... and RestoreLayoutFrom... methods with the options parameter. Create an instance of the OptionsLayoutGrid or PivotGridOptionsLayout class, customize it, and pass it as a parameter. Only the options that are enabled in this object will be saved/restored. Specific options that have been disabled in the options parameter are not affected.

To save all options, pass null (Nothing in Visual Basic) or a static OptionsLayoutBase.FullLayout property as the options parameter.