Chart Designer for End-Users

• Mar 14, 2019
• 6 minutes to read

The Chart Designer allows end-users to customize chart appearance.

This document explains how to:

• Invoke the Chart Designer
• Customize the Chart Designer

Invoke the Chart Designer

To invoke the Chart Designer, use the following code.

C#

ChartDesigner chartDesigner = new ChartDesigner(chartControl);
chartDesigner.ShowDialog();

VB.NET

Dim chartDesigner As New ChartDesigner(chartControl)
chartDesigner.ShowDialog()

The code above uses the following classes and members.

Type or Member	Description
ChartDesigner	The Chart Designer.
ChartDesigner.ShowDialog	Shows the Chart Designer.

Customize the Chart Designer

The Chart Designer supports appearance configuration, e.g., the dialog caption or icon change. In addition, its behavior can be changed using events.

The following code demonstrates all possibilities of designer customization.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-customize-the-chart-designer-t462899

MainForm.cs

ChartDesigner designer = new ChartDesigner(chartControl1);
designer.AddElementMenuOptions.ShowAddSeriesMenuItem = false;
designer.AddElementMenuOptions.ShowAddSeriesTitleMenuItem = false;
designer.Caption = "Chart Designer";
designer.EnableLargeDataSetWarning = true;

designer.ChartElementHighlighting += OnChartElementHighlighting;
designer.ChartElementSelecting += OnChartElementSelecting;
designer.ChartStructureUpdating += OnChartStructureUpdating;

designer.ShowDialog();

MainForm.vb

Dim designer As New ChartDesigner(chartControl1)
designer.AddElementMenuOptions.ShowAddSeriesMenuItem = False
designer.AddElementMenuOptions.ShowAddSeriesTitleMenuItem = False
designer.Caption = "Chart Designer"
designer.EnableLargeDataSetWarning = True

AddHandler designer.ChartElementHighlighting, AddressOf OnChartElementHighlighting
AddHandler designer.ChartElementSelecting, AddressOf OnChartElementSelecting
AddHandler designer.ChartStructureUpdating, AddressOf OnChartStructureUpdating

designer.ShowDialog()

The properties and events represented in the table below allow for the configuration of the Designer.

Property or Event	Description
ChartDesigner.Caption	Specifies the caption of the Designer dialog window.
ChartDesigner.Icon	Specifies the icon of the Designer dialog window.
ChartDesigner.AvailableViewTypes	Specifies the types of series view available to show on the chart.
ChartDesigner.AddElementMenuOptions	Specifies parameters of the Add Element menu.
ChartDesigner.ChartElementHighlighting	Occurs when chart element highlighting begins. Allows preventing element highlighting.
ChartDesigner.ChartElementSelecting	Occurs when chart element selection begins. Allows you to prevent element selection or configure selected element visible editors.
ChartDesigner.ChartStructureUpdating	Occurs when chart structure changes begin. Allows you to specify elements that are editable using the Chart Structure Tree.

The following code of event handlers demonstrates how the above-mentioned events can be processed.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-customize-the-chart-designer-t462899

MainForm.cs

// The ChartStructureUpdating event allows for modifying chart model.
private void OnChartStructureUpdating(object sender, ChartStructureChangingEventArgs e) {
    e.ChartModel.Series.AllowAddChild = false;
    foreach(SeriesModel seriesModel in e.ChartModel.Series) { 
        seriesModel.AllowChangeVisibility = false;
        seriesModel.AllowRemove = false;
    }
    e.ChartModel.Legends.ShowInStructureControl = false;
}

// The ChartElementSelecting event allows for preventing element selection or
// modifying the selecting element edit controls.
private void OnChartElementSelecting(object sender, ChartElementSelectingEventArgs e) {
    if(e.ElementModel is SeriesBaseModel) {
        e.Cancel = true;
        return;
    }
    if (e.ElementModel is LegendModel) {
        e.ShowPropertiesTab = false;
        e.ShowDataTab = false;
        e.CustomOptionsControl = new CustomLegendOptionsControl(e.ElementModel); 
    }
}

// The ChartElementSelecting event allows for preventing element highlight.
private void OnChartElementHighlighting(object sender, ChartElementHighlightingEventArgs e) {
    SeriesBaseModel series = e.ElementModel as SeriesBaseModel;
    if(series == null) {
        e.Cancel = true;
        return;
    }

}

