Chart Item - Scale Breaks

• Oct 15, 2021
• 8 minutes to read

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

Create the Custom Functionality Module

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:

• a dashboard control that you pass as a parameter when you register the module,
• a custom property’s unique name,
• event subscriptions that are used to provide custom functionality,
• a ribbon in which you add a button to edit custom property’s value.

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.

C#

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;
}

VB.NET

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

Save the Custom Property’s Value to a Dashboard

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.

C#

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);
}

VB.NET

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

Apply the Custom Property’s Value to the Underlying Control

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:

C#

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;
    }
}

VB.NET

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

Update the Bar Item

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.

C#

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();
}

VB.NET

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

Register the Custom Functionality Module

The code below is a complete module you need to add the Chart item’s Scale Break option:

C#

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;
            }
        }
    }
}

VB.NET

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.

C#

using WindowsFormsAppCustomProperties;
//...
public Form1() {
    InitializeComponent();

    new ChartScaleBreakModule(dashboardDesigner1, svgImageCollection1["changechartseriestype"]);
    dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml");
//...
}

VB.NET

Imports WindowsFormsAppCustomProperties
'...
Public Sub New()
    InitializeComponent()

    Dim TempChartScaleBreakModule As ChartScaleBreakModule = New ChartScaleBreakModule(dashboardDesigner1, svgImageCollection1("changechartseriestype"))
    dashboardDesigner1.LoadDashboard("../../Dashboard/newDashboard.xml")
'...
End Sub

Result

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.