TAtlasPlotAxis

Create constructor

constructor Create;

Creates an automatic linear axis with grid and labels, Minimum = 0, Maximum = 1. A chart creates its two axes itself; create one only to use the scaling on its own.

ViewMin property

property ViewMin: Double read FViewMin;

Start of the visible range of the most recent cartesian render (or Prepare). A pie render leaves it unchanged. 0 before the first render.

Plot.Footnote := Format('%g to %g', [Plot.ArgumentAxis.ViewMin, Plot.ArgumentAxis.ViewMax]);

ViewMax property

property ViewMax: Double read FViewMax;

End of the visible range; see ViewMin. 1 before the first render.

Automatic property

property Automatic: Boolean read FAutomatic write SetAutomatic default True;

True: the range follows the data. False: Minimum..Maximum is shown exactly, provided Minimum is below Maximum (otherwise the data range is used). A zoom window overrides both. Switching it off on a logarithmic axis whose Minimum is zero or less raises EAtlasPlotError.

Plot.ValueAxis.Automatic := False;

Minimum property

property Minimum: Double read FMinimum write SetMinimum stored IsMinimumStored;

Start of the manual range. Used only while Automatic is False; setting it does not switch Automatic off (use SetRange). Must be finite and within 1E100, and positive on a manual logarithmic axis.

Plot.ValueAxis.Minimum := -10;

Maximum property

property Maximum: Double read FMaximum write SetMaximum stored IsMaximumStored;

End of the manual range, default 1. Used only while Automatic is False.

Plot.ValueAxis.Maximum := 40;

Logarithmic property

property Logarithmic: Boolean read FLogarithmic write SetLogarithmic default False;

Logarithmic scale with ticks at powers of ten. Points with a zero or negative coordinate on this axis are skipped, not rejected; bars and areas grow from the bottom of the view. Cannot be combined with DateTime (raises EAtlasPlotError); a manual range must have a positive Minimum. An automatic logarithmic value axis rounds to whole decades.

Plot.ValueAxis.Logarithmic := True;

DateTime property

property DateTime: Boolean read FDateTime write SetDateTime default False;

Treats values as TDateTime and chooses calendar ticks: the first of a month (every 1, 2, 3, 6, 12 or 24 months, or whole years) for long ranges, otherwise steps from one second to four weeks. Cannot be combined with Logarithmic. A date/time argument axis shows no category ticks.

Plot.ArgumentAxis.DateTime := True;

Inverted property

property Inverted: Boolean read FInverted write SetInverted default False;

Runs the axis in the opposite direction: values grow downward (leftward when Rotated), arguments run right to left (top to bottom when Rotated).

Plot.ArgumentAxis.Inverted := True;

Grid property

property Grid: Boolean read FGrid write SetGrid default True;

Draws light grid lines across the plot at each tick, also when the axis labels are hidden.

Visible property

property Visible: Boolean read FVisible write SetVisible default True;

Shows tick labels and the axis title. When False their space is given to the plot; grid lines follow Grid.

Title property

property Title: string read FTitle write SetTitle;

Axis caption: centred below a horizontal axis, reading bottom to top beside a vertical one. Empty means none.

Plot.ValueAxis.Title := 'Orders';

LabelFormat property

property LabelFormat: string read FLabelFormat write SetLabelFormat;

Mask for tick labels: a FormatFloat mask such as 0.0, #,##0 or 0"%", or a FormatDateTime mask such as dd mmm when DateTime is set. Empty chooses automatically. Not used for category ticks, which show point texts.

Plot.ValueAxis.LabelFormat := '#,##0';

OnChange event

property OnChange: TNotifyEvent read FOnChange write FOnChange;

Called after any published setting changes. The chart assigns it on its own axes to repaint; do not replace it there, use TAtlasPlot.AddChangeListener.

Assign method

procedure Assign(Source: TPersistent); override;

Copies every published setting from another axis (not the current view) and notifies the owner.

Axis.Assign(Plot.ValueAxis);

NiceStep method

class function NiceStep(const Range: Double; MaxTicks: Integer): Double; static;

The largest readable step (1, 2 or 5 times a power of ten) that divides Range into no more than MaxTicks intervals. Returns 1 for a zero, negative or non-finite range.

