devexpress/agent-skills/devexpress-winforms-charts

DevExpress WinForms Chart Control

DevExpress.XtraCharts.ChartControl is a 2D and 3D data-visualization component that supports 50+ series view types (bar, line, area, pie, financial, radar, polar, funnel, gantt, swift plot for huge datasets, etc.). The architecture is a four-level hierarchy: a ChartControl hosts a single Diagram of a specific type (XYDiagram, SimpleDiagram, GanttDiagram, RadarDiagram, PolarDiagram, SwiftPlotDiagram, or their 3D counterparts), the diagram contains a collection of Series, and each Series has a View (BarSeriesView, LineSeriesView, PieSeriesView, …) that determines its appearance. The diagram type is implicitly chosen by the first added series' view — adding a Series of ViewType.Pie produces a SimpleDiagram automatically; adding ViewType.Bar produces an XYDiagram.

Every chart concept — series, axis, label, legend, tooltip, crosshair, selection — exposes a consistent property model and a CustomDraw* event for cases the property model cannot cover. The same Series API works for bound and unbound modes: assign DataSource + ArgumentDataMember + ValueDataMembers for data binding, or Points.Add(new SeriesPoint(...)) for inline values.

When to Use This Skill

• Adding a chart to a WinForms app — pick a series view, bind data, configure axes.
• Choosing the right series view for the data shape (bar comparison vs trend line vs pie share vs financial OHLC vs radar profile vs gantt timeline).
• Configuring axes (primary + secondary; Numerical / DateTime / TimeSpan / Qualitative scale types) and their ranges.
• Formatting axis titles and labels (TextPattern with {A}/{V}/{VP} placeholders + .NET format specifiers).
• Aggregating large data sets on a DateTime axis via ScaleMode = Automatic and AggregateFunction.
• Configuring the legend — single or multiple legends, alignment, layout, per-series legend item text via LegendTextPattern.
• Enabling tooltips and the crosshair cursor; formatting their content; understanding when each one is the default.
• Enabling selection (Single, Multiple, or Extended) and choosing whether the entire series, a single point, or all points with the same argument get selected.

Prerequisites & Installation

NuGet Packages

Host Form

XtraForm is recommended for skin propagation but not required — ChartControl works on a plain Form.

Common Imports

using DevExpress.XtraCharts;
using DevExpress.Utils;                  // DefaultBoolean, BorderOptions
using DevExpress.XtraEditors;            // XtraForm host

For chart-specific repository items used in grids, also using DevExpress.XtraEditors.Repository; (RepositoryItemAnyControl to embed a chart in a grid cell).

Before You Start — Ask the Developer

If the host agent has a structured question-asking tool available, use it to ask these questions one at a time with clear options — for example, Claude Code's AskUserQuestion tool or GitHub Copilot's askQuestions tool. If no such tool is available, ask the questions directly in the chat response before generating code.

1. What shape of data, conceptually — comparison (Bar), trend over time (Line/Area), composition (Pie/Doughnut/Funnel), distribution (Histogram/BoxPlot), correlation (Scatter/Bubble), OHLC (CandleStick/Stock), schedule (Gantt), profile (Radar)?
2. 2D or 3D? 3D charts do not support tooltips, crosshair cursor, or runtime selection.
3. One series or several? Multiple series with different ranges → use secondary axes (XYDiagram only).
4. What is the argument type — number / date+time / time-span / category string? This drives ArgumentScaleType and the diagram's axis scale.
5. How large is the data set? > 100 k points → switch to `SwiftPlotDiagram` + SwiftPlotSeriesView / SwiftPointSeriesView; > 1 M points → also enable data aggregation.
6. Bound or unbound? Bound from EF/DTO/DataTable → set DataSource + ArgumentDataMember + ValueDataMembers. Unbound → series.Points.Add(new SeriesPoint(arg, value)).

Documentation & Navigation Guide

Getting Started

Refer to references/getting-started.md (.NET 8+) or references/getting-started-dotnet-fw.md (.NET Framework 4.x) When you need to: install NuGet, drop a ChartControl on a form, add a first series, run the Chart Designer, understand the element hierarchy.

Data Binding

Refer to references/data-binding.md When you need to: bind to a DataTable/IList/DataView/EF DbSet, set DataSource + DataAdapter + ArgumentDataMember + ValueDataMembers, use SeriesTemplate + SeriesDataMember to auto-create one series per category, configure financial data members (SetFinancialDataMembers), refresh data at runtime with RefreshData, swap argument/value scale types via ArgumentScaleType / ValueScaleType.

Series and Diagrams (Series View Catalog)

Refer to references/series-and-diagrams.md When you need to: pick a series view, know which *Diagram parent it lives in, look up the compatibility table, change a series view with Series.ChangeView(ViewType.X), mix series on one chart (only views from compatible diagrams can coexist).

