Back to Devexpress

DashboardViewer.DashboardItemClick Event

dashboard-devexpress-dot-dashboardwin-dot-dashboardviewer-8e14fe89.md

latest21.2 KB
Original Source

DashboardViewer.DashboardItemClick Event

Occurs when an end user clicks a dashboard item.

Namespace : DevExpress.DashboardWin

Assembly : DevExpress.Dashboard.v25.2.Win.dll

NuGet Package : DevExpress.Win.Dashboard

Declaration

csharp
public event DashboardItemMouseActionEventHandler DashboardItemClick
vb
Public Event DashboardItemClick As DashboardItemMouseActionEventHandler

Event Data

The DashboardItemClick event's data class is DashboardItemMouseActionEventArgs. The following properties provide information specific to this event:

PropertyDescription
DashboardItemNameGets the name of the dashboard item for which the event has been raised. Inherited from DashboardItemMouseEventArgs.
DataGets the dashboard item’s client data. Inherited from DashboardItemMouseHitTestEventArgs.

The event data class exposes the following methods:

MethodDescription
GetAxisPoint()Returns the axis point corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetAxisPoint(String)Returns the axis point corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetDeltas()Gets a list of deltas corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetMeasures()Gets a list of measures corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetSlice()Returns the slice of client data by the axis point corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetSlice(String)Returns the slice of client data by the axis point corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetUnderlyingData()Returns underlying data corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetUnderlyingData(IList<String>)Returns underlying data corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetUnderlyingData(String, IList<String>)Returns underlying data corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.
GetUnderlyingData(String)Returns underlying data corresponding to the visual element located under the test point. Inherited from DashboardItemMouseHitTestEventArgs.

Remarks

Use the DashboardItemMouseEventArgs.DashboardItemName property to obtain the dashboard item name for which the event has been raised. The DashboardItemMouseHitTestEventArgs.Data property returns the client data for this dashboard item.

The DashboardItemMouseHitTestEventArgs.GetAxisPoint method returns the axis point related to the clicked dashboard item element. To obtain the underlying data for this element, use the DashboardItemMouseHitTestEventArgs.GetUnderlyingData method.

Note

The DashboardItemClick event has the following limitations:

Example

The following example demonstrates how to obtain client data corresponding to a particular visual element using DashboardViewer‘s API.

In this example, the DashboardViewer.DashboardItemClick event is handled to obtain client data for the Card dashboard item and display this data in a Chart control.

When a user clicks a card, the app obtains axis points placed on the “Sparkline” axis, determines corresponding actual/target values, and saves these values to a data table. This table is used as a data source for the Chart control.

The Pie dashboard item demonstrates the master filtering feature. Click the slice and the Cards will display client data by the selected year.

View Example: How to obtain a dashboard item's client data in the WinForms Viewer

csharp
using System;
using System.Data;
using System.Drawing;
using System.Windows.Forms;
using DevExpress.XtraEditors;
using DevExpress.DashboardWin;
using DevExpress.DashboardCommon;
using DevExpress.XtraCharts;
using DevExpress.DashboardCommon.ViewerData;

