Back to Devexpress

Manage Dashboard State in the WPF Viewer Control

dashboard-400144-wpf-viewer-manage-dashboard-state.md

latest14.8 KB
Original Source

Manage Dashboard State in the WPF Viewer Control

  • Sep 10, 2021
  • 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 ObjectProperty
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:
Card
Choropleth Map
Gauges
Pie
Treemap
DashboardItemState.SelectedLayerIndex
A selected tab page.DashboardItemState.TabPageName
Dashboard parameter values.DashboardState.Parameters

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

MemberDescription
GetDashboardState()Gets the current dashboard state.
SetDashboardState(DashboardState)Applies the dashboard state to the loaded dashboard.
SetInitialDashboardStateAllows you to specify the initial dashboard state when loading a dashboard.
DashboardStateChangedOccurs 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.

Examples

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

csharp
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()
        {
            InitializeComponent();

        }

        DashboardState GetDataFromString(string customPropertyValue) {
            DashboardState dState = new DashboardState();
            if(!string.IsNullOrEmpty(customPropertyValue)) {
                var xmlStateEl = XDocument.Parse(customPropertyValue);
                dState.LoadFromXml(xmlStateEl);
            }
            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);
            dashboardControl.Dashboard.SaveToXml("SampleDashboardWithState.xml");
        }

       //...
    }
}
vb
Imports DevExpress.DashboardCommon
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
        Public Shared ReadOnly PropertyName As String = "DashboardState"

        Public Sub New()
            InitializeComponent()

        End Sub

        Private Function GetDataFromString(ByVal customPropertyValue As String) As DashboardState
            Dim dState As New DashboardState()
            If (Not String.IsNullOrEmpty(customPropertyValue)) Then
                Dim xmlStateEl = XDocument.Parse(customPropertyValue)
                dState.LoadFromXml(xmlStateEl)
            End If
            Return dState
        End Function

        Private Sub dashboardControl_DashboardLoaded(ByVal sender As Object, ByVal e As DevExpress.DashboardWpf.DashboardLoadedEventArgs)

        End Sub
        Private Sub dashboardControl_SetInitialDashboardState(ByVal sender As Object, ByVal e As DevExpress.DashboardWpf.SetInitialDashboardStateWpfEventArgs)
            Dim state = GetDataFromString(dashboardControl.Dashboard.CustomProperties.GetValue(PropertyName))
            e.InitialState = state
        End Sub
        Private Sub Window_Closing(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
            Dim dState = dashboardControl.GetDashboardState()
            Dim stateValue = dState.SaveToXml().ToString(SaveOptions.DisableFormatting)
            dashboardControl.Dashboard.CustomProperties.SetValue("DashboardState", stateValue)
            dashboardControl.Dashboard.SaveToXml("SampleDashboardWithState.xml")
        End Sub

       '...
    End Class
End Namespace

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

csharp
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;  
}
vb
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWpf
Imports System
Imports System.Linq
Imports System.Windows
' ...
 Private Sub DashboardControl_DashboardStateChanged(ByVal sender As Object, ByVal e As DashboardStateChangedWpfEventArgs)
    Dim newState = e.DashboardState
    Dim message = String.Empty
    For Each itemState As DashboardItemState In newState.Items
        Dim item = dashboardControl1.Dashboard.Items(itemState.ItemName)
        message += item.Name
        If itemState.DrillDownValues.Count <> 0 Then
            message += Constants.vbLf & "Filter Drill-Down:" & " " & String.Join(",", itemState.DrillDownValues)
        End If
        If itemState.MasterFilterValues.Count <> 0 Then
            message += Constants.vbLf & "Master Filter:" & " " & String.Join(" | ", itemState.MasterFilterValues.Select(Function(v) String.Join(",",v)))
        End If
        If itemState.RangeFilterState.Selection.Minimum IsNot Nothing OrElse itemState.RangeFilterState.Selection.Maximum IsNot Nothing Then
            message += Constants.vbLf & "Range Filter:" & " " & (CDate(itemState.RangeFilterState.Selection.Minimum)).ToString("y") & "-" & (CDate(itemState.RangeFilterState.Selection.Maximum)).ToString("y")
        End If
        message += Environment.NewLine
        message += Constants.vbLf
    Next itemState
          TextEdit.Text = message
 End Sub

How to Clear Selections in a Dashboard State

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

csharp
using DevExpress.DashboardCommon;
using DevExpress.DashboardWpf;
using System.Windows;
namespace WpfDashboard_DashboardState {

    public partial class MainWindow : Window {

        public MainWindow() {
            InitializeComponent();

        }

  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;
        }
    }
}
vb
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWpf
Imports System.Windows
Namespace WpfDashboard_DashboardState

    Partial Public Class MainWindow
        Inherits Window

        Public Sub New()
            InitializeComponent()

        End Sub

  Private Sub DashboardControl_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateWpfEventArgs)
            Dim state = CreateDashboardState()
            e.InitialState = state
  End Sub

    Public Function CreateDashboardState() As DashboardState
            Dim state As New DashboardState()
            'Clears selections in the LisxBox item.
            state.Items.Add(New DashboardItemState("listBoxDashboardItem1") With {.MasterFilterValues = New List(Of Object())()})
            'The lines below clears all values if neutral filter mode is disabled:
            'state.Items.Add(new DashboardItemState("listBoxDashboardItem1") {
            ' MasterFilterValues = null
            '});
            Return state
    End Function
    End Class
End Namespace