MainForm.vb

' The ChartStructureUpdating event allows for modifying chart model.
Private Sub OnChartStructureUpdating(ByVal sender As Object, ByVal e As ChartStructureChangingEventArgs)
    e.ChartModel.Series.AllowAddChild = False
    For Each seriesModel As SeriesModel In e.ChartModel.Series
        seriesModel.AllowChangeVisibility = False
        seriesModel.AllowRemove = False
    Next seriesModel
    e.ChartModel.Legends.ShowInStructureControl = False
End Sub

' The ChartElementSelecting event allows for preventing element selection or
' modifying the selecting element edit controls.
Private Sub OnChartElementSelecting(ByVal sender As Object, ByVal e As ChartElementSelectingEventArgs)
    If TypeOf e.ElementModel Is SeriesBaseModel Then
        e.Cancel = True
        Return
    End If
    If TypeOf e.ElementModel Is LegendModel Then
        e.ShowPropertiesTab = False
        e.ShowDataTab = False
        e.CustomOptionsControl = New CustomLegendOptionsControl(e.ElementModel)
    End If
End Sub

' The ChartElementSelecting event allows for preventing element highlight.
Private Sub OnChartElementHighlighting(ByVal sender As Object, ByVal e As ChartElementHighlightingEventArgs)
    Dim series As SeriesBaseModel = TryCast(e.ElementModel, SeriesBaseModel)
    If series Is Nothing Then
        e.Cancel = True
        Return
    End If

End Sub

Note that the ChartDesigner.ChartElementSelecting event allows you to specify the custom control used in the Options tab. The custom control must inherit the DevExpress.XtraCharts.Designer.CustomOptionsControl class. The image below shows the custom Legend Options tab.

The following code demonstrates how to design the Legend Options tab, which resembles the one in the image above.

Note

A complete sample project is available at https://github.com/DevExpress-Examples/how-to-customize-the-chart-designer-t462899

CustomLegendOptionsControl.cs

using DevExpress.Utils;
using DevExpress.XtraCharts;
using DevExpress.XtraCharts.Designer;
using System;
using System.Windows.Forms;

namespace CrosshairOptions {
    partial class CustomLegendOptionsControl : CustomOptionsControl {
        bool updateStarted = false;

        LegendModel LegendModel { get { return (LegendModel)this.Model; } }

        public CustomLegendOptionsControl(ChartElementModel model) : base(model) {
            InitializeComponent();
            if(!(model is LegendModel)) throw new ArgumentException("The model must have the LegendModel type.");
        }

        protected override void OnLoad(EventArgs e) {
            base.OnLoad(e);

            var horizontalAlignments = Enum.GetValues(typeof(LegendAlignmentHorizontal));
            cbeHorizontalAlignment.Properties.Items.AddRange(horizontalAlignments);
            var verticvalAlignments = Enum.GetValues(typeof(LegendAlignmentVertical));
            cbeVerticalAlignment.Properties.Items.AddRange(verticvalAlignments);

            UpdateView();
        }

        public override void OnModelUpdated() {
            UpdateView();
        }

        protected void UpdateView() {
            updateStarted = true;
            cbeHorizontalAlignment.SelectedItem = LegendModel.AlignmentHorizontal;
            cbeVerticalAlignment.SelectedItem = LegendModel.AlignmentVertical;
            ceVisible.CheckState = DefaultBooleanToCheckState(LegendModel.Visibility);
            updateStarted = false;
        }

        protected void OnVerticalAlignmentChanged(object sender, EventArgs args) {
            if(!updateStarted)
                LegendModel.AlignmentVertical = (LegendAlignmentVertical)cbeVerticalAlignment.SelectedItem;
        }

        protected void OnHorizontalAlignmentChanged(object sender, EventArgs args) {
            if(!updateStarted)
                LegendModel.AlignmentHorizontal = (LegendAlignmentHorizontal)cbeHorizontalAlignment.SelectedItem;
        }

        protected void OnVisibilityChanged(object sender, EventArgs args) {
            if(!updateStarted)
                LegendModel.Visibility = CheckStateToDefaultBoolean(ceVisible.CheckState);
        }