namespace Dashboard_ClientDataCards_Win {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();
            dashboardViewer1.DashboardItemClick += dashboardViewer1_DashboardItemClick;
        }

        // Handles the DashboardViewer.DashboardItemClick event.
        private void dashboardViewer1_DashboardItemClick(object sender, 
            DashboardItemMouseActionEventArgs e) {
            if (e.DashboardItemName == "cardDashboardItem1" & e.GetAxisPoint() != null) {
                // Obtains client data related to the clicked card.
                MultiDimensionalData clickedItemData = e.Data.GetSlice(e.GetAxisPoint());
                DeltaDescriptor delta = e.GetDeltas()[0];

                // Creates a data table that will be used to hold client data.
                DataTable dataSource = new DataTable();
                dataSource.Columns.Add("Argument", typeof(DateTime));
                dataSource.Columns.Add("Actual", typeof(double));
                dataSource.Columns.Add("Target", typeof(double));

                // Saves values of axis points placed on the "sparkline" axis and corresponding
                // actual/target values to the data table.
                foreach (AxisPoint point in 
                    clickedItemData.GetAxisPoints(DashboardDataAxisNames.SparklineAxis)) {
                        DataRow row = dataSource.NewRow();                        
                        DeltaValue deltaValue = clickedItemData.GetSlice(point).GetDeltaValue(delta);
                        if (deltaValue.ActualValue.Value != null && 
                            deltaValue.TargetValue.Value != null) {
                            row["Argument"] = point.Value;
                            row["Actual"] = deltaValue.ActualValue.Value;
                            row["Target"] = deltaValue.TargetValue.Value;
                        }
                        else {
                            row["Argument"] = DBNull.Value;
                            row["Actual"] = DBNull.Value;
                            row["Target"] = DBNull.Value;
                        }
                        dataSource.Rows.Add(row);
                }
                DisplayDetailedChart(GetFormTitle(clickedItemData), dataSource);
            }   
        }

        // Creates a new form that is invoked on the card click and 
        // shows the chart displaying client data.
        void DisplayDetailedChart(string title, DataTable dataSource) {
            XtraForm form = new XtraForm();
            form.Text = title;
            form.Bounds = new Rectangle(100, 100, 700, 350);

            ChartControl chart = new ChartControl();
            chart.Parent = form; chart.Dock = DockStyle.Fill;

            Series series1 = new Series("Actual", ViewType.SplineArea);
            Series series2 = new Series("Target", ViewType.Spline);
            chart.Series.AddRange(new Series[] { series1, series2 });

            foreach (Series series in chart.Series) {
                series.DataSource = dataSource; series.ArgumentDataMember = "Argument";
                series.ValueScaleType = ScaleType.Numerical;                
            }
            series1.ValueDataMembers.AddRange(new string[] { "Actual" });
            series2.ValueDataMembers.AddRange(new string[] { "Target" });
            ((XYDiagram)chart.Diagram).AxisY.Label.TextPattern = "{V:$0}";

            form.ShowDialog();
            form.Dispose();
        }

        // Obtains a value of the axis point placed on the "default" axis
        // to display this value in the invoked form title.
        string GetFormTitle(MultiDimensionalData clickedItemData) {
            AxisPoint clickedPoint = 
                clickedItemData.GetAxisPoints(DashboardDataAxisNames.DefaultAxis)[0];
            string clickedPointValue = clickedPoint.Value.ToString();
            return clickedPointValue;
        }
    }
}
vb
Imports System
Imports System.Data
Imports System.Drawing
Imports System.Windows.Forms
Imports DevExpress.XtraEditors
Imports DevExpress.DashboardWin
Imports DevExpress.DashboardCommon
Imports DevExpress.XtraCharts
Imports DevExpress.DashboardCommon.ViewerData

Namespace Dashboard_ClientDataCards_Win
    Partial Public Class Form1
        Inherits XtraForm

        Public Sub New()
            InitializeComponent()
            AddHandler dashboardViewer1.DashboardItemClick, AddressOf dashboardViewer1_DashboardItemClick
        End Sub

        ' Handles the DashboardViewer.DashboardItemClick event.
        Private Sub dashboardViewer1_DashboardItemClick(ByVal sender As Object, ByVal e As DashboardItemMouseActionEventArgs)
            If e.DashboardItemName = "cardDashboardItem1" And e.GetAxisPoint() IsNot Nothing Then
                ' Obtains client data related to the clicked card.
                Dim clickedItemData As MultiDimensionalData = e.Data.GetSlice(e.GetAxisPoint())
                Dim delta As DeltaDescriptor = e.GetDeltas()(0)

                ' Creates a data table that will be used to hold client data.
                Dim dataSource As New DataTable()
                dataSource.Columns.Add("Argument", GetType(Date))
                dataSource.Columns.Add("Actual", GetType(Double))
                dataSource.Columns.Add("Target", GetType(Double))

                ' Saves values of axis points placed on the "sparkline" axis and corresponding
                ' actual/target values to the data table.
                For Each point As AxisPoint In clickedItemData.GetAxisPoints(DashboardDataAxisNames.SparklineAxis)
                        Dim row As DataRow = dataSource.NewRow()
                        Dim deltaValue As DeltaValue = clickedItemData.GetSlice(point).GetDeltaValue(delta)
                        If deltaValue.ActualValue.Value IsNot Nothing AndAlso deltaValue.TargetValue.Value IsNot Nothing Then
                            row("Argument") = point.Value
                            row("Actual") = deltaValue.ActualValue.Value
                            row("Target") = deltaValue.TargetValue.Value
                        Else
                            row("Argument") = DBNull.Value
                            row("Actual") = DBNull.Value
                            row("Target") = DBNull.Value
                        End If
                        dataSource.Rows.Add(row)
                Next point
                DisplayDetailedChart(GetFormTitle(clickedItemData), dataSource)
            End If
        End Sub

        ' Creates a new form that is invoked on the card click and 
        ' shows the chart displaying client data.
        Private Sub DisplayDetailedChart(ByVal title As String, ByVal dataSource As DataTable)
            Dim form As New XtraForm()
            form.Text = title
            form.Bounds = New Rectangle(100, 100, 700, 350)

            Dim chart As New ChartControl()
            chart.Parent = form
            chart.Dock = DockStyle.Fill

            Dim series1 As New Series("Actual", ViewType.SplineArea)
            Dim series2 As New Series("Target", ViewType.Spline)
            chart.Series.AddRange(New Series() { series1, series2 })

            For Each series As Series In chart.Series
                series.DataSource = dataSource
                series.ArgumentDataMember = "Argument"
                series.ValueScaleType = ScaleType.Numerical
            Next series
            series1.ValueDataMembers.AddRange(New String() { "Actual" })
            series2.ValueDataMembers.AddRange(New String() { "Target" })
            CType(chart.Diagram, XYDiagram).AxisY.Label.TextPattern = "{V:$0}"

            form.ShowDialog()
            form.Dispose()
        End Sub

        ' Obtains a value of the axis point placed on the "default" axis
        ' to display this value in the invoked form title.
        Private Function GetFormTitle(ByVal clickedItemData As MultiDimensionalData) As String
            Dim clickedPoint As AxisPoint = clickedItemData.GetAxisPoints(DashboardDataAxisNames.DefaultAxis)(0)
            Dim clickedPointValue As String = clickedPoint.Value.ToString()
            Return clickedPointValue
        End Function
    End Class
