Back to Devexpress

DashboardViewer.DashboardItemControlUpdated Event

dashboard-devexpress-dot-dashboardwin-dot-dashboardviewer-a965fba3.md

latest19.9 KB
Original Source

DashboardViewer.DashboardItemControlUpdated Event

Allows you to access underlying WinForms controls.

Namespace : DevExpress.DashboardWin

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

NuGet Package : DevExpress.Win.Dashboard

Declaration

csharp
public event DashboardItemControlUpdatedEventHandler DashboardItemControlUpdated
vb
Public Event DashboardItemControlUpdated As DashboardItemControlUpdatedEventHandler

Event Data

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

PropertyDescription
CardControlGets an underlying Card control.
ChartContextGets the chart context.
ChartControlGets an underlying chart control.
DashboardItemNameGets the component name of the dashboard item for which the event was raised.
DateFilterControlGets an underlying date filter control.
GaugeContextGets the gauge context.
GaugeControlGets an underlying gauge control.
GridContextGets the grid context.
GridControlGets an underlying grid control.
MapControlGets an underlying map control.
PictureEditGets an underlying picture edit control.
PivotGridControlGets an underlying PivotGridControl.
RichEditControlGets an underlying RichEdit control.
TreeMapControlGets an underlying TreeMap control.

Remarks

The WinForms Viewer uses DevExpress WinForms controls to visualize data within dashboard items. The DashboardItemControlUpdated event allows you to access these controls and customize their settings if necessary.

The DashboardItemControlEventArgs.DashboardItemName property returns the component name of the dashboard item to be customized. Use the following properties to access the corresponding underlying controls.

|

Dashboard Item

|

Control

|

Property

| | --- | --- | --- | |

GridDashboardItem

|

GridControl

|

DashboardItemControlEventArgs.GridControl

| |

ChartDashboardItem

PieDashboardItem

ScatterChartDashboardItem

|

ChartControl

|

DashboardItemControlEventArgs.ChartControl

| |

GaugeDashboardItem

|

GaugeControl

|

DashboardItemControlEventArgs.GaugeControl

| |

CardDashboardItem

|

CardControl

|

DashboardItemControlEventArgs.CardControl

| |

PivotDashboardItem

|

PivotGridControl

|

DashboardItemControlEventArgs.PivotGridControl

| |

MapDashboardItem

|

MapControl

|

DashboardItemControlEventArgs.MapControl

| |

TreemapDashboardItem

|

TreeMapControl

|

DashboardItemControlEventArgs.TreeMapControl

| |

TextBoxDashboardItem

|

RichEditControl

|

DashboardItemControlEventArgs.RichEditControl

| |

ImageDashboardItem

|

PictureEdit

|

DashboardItemControlEventArgs.PictureEdit

| |

DateFilterDashboardItem

|

DateFilterControl

|

DashboardItemControlEventArgs.DateFilterControl

|

You can change the control setting or handle its events. To subscribe/unsubscribe from control events, use the DashboardViewer.DashboardItemControlCreated/DashboardViewer.DashboardItemBeforeControlDisposed events, respectively.

To learn more, see Access to Underlying Controls.

Note

The dashboard item is re-created when you maximize / restore the item. All events connected with dashboard item life cycle (such as DashboardItemControlCreated, DashboardItemControlUpdated, etc.) are fired again.

Examples

How to Customize Controls Used to Visualize Data Within Dashboard Items

The following example demonstrates how to customize controls used to visualize data within dashboard items at runtime using DashboardViewer‘s API.

In this example, the following options are changed:

View Example

vb
Imports System.Drawing
Imports DevExpress.XtraEditors
Imports DevExpress.DashboardWin
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraCharts
Imports DevExpress.XtraPivotGrid

