Access to Underlying Controls
- 3 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.
- Use the DashboardDesigner.DashboardItemControlCreated event to subscribe to control events.
- Use the DashboardDesigner.DashboardItemControlUpdated event to access underlying controls and customize their settings.
- Use the DashboardDesigner.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.
Dashboard Item | Control | Property |
|---|---|---|
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:
- Grid: The font of data rows’ text is changed in the underlying grid control in the DashboardDesigner.DashboardItemControlUpdated event.
- Chart: The background color of the chart’s pane is changed in the DashboardDesigner.DashboardItemControlUpdated event handler.
- Pivot: 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 DashboardDesigner.DashboardItemControlCreated and DashboardItemBeforeControlDisposed event handlers respectively.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/winforms-dashboard-control-access.
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.Value != null && (double)e.Value < 200000)
e.Value = 0;
}
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;
}
}
}
}