Manage Dashboard State in the WinForms Designer Control
- 6 minutes to read
A dashboard state describes the changes resulting from user interactions. The DashboardState class contains:
- dashboard parameter values (the DashboardState.Parameters property)
- states of individual dashboard items (the DashboardState.Items property).
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 DashboardDesigner provides the following API to manage the dashboard state:
| Member | Description |
|---|---|
| DashboardDesigner.GetDashboardState | Gets the current dashboard state. |
| DashboardDesigner.SetDashboardState | Applies the dashboard state to the loaded dashboard. |
| DashboardDesigner.SetInitialDashboardState | Allows you to specify the initial dashboard state when loading a dashboard. |
| DashboardDesigner.DashboardStateChanged | Occurs after the current dashboard state in the DashboardDesigner 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 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;
}
How to Use the DashboardStateChanged Event to Manage the Dashboard State
The following code snippet demonstrates how to save a dashboard state each time it is changed.
The DashboardDesigner.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 DashboardDesigner.SetInitialDashboardState event handler.
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
// ...
DashboardState state = new DashboardState();
const string path = @"..\..\Dashboards\dashboard1.xml";
// ...
private void DashboardDesigner_DashboardStateChanged(object sender, DashboardStateChangedEventArgs e) {
state = dashboardDesigner.GetDashboardState();
var stateValue = state.SaveToXml().ToString(SaveOptions.DisableFormatting);
dashboardDesigner.Dashboard.CustomProperties.SetValue("DashboardState", stateValue);
}
private void DashboardDesigner_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
e.InitialState = state;
}
// ...
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.
The DashboardDesigner.SetDashboardState method applies the created dashboard state at runtime.
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.DashboardWin;
using System;
using System.Collections.Generic;
using System.Xml.Linq;
namespace WinDesignerDashboardState
{
public partial class DesignerForm1: DevExpress.XtraBars.Ribbon.RibbonForm {
const string path = @"..\..\Dashboards\dashboardWithSavedState.xml";
public DesignerForm1() {
InitializeComponent();
dashboardDesigner.CreateRibbon();
dashboardDesigner.UseNeutralFilterMode = true;
dashboardDesigner.LoadDashboard(path);
}
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 dashboardDesigner_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
DashboardToolbarItem resetStateItem = new DashboardToolbarItem("Reset State",
new Action<DashboardToolbarItemClickEventArgs>((args) => {
dashboardDesigner.SetDashboardState(CreateDashboardState());
}));
resetStateItem.Caption = "Reset Dashboard State";
e.Items.Add(resetStateItem);
}
}
}