Axes

Refer to references/axes.md When you need to: configure primary axes (XYDiagram.AxisX/AxisY); add secondary axes (XYDiagram.SecondaryAxesX/SecondaryAxesY); pick a scale type (Numerical / DateTime / TimeSpan / Qualitative); customize NumericScaleOptions / DateTimeScaleOptions / TimeSpanScaleOptions / QualitativeScaleOptions (ScaleMode, MeasureUnit, GridSpacing, GridAlignment); set ranges (WholeRange, VisualRange, Range.SetMinMaxValues); reverse, rotate, or hide axes.

Axis Titles and Labels

Refer to references/axis-titles-and-labels.md When you need to: set Axis.Title.Text + Title.Alignment + Title.DXFont; format AxisLabel.TextPattern with {A} / {V} / {VP} placeholders and .NET format specifiers; apply a custom AxisLabel.Formatter; add CustomAxisLabel callouts; handle CustomDrawAxisLabel for per-label appearance.

Data Aggregation and Summary

Refer to references/aggregation-and-summary.md When you need to: enable automatic aggregation for very large date-time data (DateTimeScaleOptions.ScaleMode = Automatic); pick an aggregate function (Average, Sum, Min, Max, Financial for OHLC, Histogram); switch between Continuous (no aggregation) and Manual modes; choose MeasureUnit and GridSpacing; understand when aggregation is the right answer vs. when to switch to SwiftPlotDiagram.

Legend

Refer to references/legend.md When you need to: position the legend (ChartControl.Legend.AlignmentHorizontal/AlignmentVertical with the *Outside variants), add additional legends to ChartControl.Legends, dock them to specific panes (Legend.DockTargetName), configure layout (Direction, MaxHorizontalPercentage/MaxVerticalPercentage, EquallySpacedItems), add a legend title (Legend.Title), format legend item text via SeriesBase.LegendTextPattern, enable check-box markers, customize fonts and colors.

Tooltips and Crosshair Cursor

Refer to references/tooltips-and-crosshair.md When you need to: understand the automatic choice (Crosshair Cursor for XYDiagram/SwiftPlotDiagram, Tooltip for everything else 2D), enable/disable each per chart and per series, format content with ToolTipPointPattern / ToolTipSeriesPattern / CrosshairLabelPattern / CrosshairAxisLabelOptions.Pattern / GroupHeaderPattern, customize position (ToolTipRelativePosition, ShowBeak), control crosshair lines/labels via CrosshairOptions, customize appearance via CustomDrawCrosshair.

Selection

Refer to references/selection.md When you need to: enable selection (ChartControl.SelectionMode = Single/Multiple/Extended/None), pick what gets selected per click (SeriesSelectionMode = Series/Point/Argument), change the mouse/keyboard binding on the diagram (((XYDiagram)chart.Diagram).SelectionOptions.MouseAction, RectangleSelectionMouseAction), respond to selection (ObjectSelected, SelectedItemsChanged, ObjectHotTracked), customize selected appearance (CustomDrawSeriesPoint + SelectionState), and clear/set selection in code (ClearSelection, SetObjectSelection, ReplaceSelectedItems).

Quick Start

using DevExpress.XtraCharts;
 
var chart = new ChartControl { Dock = DockStyle.Fill };
Controls.Add(chart);
 
// 1) Create a series
var sales = new Series("Sales 2026", ViewType.Bar);
 
// 2) Bind data
sales.DataSource = LoadMonthlySales();           // IEnumerable<MonthlySales>
sales.ArgumentDataMember = nameof(MonthlySales.Month);
sales.ValueDataMembers.AddRange(nameof(MonthlySales.Total));
sales.ArgumentScaleType = ScaleType.DateTime;
 
// 3) Add to the chart (this also picks the diagram — XYDiagram in this case)
chart.Series.Add(sales);
 
// 4) Customize the diagram
if (chart.Diagram is XYDiagram diagram) {
    diagram.AxisX.Label.TextPattern = "{A:MMM yyyy}";
    diagram.AxisY.Label.TextPattern = "{V:c0}";
    diagram.AxisY.Title.Text        = "Revenue";
    diagram.AxisY.Title.Visibility  = DefaultBoolean.True;
}
 
// 5) Chart title + legend placement
chart.Titles.Add(new ChartTitle { Text = "Monthly Revenue" });
chart.Legend.AlignmentHorizontal = LegendAlignmentHorizontal.Right;
chart.Legend.AlignmentVertical   = LegendAlignmentVertical.TopOutside;
 
// 6) Enable selection
chart.SelectionMode       = ElementSelectionMode.Single;
chart.SeriesSelectionMode = SeriesSelectionMode.Point;
chart.ObjectSelected     += (s, e) => HandleSelection(e.Object);

Key API Surface