Manage Dashboard State

• Dec 24, 2019
• 3 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	API
Selected master filter values for dashboard items.	DashboardItemState.MasterFilterValues
Current drill-down levels for dashboard items.	DashboardItemState.DrillDownValues
Selected Range Filter interval.	DashboardItemState.RangeFilterState
Selected dashboard item layers for the following items: Card Choropleth Map Gauges Pie Treemap	DashboardItemState.SelectedLayerIndex
A selected tab page.	DashboardItemState.TabPageName
Dashboard parameter values.	DashboardState.Parameters

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

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.

Example

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.UserData property. 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 in the DashboardLoaded event handler.

The dashboard state is restored using the SetDashboardState(DashboardState) in the SetInitialDashboardState event handler.

Note

The complete sample project How to Set the Initial Dashboard State is available in the DevExpress Examples repository.

C#

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

namespace WpfDashboard_DashboardState {
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window {
        DashboardState dState = new DashboardState(); 
        public MainWindow() {
            InitializeComponent();
        }
        private void dashboardControl_DashboardLoaded(object sender, DashboardLoadedEventArgs e) {
            XElement data = e.Dashboard.UserData;
            if (data != null) {
                if (data.Element("DashboardState") != null) {
                    XDocument dStateDocument = XDocument.Parse(data.Element("DashboardState").Value);
                    dState.LoadFromXml(XDocument.Parse(data.Element("DashboardState").Value));
                }
            }
        }
        private void dashboardControl_SetInitialDashboardState(object sender, SetInitialDashboardStateWpfEventArgs e) {
            e.InitialState = dState;
        }
        private void Window_Closing(object sender, System.ComponentModel.CancelEventArgs e) {
            dState = dashboardControl.GetDashboardState();
            XElement userData = new XElement("Root", 
                new XElement("DateModified", DateTime.Now), 
                new XElement("DashboardState", dState.SaveToXml().ToString(SaveOptions.DisableFormatting)));
            dashboardControl.Dashboard.UserData = userData;
            dashboardControl.Dashboard.SaveToXml("SampleDashboardWithState.xml");
        }
    }
}

VB.NET

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWpf
Imports System
Imports System.Windows
Imports System.Xml.Linq

Namespace WpfDashboard_DashboardState
    ''' <summary>
    ''' Interaction logic for MainWindow.xaml
    ''' </summary>
    Partial Public Class MainWindow
        Inherits Window

        Private dState As New DashboardState()
        Public Sub New()
            InitializeComponent()
        End Sub
        Private Sub dashboardControl_DashboardLoaded(ByVal sender As Object, ByVal e As DashboardLoadedEventArgs)
            Dim data As XElement = e.Dashboard.UserData
            If data IsNot Nothing Then
                If data.Element("DashboardState") IsNot Nothing Then
                    Dim dStateDocument As XDocument = XDocument.Parse(data.Element("DashboardState").Value)
                    dState.LoadFromXml(XDocument.Parse(data.Element("DashboardState").Value))
                End If
            End If
        End Sub
        Private Sub dashboardControl_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateWpfEventArgs)
            e.InitialState = dState
        End Sub
        Private Sub Window_Closing(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
            dState = dashboardControl.GetDashboardState()
            Dim userData As New XElement("Root", _
             New XElement("DateModified", Date.Now), _
             New XElement("DashboardState", dState.SaveToXml().ToString(SaveOptions.DisableFormatting)))
            dashboardControl.Dashboard.UserData = userData
            dashboardControl.Dashboard.SaveToXml("SampleDashboardWithState.xml")
        End Sub
    End Class
End Namespace