TAtlasPlotSeries

Create constructor

constructor Create(Collection: TCollection); override;

Creates an empty line series (Kind = pkLine, Color = clDefault, Visible, LineWidth = 2) in Collection. Normally you call TAtlasPlot.AddSeries or Plot.Series.Add instead.

Destroy destructor

destructor Destroy; override;

Removes the series from its chart and frees its points. Plot.Series.Delete(Index) does the same by index.

Count property

property Count: Integer read GetCount;

Number of stored points, gaps included.

Points property

property Points[Index: Integer]: TAtlasPlotPoint read GetPoint; default;

Point Index (0-based) as a TAtlasPlotPoint copy. Default property, so Sales[I] works.

P := Sales[0];

Title property

property Title: string read FTitle write SetTitle;

Name shown in the legend and in CSV output, used by Series.Find and as the base of trend and average titles.

Kind property

property Kind: TAtlasPlotKind read FKind write SetKind default pkLine;

How the series is drawn; see TAtlasPlotKind. Changing to pkPie raises EAtlasPlotError while the series holds a negative value.

Sales.Kind := pkArea;

Color property

property Color: TColor read FColor write SetColor default clDefault;

Colour of lines, bars, dots and area fills (mixed with the background). clDefault takes a palette colour by series position; see TAtlasPlot.SeriesColor.

Sales.Color := clNavy;

Visible property

property Visible: Boolean read FVisible write SetVisible default True;

Hidden series are left out of drawing, the legend, the axis ranges, stacking and hit testing. Hiding the first series can change the chart form, because the first visible series decides between pie and cartesian.

Forecast.Visible := False;

ShowPoints property

property ShowPoints: Boolean read FShowPoints write SetShowPoints default False;

Draws a dot at every vertex of a line, step or area series. Point series always draw dots; bars and pies ignore it.

Sales.ShowPoints := True;

LineWidth property

property LineWidth: Integer read FLineWidth write SetLineWidth default 2;

Pen width in pixels of lines, steps and area outlines, clamped to 1..12. Dots have a radius of LineWidth + 1, at least 3.

Sales.LineWidth := 3;

Marks property

property Marks: TAtlasPlotMarks read FMarks write SetMarks default pmNone;

Label drawn at each point; see TAtlasPlotMarks.

Sales.Marks := pmValue;

Assign method

procedure Assign(Source: TPersistent); override;

Copies title, kind, colour, visibility, point display, line width, marks and every point from another series.

Backup.Assign(Sales);

Add method

function Add(const X, Y: Double; const Text: string = ''; Color: TColor = clDefault): Integer;

Appends a point and returns its index. Points are kept in the order added (see SortByX). Text labels the point (category tick, pmText mark, pie legend); Color overrides the fill of this point. Raises EAtlasPlotError, adding nothing, when X or Y is NaN, infinite or beyond 1E100, or when a pie value is negative.

Sales.Add(EncodeDate(2026, 3, 1), 120);
Sales.Add(2, 35, 'South', clRed);

AddY method

function AddY(const Y: Double; const Text: string = ''; Color: TColor = clDefault): Integer;

Appends a point whose argument is the next whole number: 0 for the first point, otherwise Int(X of the last point) + 1. The usual way to build category charts. Same validation as Add.

Sales.AddY(42, 'North');
Sales.AddY(35, 'South');

AddNull method

function AddNull(const X: Double): Integer;

Appends a gap at argument X and returns its index. Lines and areas break at a gap, bars skip it, statistics, marks and stacking ignore it; it still counts in Count and moves AddY on. Raises EAtlasPlotError when X is invalid.

Sales.AddNull(3);

SetY method

procedure SetY(Index: Integer; const Y: Double);

Replaces the value of point Index; a gap becomes a normal point. Same validation as Add; an index out of range raises EArgumentOutOfRangeException.

Sales.SetY(0, 44);

Delete method

procedure Delete(Index: Integer);

Removes point Index.

Sales.Delete(Sales.Count - 1);

Clear method

procedure Clear;

Removes every point; the series itself and its settings stay.

Sales.Clear;

SortByX method

procedure SortByX;

Sorts the points by argument. The sort is stable: points with equal arguments keep their order. Call it after adding points out of order, since lines join points in stored order.

Sales.SortByX;

ValueCount method

function ValueCount: Integer;

Number of points that are not gaps.

if Sales.ValueCount >= 2 then Plot.AddTrendLine(Sales);

MinY method

function MinY: Double;

Smallest value, ignoring gaps. Raises EAtlasPlotError when the series has no values.

MaxY method

function MaxY: Double;

Largest value, ignoring gaps. Raises EAtlasPlotError when the series has no values.

SumY method

function SumY: Double;

Sum of the values, ignoring gaps; 0 for an empty series.

MeanY method

function MeanY: Double;

Mean of the values, ignoring gaps. Raises EAtlasPlotError when the series has no values.

Average := Sales.MeanY;

Gaps, late values and statistics

A sensor series with a missing reading that arrives later, and a footnote summarising the values.

uses
  System.SysUtils, Atlas.Plot, Atlas.PlotSeries;

procedure ShowReadings(Plot: TAtlasPlot);
var
  Readings: TAtlasPlotSeries;
begin
  Readings := Plot.AddSeries('Sensor', pkLine);
  Readings.ShowPoints := True;
  Readings.Add(0, 20.5);
  Readings.Add(1, 21.0);
  Readings.AddNull(2);        // no reading yet: the line breaks here
  Readings.Add(3, 22.4);
  Readings.Add(1.5, 20.8);    // added out of order
  Readings.SortByX;           // now 0, 1, 1.5, 2, 3
  Readings.SetY(3, 21.7);     // the reading for 2 arrived: the gap becomes a value
  Plot.Footnote := Format('%d readings, mean %.1f, range %.1f to %.1f',
    [Readings.ValueCount, Readings.MeanY, Readings.MinY, Readings.MaxY]);
end;