Namespace Dashboard_ControlAccess
    Partial Public Class Form1
        Inherits XtraForm

        Public Sub New()
            InitializeComponent()
            dashboardViewer1.LoadDashboard("..\..\Data\Dashboard.xml")
        End Sub

        Private Sub dashboardViewer1_DashboardItemControlCreated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs) Handles dashboardViewer1.DashboardItemControlCreated
            If e.DashboardItemName = "pivotDashboardItem1" Then
                Dim pivotGridControl As PivotGridControl = e.PivotGridControl
                AddHandler pivotGridControl.CustomCellValue, AddressOf pivotGridControl_CustomCellValue
            End If
        End Sub

        Private Sub pivotGridControl_CustomCellValue(ByVal sender As Object, ByVal e As PivotCellValueEventArgs)
            If e.Value IsNot Nothing AndAlso DirectCast(e.Value, Decimal) < 2000 Then
                e.Value = "Too low to show"
            End If
        End Sub

        Private Sub dashboardViewer1_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs) Handles dashboardViewer1.DashboardItemControlUpdated
            If e.DashboardItemName = "gridDashboardItem1" Then
                Dim gridView As GridView = TryCast(e.GridControl.MainView, GridView)
                gridView.Appearance.Row.Font = New Font("Segoe Script", 10)
            End If
            If e.DashboardItemName = "chartDashboardItem1" Then
                Dim chartControl As ChartControl = e.ChartControl
                CType(chartControl.Diagram, XYDiagram).Panes(0).BackColor = Color.Orange
            End If
        End Sub

        Private Sub dashboardViewer1_DashboardItemBeforeControlDisposed(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs) Handles dashboardViewer1.DashboardItemBeforeControlDisposed
            If e.DashboardItemName = "pivotDashboardItem1" Then
                Dim pivotGridControl As PivotGridControl = e.PivotGridControl
                RemoveHandler pivotGridControl.CustomCellValue, AddressOf pivotGridControl_CustomCellValue
            End If
        End Sub
    End Class
End Namespace
csharp
using System.Drawing;
using DevExpress.XtraEditors;
using DevExpress.DashboardWin;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraCharts;
using DevExpress.XtraPivotGrid;

namespace Dashboard_ControlAccess {
    public partial class Form1 : XtraForm {
        public Form1() {
            InitializeComponent();
            dashboardViewer1.LoadDashboard(@"..\..\Data\Dashboard.xml");
        }

        private void dashboardViewer1_DashboardItemControlCreated(object sender, 
            DashboardItemControlEventArgs e) {
            if (e.DashboardItemName == "pivotDashboardItem1") {
                PivotGridControl pivotGridControl = e.PivotGridControl;
                pivotGridControl.CustomCellValue += pivotGridControl_CustomCellValue;
            }
        }

        void pivotGridControl_CustomCellValue(object sender, PivotCellValueEventArgs e) {
            if (e.Value != null && (decimal)e.Value < 2000)
                e.Value = "Too low to show";
        }

        private void dashboardViewer1_DashboardItemControlUpdated(object sender, 
            DashboardItemControlEventArgs e) {
            if (e.DashboardItemName == "gridDashboardItem1") {
                GridView gridView = e.GridControl.MainView as GridView;
                gridView.Appearance.Row.Font = new Font("Segoe Script", 10);
            }
            if (e.DashboardItemName == "chartDashboardItem1") {
                ChartControl chartControl = e.ChartControl;                
                ((XYDiagram)chartControl.Diagram).Panes[0].BackColor = Color.Orange;
            }
        }

        private void dashboardViewer1_DashboardItemBeforeControlDisposed(object sender, 
            DashboardItemControlEventArgs e) {
            if (e.DashboardItemName == "pivotDashboardItem1") {
                PivotGridControl pivotGridControl = e.PivotGridControl;
                pivotGridControl.CustomCellValue -= pivotGridControl_CustomCellValue;
            }
        }
    }
}

How to Display the Total Value in the Title for the Pie Item

This example demonstrates how to access the underlying controls used to display the Pie Item and configure their settings to display the Total value in the title. Total values are calculated automatically if the CalculateHiddenTotals property is enabled. Use the DashboardViewer.GetItemData method to get the total value.