        protected static CheckState DefaultBooleanToCheckState(DefaultBoolean b) {
            switch(b) {
                case DefaultBoolean.Default: return CheckState.Indeterminate;
                case DefaultBoolean.False: return CheckState.Unchecked;
                case DefaultBoolean.True: return CheckState.Checked;
                default: throw new Exception("The specified DefaultBoolean value is not supported.");
            }
        }

        protected static DefaultBoolean CheckStateToDefaultBoolean(CheckState b) {
            switch(b) {
                case CheckState.Indeterminate: return DefaultBoolean.Default;
                case CheckState.Unchecked: return DefaultBoolean.False;
                case CheckState.Checked: return DefaultBoolean.True;
                default: throw new Exception("The specified CheckState value is not supported.");
            }
        }

    }
}

CustomLegendOptionsControl.vb

Imports DevExpress.Utils
Imports DevExpress.XtraCharts
Imports DevExpress.XtraCharts.Designer
Imports System
Imports System.Windows.Forms

Namespace CrosshairOptions
    Partial Friend Class CustomLegendOptionsControl
        Inherits CustomOptionsControl

        Private updateStarted As Boolean = False

        Private ReadOnly Property LegendModel() As LegendModel
            Get
                Return CType(Me.Model, LegendModel)
            End Get
        End Property

        Public Sub New(ByVal model As ChartElementModel)
            MyBase.New(model)
            InitializeComponent()
            If Not(TypeOf model Is LegendModel) Then
                Throw New ArgumentException("The model must have the LegendModel type.")
            End If
        End Sub

        Protected Overrides Sub OnLoad(ByVal e As EventArgs)
            MyBase.OnLoad(e)

            Dim horizontalAlignments = System.Enum.GetValues(GetType(LegendAlignmentHorizontal))
            cbeHorizontalAlignment.Properties.Items.AddRange(horizontalAlignments)
            Dim verticvalAlignments = System.Enum.GetValues(GetType(LegendAlignmentVertical))
            cbeVerticalAlignment.Properties.Items.AddRange(verticvalAlignments)

            UpdateView()
        End Sub

        Public Overrides Sub OnModelUpdated()
            UpdateView()
        End Sub

        Protected Sub UpdateView()
            updateStarted = True
            cbeHorizontalAlignment.SelectedItem = LegendModel.AlignmentHorizontal
            cbeVerticalAlignment.SelectedItem = LegendModel.AlignmentVertical
            ceVisible.CheckState = DefaultBooleanToCheckState(LegendModel.Visibility)
            updateStarted = False
        End Sub

        Protected Sub OnVerticalAlignmentChanged(ByVal sender As Object, ByVal args As EventArgs)
            If Not updateStarted Then
                LegendModel.AlignmentVertical = CType(cbeVerticalAlignment.SelectedItem, LegendAlignmentVertical)
            End If
        End Sub

        Protected Sub OnHorizontalAlignmentChanged(ByVal sender As Object, ByVal args As EventArgs)
            If Not updateStarted Then
                LegendModel.AlignmentHorizontal = CType(cbeHorizontalAlignment.SelectedItem, LegendAlignmentHorizontal)
            End If
        End Sub

        Protected Sub OnVisibilityChanged(ByVal sender As Object, ByVal args As EventArgs)
            If Not updateStarted Then
                LegendModel.Visibility = CheckStateToDefaultBoolean(ceVisible.CheckState)
            End If
        End Sub

        Protected Shared Function DefaultBooleanToCheckState(ByVal b As DefaultBoolean) As CheckState
            Select Case b
                Case DefaultBoolean.Default
                    Return CheckState.Indeterminate
                Case DefaultBoolean.False
                    Return CheckState.Unchecked
                Case DefaultBoolean.True
                    Return CheckState.Checked
                Case Else
                    Throw New Exception("The specified DefaultBoolean value is not supported.")
            End Select
        End Function

        Protected Shared Function CheckStateToDefaultBoolean(ByVal b As CheckState) As DefaultBoolean
            Select Case b
                Case CheckState.Indeterminate
                    Return DefaultBoolean.Default
                Case CheckState.Unchecked
                    Return DefaultBoolean.False
                Case CheckState.Checked
                    Return DefaultBoolean.True
                Case Else
                    Throw New Exception("The specified CheckState value is not supported.")
            End Select
        End Function

    End Class
End Namespace