yousefulSOFTWARE

YOUSEFUL / DELPHI / COMPONENTS

All Atlas Plot components · Atlas Plot guide

TAtlasPlotSurface

Abstract drawing target that TAtlasPlot.Render draws through: pen, brush, font, lines, shapes, text and clipping.

Class Unit Atlas.PlotSurface · Inherits TObject · Product Atlas Plot

Description

All Atlas Plot output (screen, bitmap, metafile, printer and SVG) is drawn through this small interface, so every target shares one layout. Two implementations come with the product: TAtlasCanvasSurface for any VCL canvas and TAtlasSvgSurface for SVG text. Derive from it to draw somewhere else (a PDF writer, a test recorder) and pass the object to TAtlasPlot.Render. Atlas Fin, Atlas Plot Pro and Atlas Virtual Grid use this unit for their own drawing and exports.

The unit also provides helper routines:

pascal
function AtlasFitText(Surface: TAtlasPlotSurface; const Value: string; MaxWidth: Integer): string;
function AtlasBlend(Color, Other: TColor; const OtherShare: Double): TColor;
procedure AtlasExportImage(const FileName: string; Width, Height: Integer; const Render: TAtlasRenderProc);
procedure AtlasSaveText(const FileName, Text: string);

AtlasFitText shortens text with "..." to fit a width in the surface's current font. AtlasBlend mixes OtherShare (0..1) of Other into Color. AtlasExportImage renders into a .png, .bmp, .emf or .svg file through a callback (see TAtlasRenderProc); AtlasSaveText writes UTF-8 without BOM. Both write <name>.part and rename it, so a failed export keeps the previous file.

Members

MemberKindWhat it does
UsePenmethodSelects the stroke for following lines, polylines and outlines.
UseBrushmethodSelects the fill for following polygons, boxes and circles; clNone means hollow.
UseFontmethodSelects the font for following text and TextSize, optionally bold (the chart title).
LinemethodStrokes a line with the current pen.
PolylinemethodStrokes connected segments; fewer than two points draw nothing in the supplied surfaces.
PolygonmethodFills with the brush and outlines with the pen (areas, pie slices).
BoxmethodFilled and outlined rectangle (background, bars, legend swatches).
CirclemethodFilled and outlined circle (point dots).
TextmethodDraws one line of text in the font colour without a background.
TextUpmethodDraws text reading bottom to top (vertical axis titles).
TextSizemethodWidth and height of Value in the current font.
BeginClipmethodRestricts drawing to Bounds until EndClip (the series inside the plot area).
EndClipmethodEnds the clip started by BeginClip.

Methods

UsePen method

procedure UsePen(Color: TColor; Width: Integer = 1; Dashed: Boolean = False); virtual; abstract;

Selects the stroke for following lines, polylines and outlines.

UseBrush method

procedure UseBrush(Color: TColor); virtual; abstract;

Selects the fill for following polygons, boxes and circles; clNone means hollow.

UseFont method

procedure UseFont(Source: TFont; Bold: Boolean = False); virtual; abstract;

Selects the font for following text and TextSize, optionally bold (the chart title).

Line method

procedure Line(X1, Y1, X2, Y2: Integer); virtual; abstract;

Strokes a line with the current pen.

Polyline method

procedure Polyline(const Points: TArray<TPoint>); virtual; abstract;

Strokes connected segments; fewer than two points draw nothing in the supplied surfaces.

Polygon method

procedure Polygon(const Points: TArray<TPoint>); virtual; abstract;

Fills with the brush and outlines with the pen (areas, pie slices).

Box method

procedure Box(const Bounds: TRect); virtual; abstract;

Filled and outlined rectangle (background, bars, legend swatches).

Circle method

procedure Circle(X, Y, Radius: Integer); virtual; abstract;

Filled and outlined circle (point dots).

Text method

procedure Text(X, Y: Integer; const Value: string; Align: TAlignment = taLeftJustify); virtual; abstract;

Draws one line of text in the font colour without a background. Y is the top of the text; X is its left edge, centre or right edge according to Align.

TextUp method

procedure TextUp(X, Y: Integer; const Value: string); virtual; abstract;

