Access to Underlying Controls

The WinForms Viewer uses DevExpress WinForms controls to visualize data within dashboard items. If necessary, you can access these controls and customize their settings to add specific capabilities.

The DashboardViewer control exposes the following events that allow you to access these controls and customize their settings.

The DashboardItemControlEventArgs.DashboardItemName event parameter 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

Limitations

Note that changing specific control settings may lead to various issues. We do not recommend changing the following settings:

  • data binding settings;
  • basic data presentation settings (for instance, a set of grid columns, chart series or pivot grid fields).
Note

Note that printed or exported documents containing a dashboard/dashboard item do not reflect appearance settings applied using the events for accessing of underlying controls.

Example

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:

´╗┐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 CDec(e.Value) < 2000 Then
                e.Value = 0
            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("Arial", 10)
            End If
            If e.DashboardItemName = "chartDashboardItem1" Then
                Dim chartControl As ChartControl = e.ChartControl
                CType(chartControl.Diagram, XYDiagram).Panes(0).BackColor = Color.AliceBlue
            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