Manage Dashboard State

  • 4 minutes to read

A dashboard state describes the changes resulting from end-user interaction. The dashboard state is the DashboardState class instance and can contain the following objects:

Dashboard State Object


Selected master filter values for dashboard items.


Current drill-down levels for dashboard items.


Selected Range Filter interval.


Selected dashboard item layers for the following items:


A selected tab page.


Dashboard parameter values.


Use the DashboardState.Items property to get access to the dashboard item state collection.

The DashboardViewer provides the following API to manage the dashboard state:

Member Description
DashboardViewer.GetDashboardState Gets the current dashboard state.
DashboardViewer.SetDashboardState Applies the dashboard state to the loaded dashboard.
DashboardViewer.SetInitialDashboardState Allows you to specify the initial dashboard state when loading a dashboard.
DashboardViewer.DashboardStateChanged Occurs after the current dashboard state in the DashboardViewer is changed.



The complete sample project is available on GitHub: How to Save and Restore the Dashboard State

The following code snippet shows how to create a dashboard state for in code:

public DashboardState CreateDashboardState()
    DashboardState state = new DashboardState();
    // Set a range for a Range Filter.
    state.Items.Add(new DashboardItemState("rangeFilterDashboardItem1")
        RangeFilterState = new RangeFilterState(
            new RangeFilterSelection(
                new DateTime(2015, 1, 1), new DateTime(2017, 1, 1)))
    // Specify master filter and drill-down values.
    state.Items.Add(new DashboardItemState("gridDashboardItem1")
        MasterFilterValues = new List<object[]>() { 
            new object[] { "Gravad lax" }, 
            new object[] { "Ikura" } },
        DrillDownValues = new List<object>() { "Seafood" }
    // Set a dashboard item layer.
    state.Items.Add(new DashboardItemState("treemapDashboardItem1")
        SelectedLayerIndex = 1
    // Specify a default tab page.
    state.Items.Add(new DashboardItemState("tabContainerDashboardItem1")
        TabPageName = "dashboardTabPage2"
    // Define a dashboard parameter value.
    state.Parameters.Add(new DashboardParameterState()
        Name = "ParameterCountry",
        Value = "UK",
        Type = typeof(string)
    return state;

The complete sample project is available on GitHub: How to Use the DashboardStateChanged Event to Manage the Dashboard State

The following code snippet demonstrates how to save a dashboard state each time it is changed.

The DashboardViewer.GetDashboardState method obtains a dashboard's state object in the DashboardStateChanged event that is handled each time the dashboard state is changed. The state is serialized to XML and added to the XElement object stored in the Dashboard.UserData.

The DashboardViewer.SetDashboardState method restores the dashboard's state in the DashboardViewer.SetInitialDashboardState event handler.

using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
// ...
DashboardState state = new DashboardState();
const string path = @"..\..\Dashboards\dashboard1.xml";
// ... 
private void DashboardViewer_DashboardStateChanged(object sender, DashboardStateChangedEventArgs e) {
  state = dashboardViewer.GetDashboardState();

private void DashboardViewer_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
  e.InitialState = state;
// ...  
See Also