A newer version of this page is available. Switch to the current version.

Chart Designer for End-Users

  • 6 minutes to read

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

ChartDesigner_ItemSelection

This document explains how to:

Invoke the Chart Designer

To invoke the Chart Designer, use the following code.


ChartDesigner chartDesigner = 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.

ChartDesigner-DisabledSelection

The following code demonstrates all possibilities of designer customization.

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

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.

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

}

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.

ChartDesigner-CustomOptionsTab

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

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

    }
}