Access to Underlying Controls

• Dec 22, 2020
• 4 minutes to read

The WinForms Designer 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 DashboardDesigner control exposes the following events that allow you to access these controls and customize their settings.

Event	Description
DashboardDesigner.DashboardItemControlCreated	Allows you to subscribe to control events.
DashboardDesigner.DashboardItemControlUpdated	Allows you to access underlying controls and customize their settings.
DashboardDesigner.DashboardItemBeforeControlDisposed	Allows you 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.

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 also access underlying controls with the following methods:

Method	Description
DashboardDesigner.GetUnderlyingControl	Gets the underlying control used to visualize data within the specified dashboard item.
DashboardDesigner.GetUnderlyingControls	Gets the underlying controls used to visualize data within the dashboard items.

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

This example demonstrates how to customize the controls used to visualize data in the dashboard items at runtime.

The following options are changed:

• Grid: The DashboardDesigner.DashboardItemControlUpdated event is handled to change font.
• Chart: The DashboardDesigner.DashboardItemControlUpdated event is handled to change the background color of the chart pane.
• Pivot: Cell values related to “Mountain” products are hidden. The PivotGridControl.CustomCellValue, DashboardDesigner.DashboardItemControlCreated and DashboardDesigner.DashboardItemBeforeControlDisposed events are handled.

View Example: How to Access the Underlying Controls of the Dashboard Items

Form1.cs

using DevExpress.XtraCharts;
using DevExpress.XtraGrid.Views.Grid;
using DevExpress.XtraPivotGrid;
using System.Drawing;

namespace DashboardDesigner_ControlAccess
{
    public partial class DesignerForm1: DevExpress.XtraBars.Ribbon.RibbonForm
    {
        public DesignerForm1() {
            InitializeComponent();
            dashboardDesigner.CreateRibbon();
            dashboardDesigner.LoadDashboard(@"..\..\Dashboards\dashboard1.xml");
        }

        private void dashboardDesigner_DashboardItemControlCreated(object sender, DevExpress.DashboardWin.DashboardItemControlEventArgs e) {
            if(e.DashboardItemName == "pivotDashboardItem1") {
                PivotGridControl pivotGridControl = e.PivotGridControl;
                pivotGridControl.CustomCellValue += PivotGridControl_CustomCellValue; ;
            }
        }

        private void PivotGridControl_CustomCellValue(object sender, PivotCellValueEventArgs e) {
            if (e.RowField == null) return;
            if (e.GetFieldValue(e.RowField).ToString().Contains("Mountain"))
                e.Value = "###";
        }

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

        private void dashboardDesigner_DashboardItemBeforeControlDisposed(object sender, DevExpress.DashboardWin.DashboardItemControlEventArgs e) {
            if(e.DashboardItemName == "pivotDashboardItem1") {
                PivotGridControl pivotGridControl = e.PivotGridControl;
                pivotGridControl.CustomCellValue -= PivotGridControl_CustomCellValue;
            }
        }
    }
}

Form1.vb

Imports DevExpress.XtraCharts
Imports DevExpress.XtraGrid.Views.Grid
Imports DevExpress.XtraPivotGrid
Imports System.Drawing

Namespace DashboardDesigner_ControlAccess
    Partial Public Class DesignerForm1
        Inherits DevExpress.XtraBars.Ribbon.RibbonForm

        Public Sub New()
            InitializeComponent()
            dashboardDesigner.CreateRibbon()
            dashboardDesigner.LoadDashboard("..\..\Dashboards\dashboard1.xml")
        End Sub

        Private Sub dashboardDesigner_DashboardItemControlCreated(ByVal sender As Object, ByVal e As DevExpress.DashboardWin.DashboardItemControlEventArgs) Handles dashboardDesigner.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.RowField Is Nothing Then
                Return
            End If
            If e.GetFieldValue(e.RowField).ToString().Contains("Mountain") Then
                e.Value = "###"
            End If
        End Sub

        Private Sub dashboardDesigner_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DevExpress.DashboardWin.DashboardItemControlEventArgs) Handles dashboardDesigner.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 dashboardDesigner_DashboardItemBeforeControlDisposed(ByVal sender As Object, ByVal e As DevExpress.DashboardWin.DashboardItemControlEventArgs) Handles dashboardDesigner.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