Chart Architecture

Overview

Namespace: TheTechIdea.Beep.Winform.Controls.Charts
Assembly: TheTechIdea.Beep.Winform.Controls.dll
Inheritance: BaseControl

BeepChart is a full-featured charting control supporting 5 chart types (Bar, Line, Pie, Area, Bubble) with interactive viewport control (zoom/pan/auto-scale), performance optimization for datasets exceeding 10,000 points, real-time streaming, trackball with crosshair and multi-series tooltips, and 18 events with dedicated EventArgs classes. It is decomposed across 5 partial files with ~20 helper classes organized into five subsystems.

Partial File Layout (5 Files)

Helper Subsystems (20 Classes)

Painting Pipeline

DrawContent(Graphics g)
  -> Paint(Graphics g, Rectangle bounds)
       -> IChartPainter.Initialize(owner, theme)
       -> IChartPainter.AdjustLayout(drawingRect, ctx) -> ChartLayout
            |-- IChartAxisPainter.AdjustPlotRect(g, axisCtx) -> AxisLayout (48px margins)
       -> IChartPainter.DrawBackground(g, ctx)
            |-- CardChartPainter: rounded card background + border
            |-- IChartAxisPainter.DrawAxes(g, axisCtx) -> X/Y axis lines + titles
            |-- IChartAxisPainter.DrawTicks(g, axisCtx) -> numeric | date | text
       -> [foreach DataSeries, palette index]:
            IChartSeriesPainter.DrawSeries(g, plotRect, data, toX, toY,
                xMin, xMax, yMin, yMax, palette, axisColor, textColor, options)
       -> IChartLegendPainter.DrawLegend(g, chartRect, series, palette,
            font, textColor, backColor, shapeColor, owner, onToggleSeries, ...)
       -> IChartPainter.DrawForeground(g, ctx) -> title, subtitle, value
       -> IChartPainter.UpdateHitAreas(owner, ctx, notifyAreaHit)

Painter Contracts (4 Interfaces)

IChartPainter

Top-level chart painter. Handles layout adjustment, background/foreground, and hit area registration. Concrete implementation: CardChartPainter renders charts as cards with rounded corners, title bars, and value text areas.

internal interface IChartPainter
{
    void Initialize(BaseControl owner, IBeepTheme theme);
    ChartLayout AdjustLayout(Rectangle drawingRect, ChartLayout ctx);
    void DrawBackground(Graphics g, ChartLayout ctx);
    void DrawForeground(Graphics g, ChartLayout ctx);
    void UpdateHitAreas(BaseControl owner, ChartLayout ctx,
        Action<string, Rectangle> notifyAreaHit);
}

// ChartLayout data class:
// DrawingRect, PlotRect, Radius, AccentColor, TitleBottom

IChartSeriesPainter

Responsible for rendering individual chart series (bars, lines, pie slices, etc.). Five concrete implementations returned by SeriesPainterFactory.

internal interface IChartSeriesPainter
{
    void Initialize(BaseControl owner);
    void DrawSeries(Graphics g, Rectangle plotRect,
        List<ChartDataSeries> data,
        Func<ChartDataPoint, object> toX,
        Func<ChartDataPoint, object> toY,
        float xMin, float xMax, float yMin, float yMax,
        List<Color> palette, Color axisColor, Color textColor,
        SeriesRenderOptions options);
    void UpdateHitAreas(BaseControl owner, Rectangle plotRect,
        List<ChartDataSeries> data,
        Func<ChartDataPoint, PointF> toScreen,
        Action<string, Rectangle> notifyAreaHit);
}

IChartAxisPainter

Renders coordinate axes with intelligent tick calculation. Concrete implementation: CartesianAxisPainter (internal sealed). AxisLayout data class carries Bounds, PlotRect, BottomAxisType, LeftAxisType, XMin/XMax/YMin/YMax, XTitle/YTitle, XLabelAngle/YLabelAngle, AxisColor, GridLineColor, and category/date epoch data.

IChartLegendPainter

Renders a color-coded series reference panel. Concrete implementation: RightSideLegendPainter. Supports series toggle via onToggleSeries(int) callback and LegendPlacement (Right, Bottom, Top, Left). EnableLegendIsolate enables single-series isolation mode.

Series Painters (5 Types)

SeriesPainterFactory.Get(ChartType) resolves the chart type to its painter. LineSeriesPainter is the default fallback.

Axis & Legend System

CartesianAxisPainter

Implements IChartAxisPainter. Three-phase rendering:

• AdjustPlotRect -- Adds 48px margins on all sides of the chart area
• DrawAxes -- Renders X/Y axis lines and titles (titles drawn rotated)
• DrawTicks -- Dispatches to three sub-renderers based on axis type:
  • NumericTicks -- "Nice" step sizes: 1, 2, 5, 10, 20, 50, 100, etc. No unnecessary decimal places.
  • DateTicks -- Auto-granularity: < 1h -> minutes, < 24h -> hours, < 30d -> days, < 365d -> months, >= 1y -> years
  • TextTicks -- Category-indexed labels from Dictionary<string,int> map, centered in each column

