dashboard-401684-winforms-dashboard-winforms-viewer-display-custom-properties.md
Custom properties allow you to store custom settings in dashboard definition. You can read these settings and use these values to natively implement and embed your own functionality into the Dashboard Viewer.
If a custom property is stored in your dashboard definition, you can display its value in the WinForms Dashboard Viewer.
You can read custom properties’ data that is stored on the following levels:
| Level | Description | Property |
|---|---|---|
| Dashboard | Custom data related to the dashboard. | Dashboard.CustomProperties |
| Dashboard item | Custom data related to a particular dashboard item. | DashboardItem.CustomProperties |
| Data item container | Custom data related to the Grid’s columns, the Chart’s series and other elements of a dashboard item. | DataItemContainer.CustomProperties |
Use the CustomProperties.GetValue method to read a value of the specified custom property.
For example, the DashboardDescription custom property is stored in a dashboard XML file at the dashboard’s level. The custom property’s value is stored as a string.
<Dashboard>
...
<CustomProperties>
<DashboardDescription>This dashboard shows statistics on sales of bicycles, related equipment and accessories. ...</DashboardDescription>
</CustomProperties>
</Dashboard>
The following code snippet illustrates how to read the property’s value:
var currentDescription = viewer.Dashboard.CustomProperties.GetValue("DashboardDescription");
Dim currentDescription = viewer.Dashboard.CustomProperties.GetValue("DashboardDescription")
All property values are stored in string format. You can use system methods like Convert.ToBoolean or Convert.ToInt32 to convert the custom property’s value to a base data type.
For complex conversions, use the class below:
using DevExpress.DashboardCommon;
using System;
using System.Collections.Generic;
using System.Linq;
namespace WindowsFormsAppCustomProperties {
public static class CustomPropertyExtensions {
public static T GetValue<T>(this CustomProperties property, string name) where T : struct {
var value = property.GetValue(name);
if(value == null) return default(T);
return (T)Convert.ChangeType(value, typeof(T));
}
public static EnumType ConvertToEnum<EnumType>(this String enumValue) {
return (EnumType)Enum.Parse(typeof(EnumType), enumValue);
}
public static string ConvertToString(this Enum enumValue) {
return Enum.GetName(enumValue.GetType(), enumValue);
}
}
}
Imports DevExpress.DashboardCommon
Imports System
Imports System.Collections.Generic
Imports System.Linq
Namespace WindowsFormsAppCustomProperties
Public NotInheritable Class CustomPropertyExtensions
Private Sub New()
End Sub
_
Public Shared Function GetValue(Of T As Structure)(ByVal [property] As CustomProperties, ByVal name As String) As T
Dim value = [property].GetValue(name)
If value Is Nothing Then
Return Nothing
End If
Return CType(Convert.ChangeType(value, GetType(T)), T)
End Function
_
Public Shared Function ConvertToEnum(Of EnumType)(ByVal enumValue As String) As EnumType
Return CType(System.Enum.Parse(GetType(EnumType), enumValue), EnumType)
End Function
_
Public Shared Function ConvertToString(ByVal enumValue As System.Enum) As String
Return System.Enum.GetName(enumValue.GetType(), enumValue)
End Function
End Class
End Namespace
The code line below converts a string to a CheckMode enumeration value:
var newValue = designer.Dashboard.Items[itemName].CustomProperties.GetValue<CheckMode>(PropertyName);
Dim newValue = designer.Dashboard.Items(itemName).CustomProperties.GetValue(Of CheckMode)(PropertyName)
To update a dashboard and underlying controls according to the custom property’s value, use a set of API listed below:
| Event | Description |
|---|---|
| DashboardViewer.DashboardItemControlUpdated | Allows you to access underlying WinForms controls. |
| DashboardViewer.DashboardItemControlCreated | Allows you to access underlying WinForms controls. |
| DashboardViewer.DashboardCustomPropertyChanged | Occurs when the custom property’s value in the Dashboard Viewer is changed. |
| DashboardViewer.CustomizeDashboardTitle | Allows you to customize the dashboard title at runtime. |
| Dashboard.OptionsChanged | Occurs after any option in the current Dashboard is changed. |
| DashboardViewer.CustomizeDashboardItemCaption | Allows you to customize the dashboard item caption at runtime. |
| DashboardViewer.PopupMenuShowing | Allows you to customize a popup menu invoked by end-users in the DashboardViewer. |
Use context to provide a connection between data item containers and an underlying control’s elements when you apply a custom property for a data item container:
| API | Description |
|---|---|
| ChartContext.GetDashboardItemSeries | |
| ChartContext.GetControlSeries | Provides a connection between the ChartSeries object and corresponding Series. |
| GaugeContext.GetDashboardGauge | |
| GaugeContext.GetControlGauges | Provides a connection between the Gauge object and corresponding control’s gauge element. |
| GridContext.GetDashboardItemColumn | |
| GridContext.GetControlColumn | Provides a connection between the GridColumnBase descendant and corresponding control’s column. |
You can handle the DashboardViewer.CustomExport event to customize the exported document and display the same modifications the custom property provides.
You can organize the code related to a custom functionality into a separate module you can integrate in any dashboard application.
Create a new class that serves as a custom functionality module and contains:
To integrate the created functionality in your dashboard application, call the created module’s constructor, and pass the dashboard control’s instance in it.
You should register the created module before you load a dashboard to apply settings to this dashboard:
public Form1() {
InitializeComponent();
new WinDashboardDescriptionViewer(dashboardViewer1);
dashboardViewer1.LoadDashboard("../../Dashboard/newDashboard.xml");
}
Public Sub New()
InitializeComponent()
Dim TempWinDashboardDescriptionViewer As WinDashboardDescriptionViewer = New WinDashboardDescriptionViewer(dashboardViewer1)
dashboardViewer1.LoadDashboard("../../Dashboard/newDashboard.xml")
End Sub
The code below display Chart’s scale breaks. The information about scale breaks visibility is saved as a custom property:
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using DevExpress.XtraCharts;
using System;
namespace WindowsFormsAppCustomProperties {
public class ViewerScaleBreak {
public static readonly string PropertyName = "ScaleBreak";
readonly IDashboardControl dashboardControl;
readonly SvgImage titleDescriptionImage;
public ViewerScaleBreak(DashboardViewer dashboardControl, SvgImage barImage = null) {
this.dashboardControl = dashboardControl;
dashboardControl.DashboardItemControlUpdated += DashboardControl_DashboardItemControlUpdated;
}
void DashboardControl_DashboardItemControlUpdated(object sender, DashboardItemControlEventArgs e) {
if(e.ChartControl != null) {
bool value = Convert.ToBoolean(dashboardControl.Dashboard.Items[e.DashboardItemName].CustomProperties.GetValue(PropertyName));
UpdateChart(e.ChartControl, value);
}
}
void UpdateChart(ChartControl chart, bool scaleBreakEnabled) {
if(chart.Diagram != null)
((XYDiagram)chart.Diagram).SecondaryAxesY[0].AutoScaleBreaks.Enabled = scaleBreakEnabled;
}
}
}
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraCharts
Imports System
Namespace WindowsFormsAppCustomProperties
Public Class ViewerScaleBreak
Public Shared ReadOnly PropertyName As String = "ScaleBreak"
Private ReadOnly dashboardControl As IDashboardControl
Private ReadOnly titleDescriptionImage As SvgImage
Public Sub New(ByVal dashboardControl As DashboardViewer, Optional ByVal barImage As SvgImage = Nothing)
Me.dashboardControl = dashboardControl
AddHandler dashboardControl.DashboardItemControlUpdated, AddressOf DashboardControl_DashboardItemControlUpdated
End Sub
Private Sub DashboardControl_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs)
If e.ChartControl IsNot Nothing Then
Dim value As Boolean = Convert.ToBoolean(dashboardControl.Dashboard.Items(e.DashboardItemName).CustomProperties.GetValue(PropertyName))
UpdateChart(e.ChartControl, value)
End If
End Sub
Private Sub UpdateChart(ByVal chart As ChartControl, ByVal scaleBreakEnabled As Boolean)
If chart.Diagram IsNot Nothing Then
CType(chart.Diagram, XYDiagram).SecondaryAxesY(0).AutoScaleBreaks.Enabled = scaleBreakEnabled
End If
End Sub
End Class
End Namespace
The code below displays a dashboard description. Text for the description is saved as a custom property value:
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using System;
using System.Windows.Forms;
namespace WindowsFormsAppCustomProperties {
public class DescriptionViewer {
public static readonly string PropertyName = "DashboardDescription";
readonly IDashboardControl dashboardControl;
readonly SvgImage titleDescriptionImage;
public DescriptionViewer(IDashboardControl dashboardControl, SvgImage titleDescriptionImage = null) {
this.dashboardControl = dashboardControl;
this.titleDescriptionImage = titleDescriptionImage;
dashboardControl.CustomizeDashboardTitle += DashboardControl_CustomizeDashboardTitle;
}
void DashboardControl_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
string text = dashboardControl.Dashboard.CustomProperties.GetValue(PropertyName);
if (!string.IsNullOrEmpty(text)) {
DashboardToolbarItem showDataItem = new DashboardToolbarItem("Description",
new Action<DashboardToolbarItemClickEventArgs>((args) => {
MessageBox.Show(text, "Description");
}));
showDataItem.SvgImage = titleDescriptionImage;
e.Items.Insert(0, showDataItem);
}
}
}
}
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports System
Imports System.Windows.Forms
Namespace WindowsFormsAppCustomProperties
Public Class DescriptionViewer
Public Shared ReadOnly PropertyName As String = "DashboardDescription"
Private ReadOnly dashboardControl As IDashboardControl
Private ReadOnly titleDescriptionImage As SvgImage
Public Sub New(ByVal dashboardControl As IDashboardControl, Optional ByVal titleDescriptionImage As SvgImage = Nothing)
Me.dashboardControl = dashboardControl
Me.titleDescriptionImage = titleDescriptionImage
AddHandler dashboardControl.CustomizeDashboardTitle, AddressOf DashboardControl_CustomizeDashboardTitle
End Sub
Private Sub DashboardControl_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
Dim text As String = dashboardControl.Dashboard.CustomProperties.GetValue(PropertyName)
If (Not String.IsNullOrEmpty(text)) Then
Dim showDataItem As New DashboardToolbarItem("Description", New Action(Of DashboardToolbarItemClickEventArgs)(Function(args) AnonymousMethod1(args, text)))
showDataItem.SvgImage = titleDescriptionImage
e.Items.Insert(0, showDataItem)
End If
End Sub
Private Function AnonymousMethod1(ByVal args As Object, ByVal text As String) As Boolean
MessageBox.Show(text, "Description")
Return True
End Function
End Class
End Namespace