View Example

csharp
using DevExpress.DashboardCommon.ViewerData;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;

namespace TotalsInChartsExample
{
    public partial class Form1 : DevExpress.XtraEditors.XtraForm
    {
        public Form1() {
            InitializeComponent();

            dashboardViewer1.DashboardItemControlUpdated += Viewer_DashboardItemControlUpdated;
            dashboardViewer1.CalculateHiddenTotals = true;
            dashboardViewer1.DashboardSource = typeof(Dashboards.Dashboard1);
        }

        private void Viewer_DashboardItemControlUpdated(object sender, DashboardItemControlEventArgs e) {
            if (e.DashboardItemName == "pieDashboardItem1") {
                var viewer = (DashboardViewer)sender;
                var chart = e.ChartControl;

                var data = viewer.GetItemData(e.DashboardItemName);
                var measure = data.GetMeasures()[0];

                foreach (Series series in chart.Series) {
                    var axisPoint = series.Tag as AxisPoint;
                    if (axisPoint != null) {
                        var total = data.GetSlice(axisPoint).GetValue(measure).DisplayText;
                        var view = series.View as PieSeriesView;
                        if (view != null)
                            view.Titles[0].Text = string.Format("{0} - {1}", series.Name, total);
                    }
                }
            }
        }
    }
}
vb
Imports DevExpress.DashboardCommon.ViewerData
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts

Namespace TotalsInChartsExample
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Public Sub New()
            InitializeComponent()

            AddHandler dashboardViewer1.DashboardItemControlUpdated, AddressOf Viewer_DashboardItemControlUpdated
            dashboardViewer1.CalculateHiddenTotals = True
            dashboardViewer1.DashboardSource = GetType(Dashboards.Dashboard1)
        End Sub

        Private Sub Viewer_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs)
            If e.DashboardItemName = "pieDashboardItem1" Then
                Dim viewer = DirectCast(sender, DashboardViewer)
                Dim chart = e.ChartControl

                Dim data = viewer.GetItemData(e.DashboardItemName)
                Dim measure = data.GetMeasures()(0)

                For Each series As Series In chart.Series
                    Dim axisPoint = TryCast(series.Tag, AxisPoint)
                    If axisPoint IsNot Nothing Then
                        Dim total = data.GetSlice(axisPoint).GetValue(measure).DisplayText
                        Dim view = TryCast(series.View, PieSeriesView)
                        If view IsNot Nothing Then
                            view.Titles(0).Text = String.Format("{0} - {1}", series.Name, total)
                        End If
                    End If
                Next series
            End If
        End Sub
    End Class
End Namespace

The following code snippets (auto-collected from DevExpress Examples) contain references to the DashboardItemControlUpdated 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-window-calculation-example/CS/WindowCalculationExample/Form1.cs#L18

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

how-to-display-the-total-value-above-each-pie-chart/CS/TotalsInChartsExample/Form1.cs#L12

csharp
dashboardViewer1.DashboardItemControlUpdated += Viewer_DashboardItemControlUpdated;
dashboardViewer1.CalculateHiddenTotals = true;

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

vb
AddHandler dashboardViewer1.DashboardItemControlCreated, AddressOf DashboardViewer1_DashboardItemControlCreated
AddHandler dashboardViewer1.DashboardItemControlUpdated, AddressOf DashboardViewer1_DashboardItemControlUpdated
AddHandler dashboardViewer1.DashboardItemClick, AddressOf DashboardViewer1_DashboardItemClick

how-to-display-the-total-value-above-each-pie-chart/VB/TotalsInChartsExample/Form1.vb#L12

vb
AddHandler dashboardViewer1.DashboardItemControlUpdated, AddressOf Viewer_DashboardItemControlUpdated
dashboardViewer1.CalculateHiddenTotals = True

Implements

DashboardItemControlUpdated

See Also

DashboardViewer Class

DashboardViewer Members

DevExpress.DashboardWin Namespace