Draws text reading bottom to top (vertical axis titles). X is its left edge, Y its vertical centre.

TextSize method

function TextSize(const Value: string): TSize; virtual; abstract;

Width and height of Value in the current font. The layout derives every spacing from TextSize('Ag').cy.

BeginClip method

procedure BeginClip(const Bounds: TRect); virtual; abstract;

Restricts drawing to Bounds until EndClip (the series inside the plot area).

EndClip method

procedure EndClip; virtual; abstract;

Ends the clip started by BeginClip.

Examples

Collect every text the chart draws

A minimal surface that records text instead of drawing, for example to check labels in a unit test. Measuring still needs a real font, so it keeps a 1 x 1 bitmap.

pascal
uses
  System.Types, System.Classes, Vcl.Graphics, Atlas.Plot, Atlas.PlotSurface;

type
  TTextCollector = class(TAtlasPlotSurface)
  private
    FMeasure: Vcl.Graphics.TBitmap;
    FTexts: TStringList;
  public
    constructor Create;
    destructor Destroy; override;
    procedure UsePen(Color: TColor; Width: Integer = 1; Dashed: Boolean = False); override;
    procedure UseBrush(Color: TColor); override;
    procedure UseFont(Source: TFont; Bold: Boolean = False); override;
    procedure Line(X1, Y1, X2, Y2: Integer); override;
    procedure Polyline(const Points: TArray<TPoint>); override;
    procedure Polygon(const Points: TArray<TPoint>); override;
    procedure Box(const Bounds: TRect); override;
    procedure Circle(X, Y, Radius: Integer); override;
    procedure Text(X, Y: Integer; const Value: string; Align: TAlignment = taLeftJustify); override;
    procedure TextUp(X, Y: Integer; const Value: string); override;
    function TextSize(const Value: string): TSize; override;
    procedure BeginClip(const Bounds: TRect); override;
    procedure EndClip; override;
    property Texts: TStringList read FTexts;
  end;

constructor TTextCollector.Create;
begin
  inherited Create;
  FMeasure := Vcl.Graphics.TBitmap.Create;
  FMeasure.SetSize(1, 1);
  FTexts := TStringList.Create;
end;

destructor TTextCollector.Destroy;
begin
  FTexts.Free;
  FMeasure.Free;
  inherited;
end;

procedure TTextCollector.UsePen(Color: TColor; Width: Integer; Dashed: Boolean);
begin
end;

procedure TTextCollector.UseBrush(Color: TColor);
begin
end;

procedure TTextCollector.UseFont(Source: TFont; Bold: Boolean);
begin
  FMeasure.Canvas.Font.Assign(Source);
end;

procedure TTextCollector.Line(X1, Y1, X2, Y2: Integer);
begin
end;

procedure TTextCollector.Polyline(const Points: TArray<TPoint>);
begin
end;

procedure TTextCollector.Polygon(const Points: TArray<TPoint>);
begin
end;

procedure TTextCollector.Box(const Bounds: TRect);
begin
end;

procedure TTextCollector.Circle(X, Y, Radius: Integer);
begin
end;

procedure TTextCollector.Text(X, Y: Integer; const Value: string; Align: TAlignment);
begin
  FTexts.Add(Value);
end;

procedure TTextCollector.TextUp(X, Y: Integer; const Value: string);
begin
  FTexts.Add(Value);
end;

function TTextCollector.TextSize(const Value: string): TSize;
begin
  Result := FMeasure.Canvas.TextExtent(Value);
end;

procedure TTextCollector.BeginClip(const Bounds: TRect);
begin
end;

procedure TTextCollector.EndClip;
begin
end;

function ChartTexts(Plot: TAtlasPlot): string;
var
  Collector: TTextCollector;
begin
  Collector := TTextCollector.Create;
  try
    Plot.Render(Collector, Rect(0, 0, 640, 400));
    Result := Collector.Texts.CommaText; // title, tick labels, legend, marks
  finally
    Collector.Free;
  end;
end;

TAtlasCanvasSurface · TAtlasSvgSurface · TAtlasRenderProc · TAtlasPlot

Also in Atlas Plot

TAtlasPlot