dashboard-400144-wpf-viewer-manage-dashboard-state.md
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: | |
| 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:
| 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.
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()
{
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");
}
//...
}
}
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
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;
}
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
The following code snippet shows how to clear/select all filter values in a Dashboard state.
Neutral filter mode is enabled ( UseNeutralFilterMode is true ):
Neutral filter mode is disabled ( UseNeutralFilterMode is false ):
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;
}
}
}
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