dashboard-401620-winforms-dashboard-winforms-designer-ui-elements-and-customization-create-custom-properties-chart-item-scale-breaks.md
This topic describes how to create a custom property for a dashboard item. In this example, the custom property enables or disables scale breaks for the selected Chart item in the WinForms Dashboard Designer. A Boolean property is used in the example, so you can click the Ribbon button to change Chart’s behavior.
View Example: WinForms Dashboard - Custom Properties
The code is organized in a separate module you can integrate into any dashboard application.
Create the ChartScaleBreakModule class that serves as a custom functionality module and contains:
Note
You can use the IDashboardControl interface that provides common API for WinForms Designer and Viewer to write code that can be used in both controls simultaneously.
Add control elements to the Ribbon / Toolbar to change the custom property’s value in the Dashboard Designer’s UI.
In this example, the AddBarItem method places the Scale Break button in the Custom Properties ribbon group on the Chart’s Design page.
public class ChartScaleBreakModule {
public static readonly string PropertyName = "ScaleBreak";
readonly DashboardDesigner designer;
BarCheckItem barItem;
public ChartScaleBreakModule(DashboardDesigner designer, SvgImage barImage = null) {
this.designer = designer;
RibbonControl ribbon = (RibbonControl)designer.MenuManager;
RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.ChartTools, DashboardRibbonPage.Design);
RibbonPageGroup group = page.GetGroupByName("Custom Properties");
if(group == null) {
group = new RibbonPageGroup("Custom Properties") { Name = "Custom Properties" };
page.Groups.Add(group);
}
barItem = CreateBarItem("Scale Break", barImage);
group.ItemLinks.Add(barItem);
barItem.ItemClick += ChangeCustomPropertyValue;
designer.DashboardItemControlUpdated += Designer_DashboardItemControlUpdated;
designer.DashboardItemSelected += Designer_DashboardItemSelected;
designer.DashboardCustomPropertyChanged += Designer_DashboardCustomPropertyChanged;
}
BarCheckItem CreateBarItem(string caption, SvgImage barImage) {
BarCheckItem barItem = new BarCheckItem();
barItem.Caption = caption;
barItem.ImageOptions.SvgImage = barImage;
return barItem;
}
Public Class ChartScaleBreakModule
Public Shared ReadOnly PropertyName As String = "ScaleBreak"
Private ReadOnly designer As DashboardDesigner
Private barItem As BarCheckItem
Public Sub New(ByVal designer As DashboardDesigner, Optional ByVal barImage As SvgImage = Nothing)
Me.designer = designer
Dim ribbon As RibbonControl = CType(designer.MenuManager, RibbonControl)
Dim page As RibbonPage = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.ChartTools, DashboardRibbonPage.Design)
Dim group As RibbonPageGroup = page.GetGroupByName("Custom Properties")
If group Is Nothing Then
group = New RibbonPageGroup("Custom Properties") With {.Name = "Custom Properties"}
page.Groups.Add(group)
End If
barItem = CreateBarItem("Scale Break", barImage)
group.ItemLinks.Add(barItem)
barItem.ItemClick += ChangeCustomPropertyValue
designer.DashboardItemControlUpdated += Designer_DashboardItemControlUpdated
designer.DashboardItemSelected += Designer_DashboardItemSelected
designer.DashboardCustomPropertyChanged += Designer_DashboardCustomPropertyChanged
End Sub
Private Function CreateBarItem(ByVal caption As String, ByVal barImage As SvgImage) As BarCheckItem
Dim barItem As New BarCheckItem()
barItem.Caption = caption
barItem.ImageOptions.SvgImage = barImage
Return barItem
End Function
In this example, the property’s value is stored in the DashboardItem.CustomProperties collection.
Use the DashboardDesigner.AddToHistory method to record a new custom property’s value and save the action to the Dashboard Designer’s history when a user changes the value. This method calls the CustomProperties.SetValue method and adds the information to the history item. You can undo/redo this action like other user actions.
void ChangeCustomPropertyValue(object sender, ItemClickEventArgs e) {
DashboardItem dashboardItem = designer.SelectedDashboardItem;
bool newValue = !Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName));
string status = newValue ? "enabled" : "disabled";
CustomPropertyHistoryItem historyItem = new CustomPropertyHistoryItem(dashboardItem, PropertyName, newValue.ToString(), $"Scale break for {dashboardItem.ComponentName} is {status}");
designer.AddToHistory(historyItem);
}
Private Sub ChangeCustomPropertyValue(ByVal sender As Object, ByVal e As ItemClickEventArgs)
Dim dashboardItem As DashboardItem = designer.SelectedDashboardItem
Dim newValue As Boolean = Not Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName))
Dim status As String = If(newValue, "enabled", "disabled")
Dim historyItem As New CustomPropertyHistoryItem(dashboardItem, PropertyName, newValue.ToString(), $"Scale break for {dashboardItem.ComponentName} is {status}")
designer.AddToHistory(historyItem)
End Sub
Handle the DashboardDesigner.DashboardItemControlUpdated event to access the underlying Chart control. Call the CustomProperties.GetValue method to get the AutoScaleBreaks property’s value. Update the Chart’s options according to this value:
void Designer_DashboardItemControlUpdated(object sender, DashboardItemControlEventArgs e) {
if(e.ChartControl != null)
UpdateChartScaleBreaks(designer.Dashboard.Items[e.DashboardItemName], e.ChartControl.Diagram);
}
void UpdateChartScaleBreaks(DashboardItem dashboardItem, Diagram chartDiagram) {
if (chartDiagram is XYDiagram diagram){
bool scaleBreakEnabled = Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName));
diagram.SecondaryAxesY[0].AutoScaleBreaks.Enabled = scaleBreakEnabled;
}
}
Private Sub Designer_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs)
If e.ChartControl IsNot Nothing Then
UpdateChartScaleBreaks(designer.Dashboard.Items(e.DashboardItemName), e.ChartControl.Diagram)
End If
End Sub
Private Sub UpdateChartScaleBreaks(ByVal dashboardItem As DashboardItem, ByVal chartDiagram As Diagram)
Dim tempVar As Boolean = TypeOf chartDiagram Is XYDiagram
Dim diagram As XYDiagram = If(tempVar, CType(chartDiagram, XYDiagram), Nothing)
If tempVar Then
Dim scaleBreakEnabled As Boolean = Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName))
diagram.SecondaryAxesY(0).AutoScaleBreaks.Enabled = scaleBreakEnabled
End If
End Sub
Create the UpdateBarItem method to update the bar item’s checked state according to the property’s value. The bar item should be checked if this property is enabled.
Handle the DashboardDesigner.DashboardCustomPropertyChanged event to update the bar item each time the custom property’s value changes.
Subscribe to the DashboardDesigner.DashboardItemSelected event to update the bar item’s checked state when you select another Chart item.
void UpdateBarItem() {
if (designer.SelectedDashboardItem != null)
barItem.Checked = Convert.ToBoolean(designer.SelectedDashboardItem.CustomProperties.GetValue(PropertyName));
}
void Designer_DashboardCustomPropertyChanged(object sender, CustomPropertyChangedEventArgs e) {
if(e.Name == PropertyName)
UpdateBarItem();
}
void Designer_DashboardItemSelected(object sender, DevExpress.DashboardWin.ServiceModel.DashboardItemSelectedEventArgs e) {
UpdateBarItem();
}
Private Sub UpdateBarItem()
If designer.SelectedDashboardItem IsNot Nothing Then
barItem.Checked = Convert.ToBoolean(designer.SelectedDashboardItem.CustomProperties.GetValue(PropertyName))
End if
End Sub
Private Sub Designer_DashboardCustomPropertyChanged(ByVal sender As Object, ByVal e As CustomPropertyChangedEventArgs)
If e.Name = PropertyName Then
UpdateBarItem()
End If
End Sub
Private Sub Designer_DashboardItemSelected(ByVal sender As Object, ByVal e As DevExpress.DashboardWin.ServiceModel.DashboardItemSelectedEventArgs)
UpdateBarItem()
End Sub
The code below is a complete module you need to add the Chart item’s Scale Break option:
using System;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraCharts;
namespace WindowsFormsAppCustomProperties {
public class ChartScaleBreakModule {
public static readonly string PropertyName = "ScaleBreak";
readonly DashboardDesigner designer;
BarCheckItem barItem;
public ChartScaleBreakModule(DashboardDesigner designer, SvgImage barImage = null) {
this.designer = designer;
RibbonControl ribbon = (RibbonControl)designer.MenuManager;
RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.ChartTools, DashboardRibbonPage.Design);
RibbonPageGroup group = page.GetGroupByName("Custom Properties");
if (group == null) {
group = new RibbonPageGroup("Custom Properties") { Name = "Custom Properties" };
page.Groups.Add(group);
}
barItem = CreateBarItem("Scale Break", barImage);
group.ItemLinks.Add(barItem);
barItem.ItemClick += ChangeCustomPropertyValue;
designer.DashboardItemControlUpdated += Designer_DashboardItemControlUpdated;
designer.DashboardItemSelected += Designer_DashboardItemSelected;
designer.DashboardCustomPropertyChanged += Designer_DashboardCustomPropertyChanged;
}
BarCheckItem CreateBarItem(string caption, SvgImage barImage) {
BarCheckItem barItem = new BarCheckItem();
barItem.Caption = caption;
barItem.ImageOptions.SvgImage = barImage;
return barItem;
}
void ChangeCustomPropertyValue(object sender, ItemClickEventArgs e) {
DashboardItem dashboardItem = designer.SelectedDashboardItem;
bool newValue = !Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName));
string status = newValue ? "enabled" : "disabled";
CustomPropertyHistoryItem historyItem = new CustomPropertyHistoryItem(dashboardItem, PropertyName, newValue.ToString(), $"Scale break for {dashboardItem.ComponentName} is {status}");
designer.AddToHistory(historyItem);
}
void Designer_DashboardCustomPropertyChanged(object sender, CustomPropertyChangedEventArgs e) {
if(e.Name == PropertyName)
UpdateBarItem();
}
void Designer_DashboardItemSelected(object sender, DashboardItemSelectedEventArgs e) {
UpdateBarItem();
}
void UpdateBarItem() {
if (designer.SelectedDashboardItem != null)
barItem.Checked = Convert.ToBoolean(designer.SelectedDashboardItem.CustomProperties.GetValue(PropertyName));
}
void Designer_DashboardItemControlUpdated(object sender, DashboardItemControlEventArgs e) {
if(e.ChartControl != null)
UpdateChartScaleBreaks(designer.Dashboard.Items[e.DashboardItemName], e.ChartControl.Diagram);
}
void UpdateChartScaleBreaks(DashboardItem dashboardItem, Diagram chartDiagram) {
if (chartDiagram is XYDiagram diagram){
bool scaleBreakEnabled = Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName));
diagram.SecondaryAxesY[0].AutoScaleBreaks.Enabled = scaleBreakEnabled;
}
}
}
}
Imports System
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraCharts
Namespace WindowsFormsAppCustomProperties
Public Class ChartScaleBreakModule
Public Shared ReadOnly PropertyName As String = "ScaleBreak"
Private ReadOnly designer As DashboardDesigner
Private barItem As BarCheckItem
Public Sub New(ByVal designer As DashboardDesigner, Optional ByVal barImage As SvgImage = Nothing)
Me.designer = designer
Dim ribbon As RibbonControl = CType(designer.MenuManager, RibbonControl)
Dim page As RibbonPage = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.ChartTools, DashboardRibbonPage.Design)
Dim group As RibbonPageGroup = page.GetGroupByName("Custom Properties")
If group Is Nothing Then
group = New RibbonPageGroup("Custom Properties") With {.Name = "Custom Properties"}
page.Groups.Add(group)
End If
barItem = CreateBarItem("Scale Break", barImage)
group.ItemLinks.Add(barItem)
AddHandler barItem.ItemClick, AddressOf ChangeCustomPropertyValue
AddHandler designer.DashboardItemControlUpdated, AddressOf Designer_DashboardItemControlUpdated
AddHandler designer.DashboardItemSelected, AddressOf Designer_DashboardItemSelected
AddHandler designer.DashboardCustomPropertyChanged, AddressOf Designer_DashboardCustomPropertyChanged
End Sub
Private Function CreateBarItem(ByVal caption As String, ByVal barImage As SvgImage) As BarCheckItem
Dim barItem As New BarCheckItem()
barItem.Caption = caption
barItem.ImageOptions.SvgImage = barImage
Return barItem
End Function
Private Sub ChangeCustomPropertyValue(ByVal sender As Object, ByVal e As ItemClickEventArgs)
Dim dashboardItem As DashboardItem = designer.SelectedDashboardItem
Dim newValue As Boolean = Not Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName))
Dim status As String = If(newValue, "enabled", "disabled")
Dim historyItem As New CustomPropertyHistoryItem(dashboardItem, PropertyName, newValue.ToString(), $"Scale break for {dashboardItem.ComponentName} is {status}")
designer.AddToHistory(historyItem)
End Sub
Private Sub Designer_DashboardCustomPropertyChanged(ByVal sender As Object, ByVal e As CustomPropertyChangedEventArgs)
If e.Name = PropertyName Then
UpdateBarItem()
End If
End Sub
Private Sub Designer_DashboardItemSelected(ByVal sender As Object, ByVal e As DashboardItemSelectedEventArgs)
UpdateBarItem()
End Sub
Private Sub UpdateBarItem()
If designer.SelectedDashboardItem IsNot Nothing Then
barItem.Checked = Convert.ToBoolean(designer.SelectedDashboardItem.CustomProperties.GetValue(PropertyName))
End if
End Sub
Private Sub Designer_DashboardItemControlUpdated(ByVal sender As Object, ByVal e As DashboardItemControlEventArgs)
If e.ChartControl IsNot Nothing Then
UpdateChartScaleBreaks(designer.Dashboard.Items(e.DashboardItemName), e.ChartControl.Diagram)
End If
End Sub
Private Sub UpdateChartScaleBreaks(ByVal dashboardItem As DashboardItem, ByVal chartDiagram As Diagram)
Dim tempVar As Boolean = TypeOf chartDiagram Is XYDiagram
Dim diagram As XYDiagram = If(tempVar, CType(chartDiagram, XYDiagram), Nothing)
If tempVar Then
Dim scaleBreakEnabled As Boolean = Convert.ToBoolean(dashboardItem.CustomProperties.GetValue(PropertyName))
diagram.SecondaryAxesY(0).AutoScaleBreaks.Enabled = scaleBreakEnabled
End If
End Sub
End Class
End Namespace
Register this code before you load a dashboard to apply settings. For this, create a new ChartScaleBreakModule instance and pass the Dashboard Designer for which you register a custom property. You can create the SvgImageCollection instance to store vector images and use one of them as the bar item’s icon.
using WindowsFormsAppCustomProperties;
//...
public Form1() {
InitializeComponent();
new ChartScaleBreakModule(dashboardDesigner1, svgImageCollection1["changechartseriestype"]);
dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml");
//...
}
Imports WindowsFormsAppCustomProperties
'...
Public Sub New()
InitializeComponent()
Dim TempChartScaleBreakModule As ChartScaleBreakModule = New ChartScaleBreakModule(dashboardDesigner1, svgImageCollection1("changechartseriestype"))
dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml")
'...
End Sub
After you registered the ChartScaleBreakModule module, it adds the ScaleBreak button that enables scale break for each selected Chart item in a dashboard. The information about the scale break property’s state is saved in history, so you can undo/redo the current action.
See Also