Manage Dashboard State

  • 6 minutes to read

A dashboard state describes the changes resulting from user interactions. The DashboardState class contains:

You can manage the following objects in a dashboard state:

Dashboard Item State Object Property
Selected master filter values for dashboard items. DashboardItemState.MasterFilterValues
Current drill-down values that indicate the drill-down level in dashboard items. DashboardItemState.DrillDownValues
Selected Range Filter/Date Filter intervals. DashboardItemState.RangeFilterState
Selected dashboard item layers for the following items:
Choropleth Map
A selected tab page. DashboardItemState.TabPageName
Dashboard parameter values. DashboardState.Parameters

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

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

The SetInitialDashboardState event applies a dashboard state when a dashboard is loading. Call the SetDashboardState method to apply a dashboard state at runtime.


How to Set the Initial Dashboard State

This example demonstrates how to manage the dashboard state to save and restore selected master filter values, current drill-down levels and other selections such as the selected Treemap layer.

When the main window closes, the GetDashboardState() method obtains a dashboard state object. It is serialized to XML and added to the XElement object stored in the Dashboard.CustomProperties collection. Subsequently, the dashboard with the dashboard state data is saved to a file.

When the application starts, the DashboardControl loads the dashboard and the DashboardState object is deserialized and restored using the GetDataFromString method in the in the SetInitialDashboardState event handler.

View Example: How to Set the Initial Dashboard State

using DevExpress.DashboardCommon;
using System;
using System.Windows;
using System.Xml.Linq;

namespace WpfDashboard_DashboardState
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
        public static readonly string PropertyName = "DashboardState";

        public MainWindow()


        DashboardState GetDataFromString(string customPropertyValue) {
            DashboardState dState = new DashboardState();
            if(!string.IsNullOrEmpty(customPropertyValue)) {
                var xmlStateEl = XDocument.Parse(customPropertyValue);
            return dState;

        private void dashboardControl_DashboardLoaded(object sender, DevExpress.DashboardWpf.DashboardLoadedEventArgs e) {

        private void dashboardControl_SetInitialDashboardState(object sender, DevExpress.DashboardWpf.SetInitialDashboardStateWpfEventArgs e)
            var state = GetDataFromString(dashboardControl.Dashboard.CustomProperties.GetValue(PropertyName));
            e.InitialState = state;
        private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e)
            var dState = dashboardControl.GetDashboardState();
            var stateValue = dState.SaveToXml().ToString(SaveOptions.DisableFormatting);
            dashboardControl.Dashboard.CustomProperties.SetValue("DashboardState", stateValue);


How to Use the DashboardStateChanged Event to Display User Interactions

This example demonstrates how to use the DashboardStateChanged event to display the result of user interactions. The DashboardState.Items property accesses the states of individual dashboard items. The TextEdit control displays the name of the Item and its filter values, current drill-down levels, and range-filter selections each time the dashboard state changes.

View Example: How to Use the DashboardStateChanged Event to Display User Interactions

using DevExpress.DashboardCommon;
using DevExpress.DashboardWpf;
using System;
using System.Linq;
using System.Windows;
// ...
 private void DashboardControl_DashboardStateChanged(object sender, DashboardStateChangedWpfEventArgs e) {
    var newState = e.DashboardState;
    var message = string.Empty;
    foreach(DashboardItemState itemState in newState.Items) {
        var item = dashboardControl1.Dashboard.Items[itemState.ItemName];
        message += item.Name;
        if( itemState.DrillDownValues.Count != 0) {
            message += "\n" + "Filter Drill-Down:" + " " + string.Join("," , itemState.DrillDownValues);
        if(itemState.MasterFilterValues.Count != 0) {
            message +=  "\n" + "Master Filter:" + " " + string.Join(" | ", itemState.MasterFilterValues.Select(v=> string.Join(",",v))); 
        if (itemState.RangeFilterState.Selection.Minimum !=null || itemState.RangeFilterState.Selection.Maximum != null) {
            message += "\n" + "Range Filter:" + " " + ((DateTime)itemState.RangeFilterState.Selection.Minimum).ToString("y") + "-" + ((DateTime)itemState.RangeFilterState.Selection.Maximum).ToString("y");
        message += Environment.NewLine;
        message += "\n";
          TextEdit.Text = message;  

How to Clear Selections in a Dashboard State

The following code snippet shows how to clear/select all filter values in a Dashboard state.

  • Neutral filter mode is enabled (UseNeutralFilterMode is true):

    Pass an empty MasterFilterValues object of a dashboard item to the entire dashboard state to clear filters (unselect all values).

  • Neutral filter mode is disabled (UseNeutralFilterMode is false):

    Assign null to the MasterFilterValues object of a filter element and pass it to the entire dashboard state to select all values.

    When neutral filter mode is disabled, there is a difference between null and empty master filter values:

    MasterFilterValues values Behavior
    MasterFilterValues = null The control filters data by all values (all values are selected).
    MasterFilterValues = [] The control excludes all filter (no data is selected).
using DevExpress.DashboardCommon;
using DevExpress.DashboardWpf;
using System.Windows;
namespace WpfDashboard_DashboardState {

    public partial class MainWindow : Window {

        public MainWindow() {


  private void DashboardControl_SetInitialDashboardState(object sender, SetInitialDashboardStateWpfEventArgs e) {
            var state = CreateDashboardState();
            e.InitialState = state;

    public DashboardState CreateDashboardState(){
            DashboardState state = new DashboardState();
            //Clears selections in the LisxBox item.
            state.Items.Add(new DashboardItemState("listBoxDashboardItem1") {
                MasterFilterValues = new List<object[]>()
            //The lines below clears all values if neutral filter mode is disabled:
            //state.Items.Add(new DashboardItemState("listBoxDashboardItem1") {
            //    MasterFilterValues = null
            return state;