RightSideLegendPainter

Renders a compact color-coded legend on the right side. Shows colored square + series name per entry. Click toggles visibility. Hidden series crossed-out. Supports overflow scrolling. Colors from ChartDefaultSeriesColors palette.

Viewport & Performance

BeepChartViewportHelper (internal static)

BeepChartPerformanceHelper (public static)

Data Pipeline

BeepChartDataHelper (internal static)

// DetectAxisTypes(chart) -- reads first point of first series:
//   float.TryParse -> AxisType.Numeric
//   DateTime.TryParse -> AxisType.Date
//   else -> AxisType.Text (with Dictionary category map)

// ConvertXValue(chart, point) / ConvertYValue(chart, point):
//   Numeric: float.TryParse(value)
//   Date: (DateTime.Parse(value) - dateMin).TotalDays
//   Text: categoryMap[value] index

SeriesRenderOptions

Interaction & Trackball

ChartInputHelper supports:

• Trackball -- Crosshair overlay with multi-series tooltip values. Configurable colors and width.
• MouseWheelZoom -- Ctrl+Wheel zooms in/out (configurable step percent)
• MouseDragPan -- Click-drag pans the viewport (configurable factor)
• KeyboardNavigation -- Arrow keys for pan, +/- for zoom, configurable step percent
• PointHover -- DataPointToolTip on hover with point details
• PointSelection -- Click to select with visual highlight, configurable selection color/marker
• LegendIsolate -- Click legend item to isolate single series. Click again to restore all.

18 dedicated events enable full integration: CustomDrawSeries, InteractiveAreaHit, PointHit, AxisHit, LegendHit, PointHoverChanged, ViewportChanged, TrackballDataCollected, SeriesIsolationChanged, SelectionChanged, ContextMenuRequested, KeyboardFocusChanged, PerformanceOptimized, NonColorStateCommunicationChanged, LabelOptimizationApplied, StreamingDataAppended, IncrementalRenderCompleted.

Key Enums & EventArgs

18 EventArgs classes in BeepChart.Events.cs: CustomDrawSeriesEventArgs (Graphics, series index), ChartPointHitEventArgs (series, index, point, screen location), ChartAxisHitEventArgs (axis, value, label), ChartLegendHitEventArgs (series index, toggle), ChartPointHoverChangedEventArgs (old/new point), ChartViewportChangedEventArgs (xMin/xMax/yMin/yMax), ChartTrackballDataCollectedEventArgs (screen point, data points list with ChartTrackballDataPoint), ChartSelectionChangedEventArgs (selected points list), ChartPerformanceOptimizedEventArgs (before/after point counts), ChartStreamingDataAppendedEventArgs (series index, new point count), ChartIncrementalRenderCompletedEventArgs (render time).

Code Examples

Basic Bar Chart

var chart = new BeepChart();
chart.ChartType = ChartType.Bar;
chart.ChartTitle = "Quarterly Revenue";
chart.ShowLegend = true;
chart.LegendPlacement = LegendPlacement.Right;

chart.DataSeries.Add(new ChartDataSeries
{
    SeriesName = "Q1 Revenue",
    DataPoints = new List<ChartDataPoint>
    {
        new ChartDataPoint { X = "Product A", Y = "1200" },
        new ChartDataPoint { X = "Product B", Y = "800" },
        new ChartDataPoint { X = "Product C", Y = "1500" }
    }
});

Large Dataset with Performance Mode

chart.EnablePerformanceMode = true;
chart.LargeDatasetThreshold = 50000;
chart.EnablePointCulling = true;
chart.EnableVertexSimplification = true;
chart.ResetViewport();

if (BeepChartPerformanceHelper.ShouldOptimizePerformance(
    chart.GetTotalPointCount(), chart.LargeDatasetThreshold))
{
    float cost = BeepChartPerformanceHelper.EstimateRenderingCost(
        chart.GetTotalPointCount(), chart.Width);
    Console.WriteLine($"Rendering cost: {cost:P0}");
}

Real-Time Streaming

chart.EnableRealTimeStreaming = true;
chart.StreamRenderThrottleMs = 50;   // render batch interval
chart.MaxStreamPointsPerSeries = 1000; // rolling window

chart.StreamingDataAppended += (s, e) =>
    Console.WriteLine($"Stream: {e.NewPointCount} points");

chart.AppendDataPoint(0, new ChartDataPoint
    { X = DateTime.Now.ToString("o"), Y = sensorValue.ToString() });

Interactive Zoom/Pan with Trackball

chart.EnableMouseWheelZoom = true;
chart.EnableMouseDragPan = true;
chart.EnableTrackball = true;
chart.TrackballShowCrosshair = true;
chart.TrackballShowMultiSeriesValues = true;

chart.ViewportChanged += (s, e) =>
    Console.WriteLine($"Viewport: {e.XMin}-{e.XMax}, {e.YMin}-{e.YMax}");