Total := TAtlasPlotAxis.NiceStep(100, 5); // 20

SetRange method

procedure SetRange(const AMinimum, AMaximum: Double);

Sets a manual range and switches Automatic off in one step, with one notification. The range is shown exactly, without rounding. Raises EAtlasPlotError, changing nothing, when a value is invalid, AMinimum is not below AMaximum, or the axis is logarithmic and AMinimum is zero or less.

Plot.ValueAxis.SetRange(0, 120);

Prepare method

procedure Prepare(const DataMin, DataMax: Double; MaxTicks: Integer; Expand: Boolean);

Fixes the visible range (ViewMin/ViewMax) for one render. The chart calls it while drawing with the data, manual or zoomed limits; Expand rounds outward to whole steps (to decades when logarithmic, not for date/time). An empty range is widened; on a logarithmic axis non-positive limits are replaced. On a chart's own axis the result lasts only until the next render; call it yourself only on a standalone axis.

Axis.Prepare(3, 97, 5, True);

Ticks method

function Ticks(MaxTicks: Integer): TArray<TAtlasPlotTick>;

Tick positions and labels for the prepared range, aiming at no more than MaxTicks (clamped to 2..24) intervals and never returning more than 400. Linear axes use 1/2/5 steps; logarithmic axes use powers of ten (linear steps inside a single decade); date/time axes use first-of-month ticks for long ranges and second, minute, hour, day or week steps for short ones.

Ticks := Axis.Ticks(5);

Caption method

function Caption(const Value: Double): string;

Formats Value as a tick label: with LabelFormat when set (FormatFloat, or FormatDateTime on a date/time axis); otherwise with just enough decimals for the current step, in 0.###E+0 notation for magnitudes of 1E7 and more or steps below 1E-5, and on date/time axes as yyyy, mmm yyyy, the short date, hh:nn or hh:nn:ss by step. The automatic decimals and date masks follow the step chosen by the latest Ticks call, so on a chart's axis it formats values like the labels of the most recent render.

Caption := Plot.ValueAxis.Caption(Val);

CanShow method

function CanShow(const Value: Double): Boolean;

False for zero and negative values on a logarithmic axis; True otherwise.

Fraction method

function Fraction(const Value: Double): Double;

Position of Value in the prepared range: 0 at ViewMin, 1 at ViewMax, before inversion. Clamped to -10..11; non-positive values on a logarithmic axis give -10.

ValueAt method

function ValueAt(const AFraction: Double): Double;

The inverse of Fraction: the value at a position of the prepared range.

Manual, logarithmic and date axes

Typical axis settings on a chart.

uses
  Atlas.Plot;

procedure ConfigureAxes(Plot: TAtlasPlot; LogScale: Boolean);
begin
  // Dates along the argument axis, with a custom label mask and no vertical grid.
  Plot.ArgumentAxis.DateTime := True;
  Plot.ArgumentAxis.LabelFormat := 'dd mmm';
  Plot.ArgumentAxis.Grid := False;
  Plot.ValueAxis.Title := 'Load';
  if LogScale then
  begin
    Plot.ValueAxis.Automatic := True;
    Plot.ValueAxis.Logarithmic := True;   // decades: 1, 10, 100, ...
  end
  else
  begin
    Plot.ValueAxis.Logarithmic := False;
    Plot.ValueAxis.SetRange(0, 120);      // exact range, Automatic becomes False
    Plot.ValueAxis.LabelFormat := '0"%"';
  end;
end;

Use the scaling without a chart

A standalone logarithmic axis mapping values to positions.

uses
  System.SysUtils, Atlas.PlotAxis;

function LogPositions: string;
var
  Axis: TAtlasPlotAxis;
begin
  Axis := TAtlasPlotAxis.Create;
  try
    Axis.Logarithmic := True;
    Axis.Prepare(3, 800, 5, True); // rounded to the decades 1..1000
    Result := Format('%g..%g, 10 at %.3f, 100 at %.3f, %d ticks',
      [Axis.ViewMin, Axis.ViewMax, Axis.Fraction(10), Axis.Fraction(100), Length(Axis.Ticks(5))]);
    // 1..1000, 10 at 0.333, 100 at 0.667, 4 ticks
  finally
    Axis.Free;
  end;
end;