Display Custom Properties
- 6 minutes to read
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.
Read a Custom Property’s Value
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");
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);
}
}
}
The code line below converts a string to a CheckMode enumeration value:
var newValue = designer.Dashboard.Items[itemName].CustomProperties.GetValue<CheckMode>(PropertyName);
Update the Behavior Based on the Custom Property’s Value
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.
Create a Custom Functionality Module
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:
- a dashboard control that you pass as a parameter when you register the module (you can also use the IDashboardControl interface to provide common API for WinForms Designer and Viewer),
- a custom property’s unique name,
- event subscriptions that used to provide custom functionality.
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");
}
Examples
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;
}
}
}
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);
}
}
}
}