dashboard-400729-winforms-dashboard-winforms-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 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 SetInitialDashboardState event applies a dashboard state when a dashboard is loading. Call the SetDashboardState method to apply a dashboard state at runtime.
View Example: How to Save and Restore the Dashboard State
The following code snippet shows how to create a dashboard state 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;
}
Public Function CreateDashboardState() As DashboardState
Dim state As New DashboardState()
' Set a range for a Range Filter.
state.Items.Add(New DashboardItemState("rangeFilterDashboardItem1") With {
.RangeFilterState = New RangeFilterState(
New RangeFilterSelection(New Date(2015, 1, 1), New Date(2017, 1, 1))
)})
' Specify master filter and drill-down values.
state.Items.Add(New DashboardItemState("gridDashboardItem1") With {
.MasterFilterValues = New List(Of Object())() From {
New Object() { "Gravad lax" },
New Object() { "Ikura" }
},
.DrillDownValues = New List(Of Object)() From {"Seafood"}
})
' Set a dashboard item layer.
state.Items.Add(New DashboardItemState("treemapDashboardItem1") With {.SelectedLayerIndex = 1})
' Specify a default tab page.
state.Items.Add(New DashboardItemState("tabContainerDashboardItem1") With {.TabPageName = "dashboardTabPage2"})
' Define a dashboard parameter value.
state.Parameters.Add(New DashboardParameterState() With {.Name = "ParameterCountry", .Value = "UK", .Type = GetType(String)})
Return state
End Function
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 CustomProperties collection.
The dashboard state is restored 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();
var stateValue = state.SaveToXml().ToString(SaveOptions.DisableFormatting);
dashboardViewer.Dashboard.CustomProperties.SetValue("DashboardState", stateValue);
}
private void DashboardViewer_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
e.InitialState = state;
}
// ...
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
' ...
Private state As New DashboardState()
Private Const path As String = "..\..\Dashboards\dashboard1.xml"
' ...
Private Sub DashboardViewer_DashboardStateChanged(ByVal sender As Object, ByVal e As DashboardStateChangedEventArgs)
state = dashboardViewer.GetDashboardState()
Dim stateValue = state.SaveToXml().ToString(SaveOptions.DisableFormatting)
dashboardViewer.Dashboard.CustomProperties.SetValue("DashboardState", stateValue)
End Sub
Private Sub DashboardViewer_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
e.InitialState = state
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.DashboardWin;
using DevExpress.XtraEditors;
using System;
using System.Collections.Generic;
namespace WinFormsDashboard_DashboardState
{
public partial class Form1 : XtraForm
{
public Form1() {
dashboardViewer1.ConfigureDataConnection += DashboardViewer1_ConfigureDataConnection;
dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
dashboardViewer1.UseNeutralFilterMode = true;
}
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 filter values if neutral filter mode is disabled:
//state.Items.Add(new DashboardItemState("listBoxDashboardItem1") {
// MasterFilterValues = null
//});
return state;
}
private void DashboardViewer1_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e){
DashboardToolbarItem resetStateItem = new DashboardToolbarItem("Reset State",
new Action<DashboardToolbarItemClickEventArgs>((args) => {
dashboardViewer1.SetDashboardState(CreateDashboardState());
}));
resetStateItem.Caption = "Reset Dashboard State";
e.Items.Add(resetStateItem);
}
//...
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.XtraEditors
Imports System
Imports System.Collections.Generic
Namespace WinFormsDashboard_DashboardState
Partial Public Class Form1
Inherits XtraForm
Public Sub New()
dashboardViewer1.ConfigureDataConnection += DashboardViewer1_ConfigureDataConnection
AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
dashboardViewer1.UseNeutralFilterMode = True
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
Private Sub DashboardViewer1_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
Dim resetStateItem As New DashboardToolbarItem("Reset State", New Action(Of DashboardToolbarItemClickEventArgs)(Function(args) AnonymousMethod1(args)))
resetStateItem.Caption = "Reset Dashboard State"
e.Items.Add(resetStateItem)
End Sub
Private Function AnonymousMethod1(ByVal args As Object) As Boolean
dashboardViewer1.SetDashboardState(CreateDashboardState())
Return True
End Function
'...
End Class
End Namespace
See Also
How to Set the Initial Dashboard State in the WinForms Viewer