End Namespace

The following code snippets (auto-collected from DevExpress Examples) contain references to the DashboardItemClick event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

winforms-dashboard-obtain-dashboard-item-client-data/CS/Dashboard_ClientDataCards_Win/Form1.cs#L15

csharp
InitializeComponent();
    dashboardViewer1.DashboardItemClick += dashboardViewer1_DashboardItemClick;
}

winforms-dashboard-add-custom-interactivity-to-dashboard/CS/Dashboard_CustomVisualInteractivity/Form1.cs#L14

csharp
dashboardViewer1.DataLoading += dashboardViewer1_DataLoading;
dashboardViewer1.DashboardItemClick += dashboardViewer1_DashboardItemClick;
dashboardViewer1.DashboardItemVisualInteractivity += dashboardViewer1_DashboardItemVisualInteractivity;

winforms-dashboard-window-calculation-example/CS/WindowCalculationExample/Form1.cs#L19

csharp
dashboardViewer1.DashboardItemControlUpdated += DashboardViewer1_DashboardItemControlUpdated;
dashboardViewer1.DashboardItemClick += DashboardViewer1_DashboardItemClick;

winforms-dashboard-obtain-dashboard-item-client-data/VB/Dashboard_ClientDataCards_Win/Form1.vb#L17

vb
InitializeComponent()
    AddHandler dashboardViewer1.DashboardItemClick, AddressOf dashboardViewer1_DashboardItemClick
End Sub

winforms-dashboard-add-custom-interactivity-to-dashboard/VB/Dashboard_CustomVisualInteractivity/Form1.vb#L15

vb
AddHandler dashboardViewer1.DataLoading, AddressOf dashboardViewer1_DataLoading
AddHandler dashboardViewer1.DashboardItemClick, AddressOf dashboardViewer1_DashboardItemClick
AddHandler dashboardViewer1.DashboardItemVisualInteractivity, AddressOf dashboardViewer1_DashboardItemVisualInteractivity

winforms-dashboard-window-calculation-example/VB/WindowCalculationExample/Form1.vb#L21

vb
AddHandler dashboardViewer1.DashboardItemControlUpdated, AddressOf DashboardViewer1_DashboardItemControlUpdated
AddHandler dashboardViewer1.DashboardItemClick, AddressOf DashboardViewer1_DashboardItemClick
Dim helper As TabPageLoadHelper = New TabPageLoadHelper("CalculationProductSalesSource.xml")

Implements

DashboardItemClick

See Also

DashboardItemDoubleClick

DashboardViewer Class

DashboardViewer Members

DevExpress.DashboardWin Namespace