Manage Dashboard State in the WPF Viewer 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 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.
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.
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");
}
//...
}
}
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.
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;
}
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.
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.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;
}
}
}