Back to Devexpress

Manage Dashboard State in the WinForms Designer Control

dashboard-400730-winforms-dashboard-winforms-designer-manage-dashboard-state.md

latest13.4 KB
Original Source

Manage Dashboard State in the WinForms Designer Control

  • Oct 04, 2023
  • 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 DashboardDesigner provides the following API to manage the dashboard state:

MemberDescription
DashboardDesigner.GetDashboardStateGets the current dashboard state.
DashboardDesigner.SetDashboardStateApplies the dashboard state to the loaded dashboard.
DashboardDesigner.SetInitialDashboardStateAllows you to specify the initial dashboard state when loading a dashboard.
DashboardDesigner.DashboardStateChangedOccurs 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

View Example: How to Save and Restore the Dashboard State

The following code snippet shows how to create a dashboard state in code:

csharp
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;
}
vb
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

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.

csharp
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;
}
// ...
vb
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
' ...
Private state As New DashboardState()
Private Const path As String = "..\..\Dashboards\dashboard1.xml"
' ...
Private Sub DashboardDesigner_DashboardStateChanged(ByVal sender As Object, ByVal e As DashboardStateChangedEventArgs)
  state = dashboardDesigner.GetDashboardState()
  Dim stateValue = state.SaveToXml().ToString(SaveOptions.DisableFormatting)
  dashboardDesigner.Dashboard.CustomProperties.SetValue("DashboardState", stateValue)
End Sub

Private Sub DashboardDesigner_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
  e.InitialState = state
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.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);
        }
    }
}
vb
Imports Microsoft.VisualBasic
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports System
Imports System.Collections.Generic
Imports System.Xml.Linq

Namespace WinDesignerDashboardState
    Partial Public Class DesignerForm1
        Inherits DevExpress.XtraBars.Ribbon.RibbonForm
        Private Const path As String = "..\..\Dashboards\dashboardWithSavedState.xml"
        Public Sub New()
            InitializeComponent()
            dashboardDesigner.CreateRibbon()
            dashboardDesigner.UseNeutralFilterMode = True
            dashboardDesigner.LoadDashboard(path)
        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 dashboardDesigner_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As DevExpress.DashboardWin.CustomizeDashboardTitleEventArgs) Handles dashboardDesigner.CustomizeDashboardTitle
            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
            dashboardDesigner.SetDashboardState(CreateDashboardState())
            Return True
        End Function
    End Class
End Namespace

See Also

How to Set the Initial Dashboard State in the WinForms Designer