dashboard-18019-winforms-dashboard-winforms-viewer-access-to-underlying-controls.md
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.
DashboardItemControlCreatedAllows you to access underlying WinForms controls.DashboardItemControlUpdatedAllows you to access underlying WinForms controls.DashboardItemBeforeControlDisposedAllows you to access underlying WinForms controls.
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
| | --- | --- | --- | |
|
|
DashboardItemControlEventArgs.GridControl
| |
|
|
DashboardItemControlEventArgs.ChartControl
| |
|
|
DashboardItemControlEventArgs.GaugeControl
| |
|
|
DashboardItemControlEventArgs.CardControl
| |
|
|
DashboardItemControlEventArgs.PivotGridControl
| |
|
|
DashboardItemControlEventArgs.MapControl
| |
|
|
DashboardItemControlEventArgs.TreeMapControl
| |
|
|
DashboardItemControlEventArgs.RichEditControl
| |
|
|
DashboardItemControlEventArgs.PictureEdit
| |
|
|
DashboardItemControlEventArgs.DateFilterControl
|
You can also access underlying controls with the following methods:
DashboardViewer.GetUnderlyingControlGets the underlying control used to visualize data within the specified dashboard item.DashboardViewer.GetUnderlyingControlsGets the underlying controls used to visualize data within the dashboard items.
Note that changing specific control settings may lead to various issues. We do not recommend changing the following settings:
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.
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 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
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;
}
}
}
}
Although the export does not automatically applies custom settings, you can customize the exported document. For this, handle the DashboardViewer.CustomExport event.
The following example shows how to customize dashboard items in the exported document when you handle the DashboardDesigner.CustomExport / DashboardViewer.CustomExport / DashboardControl.CustomExport events. You can use the CustomExportEventArgs.GetPrintableControls method to obtain the printable controls.
using DevExpress.DashboardCommon;
using DevExpress.DashboardExport;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;
using DevExpress.XtraGauges.Core.Drawing;
using DevExpress.XtraGauges.Win.Base;
using DevExpress.XtraGauges.Win.Gauges.Circular;
using DevExpress.XtraReports.UI;
private void DashboardControl_CustomExport(object sender, CustomExportEventArgs e) {
foreach(var printControl in e.GetPrintableControls()) {
if(printControl.Value is XRGaugeDashboardItem) {
var gaugeItemName = printControl.Key;
DashboardViewer viewer = (DashboardViewer)sender;
var gaugeDashboardItem = viewer.Dashboard.Items[gaugeItemName] as GaugeDashboardItem;
foreach(var dashGaugeElement in gaugeDashboardItem.Gauges) {
foreach(var gaugePanel in
e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast<XRDashboardGauge>()) {
if(gaugePanel != null) {
gaugePanel.MainSeriesLabel.ForeColor = Color.Red;
}
}
}
}
if(printControl.Value is XRChart) {
var chartItemName = printControl.Key;
DashboardViewer viewer = (DashboardViewer)sender;
var chartDashboardItem = viewer.Dashboard.Items[chartItemName] as ChartDashboardItem;
foreach(var pane in chartDashboardItem.Panes) {
if(pane.Series.Count > 0) {
foreach(var dashSeries in pane.Series) {
if(dashSeries != null) {
var controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries);
if(controlSeries != null) {
foreach(var ser in controlSeries) {
LineSeriesView view = ser.View as LineSeriesView;
if(view != null) {
view.LineStyle.DashStyle = DashStyle.DashDot;
}
}
}
}
}
}
}
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardExport
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts
Imports DevExpress.XtraGauges.Core.Drawing
Imports DevExpress.XtraGauges.Win.Base
Imports DevExpress.XtraGauges.Win.Gauges.Circular
Imports DevExpress.XtraReports.UI
Private Sub DashboardControl_CustomExport(ByVal sender As Object, ByVal e As CustomExportEventArgs)
For Each printControl In e.GetPrintableControls()
If TypeOf printControl.Value Is XRDashboardPanel Then
Dim gaugeItemName = printControl.Key
Dim designer As DashboardDesigner = CType(sender, DashboardDesigner)
Dim gaugeDashboardItem = TryCast(designer.Dashboard.Items(gaugeItemName), GaugeDashboardItem)
For Each dashGaugeElement In gaugeDashboardItem.Gauges
For Each gaugePanel In e.GetGaugeContext(gaugeItemName).GetPrintableGauges(dashGaugeElement).Cast(Of XRDashboardGaugePanel)()
If gaugePanel IsNot Nothing Then
gaugePanel.MainSeriesLabel.ForeColor = Color.Red
End If
Next gaugePanel
Next dashGaugeElement
End If
If TypeOf printControl.Value Is XRChart Then
Dim chartItemName = printControl.Key
Dim designer As DashboardDesigner = CType(sender, DashboardDesigner)
Dim chartDashboardItem = TryCast(designer.Dashboard.Items(chartItemName), ChartDashboardItem)
For Each pane In chartDashboardItem.Panes
If pane.Series.Count > 0 Then
For Each dashSeries In pane.Series
If dashSeries IsNot Nothing Then
Dim controlSeries = e.GetChartContext(chartItemName).GetControlSeries(dashSeries)
If controlSeries IsNot Nothing Then
For Each ser In controlSeries
Dim view As LineSeriesView = TryCast(ser.View, LineSeriesView)
If view IsNot Nothing Then
view.LineStyle.DashStyle = DashStyle.DashDot
End If
Next ser
End If
End If
Next dashSeries
End If
Next pane
End If
Next printControl
End Sub
The following example shows how to use the DashboardViewer.CustomExport event to specify header and footer content of an exported dashboard. This event allows you to access the underlying report (XtraReport) of the exported document.