Access to Underlying Controls
- 4 min to read
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.
- Use the DashboardViewer.DashboardItemControlCreated event to subscribe to control events.
- Use the DashboardViewer.DashboardItemControlUpdated event to access underlying controls and customize their settings.
- Use the DashboardViewer.DashboardItemBeforeControlDisposed event to unsubscribe from control events.
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.
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 that printed or exported documents containing a dashboard/dashboard item do not reflect appearance settings applied using the events for accessing of underlying controls.
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:
- The font of data rows' text is changed in the underlying grid control in the DashboardViewer.DashboardItemControlUpdated event handler.
- The background color of the chart's pane is changed in the DashboardViewer.DashboardItemControlUpdated event handler.
- Values of data cells in the underlying pivot grid control are customized using the PivotGridControl.CustomCellValue event. Subscription and unsubscription to/from the CustomCellValue event are performed in the DashboardViewer.DashboardItemControlCreated and DashboardViewer.DashboardItemBeforeControlDisposed event handlers respectively.
A complete sample project is available at https://github.com/DevExpress-Examples/how-to-access-api-of-underlying-controls-in-the-winforms-viewer-t197114.
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