Canvas class final

Draws on a Surface: text, fills, pre-shaped runs, lines merged where they meet, and images, under a translation and a clip.

Coordinates are cells, relative to the origin translate moves; what falls outside the clip (clipRect) is not drawn, and save and restore keep and bring back both. A pen is a Pen's id in styles (StyleTable.pen): each cell drawn takes the style it makes over the cell's own. Text is segmented into clusters as the terminal shows them (segmenter), the clusters of more than one code point interned in glyphs. Every cell written is damaged on the surface, so the presenter compares only those.

A blue panel with a title, drawn in a 2-cell margin:

final styles = StyleTable();
final canvas = Canvas(Surface(40, 10), styles, GlyphTable());
final panel = styles.pen(const Pen(bg: Color.blue));
final title = styles.pen(const Pen(fg: Color.brightWhite));
canvas
  ..save()
  ..translate(2, 1)
  ..clipRect(0, 0, 36, 8)
  ..fill(0, 0, 36, 8, panel)
  ..text(1, 0, 'Status', title)
  ..restore();

See also:

Constructors

Canvas(Surface surface, StyleTable styles, GlyphTable glyphs, {TextSegmenter? segmenter})
A canvas on surface, with its origin at the surface's first cell and the whole surface as its clip.

Properties

clipBounds → (int, int, int, int)
Clip in surface coordinates: (x0, y0, x1, y1).
no setter
glyphs → GlyphTable
The clusters of more than one code point drawn, interned.
final
hashCode → int
The hash code for this object.
no setterinherited
originX → int
The column of the surface the origin is at, as translate moved it.
no setter
originY → int
The row of the surface the origin is at, as translate moved it.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
segmenter → TextSegmenter
How text is split into clusters and measured: as the terminal does.
final
styles → StyleTable
The pens the canvas paints with, and the styles the cells take.
final
surface ↔ Surface
The surface drawn on. Set to another, reset makes the clip that surface's.
getter/setter pair

Methods

clipContains(int x0, int y0, int x1, int y1) → bool
Whether the clip contains the surface rectangle [x0, x1) x [y0, y1).
clipRect(int x, int y, int w, int h) → void
Intersects the clip with the rectangle (local coordinates).
fill(int x, int y, int w, int h, int pen, [int cp = kBlank]) → void
Fills a rectangle with code point cp (default: blank) using pen. A two-column cp is laid out every other column. A cp that can't stand in a cell of its own (a control, a mark, or one a terminal would join with its neighbours) fills with blanks.
image(int x, int y, int cols, int rows, TerminalImage image) → void
Shows image in the cols x rows cells from (x, y), scaled to fill them: the cells are reserved as by reserve, and the presenter draws the image over blanks in the styles they have (a transparent image shows the background painted there first). What the clip cuts off is not shown; of a sixel or iTerm2 image then none is, its cells stay blank. The image takes the place of those it is drawn over, and goes once anything is drawn over its cells (see Surface.images): kitty's from all of them, sixel and iTerm2 pixels from those written over.
mergeRun(int x, int y, GlyphRun r, int pen, {int under = -1, int trimFirst = 0, int trimLast = 0}) → int
Draws r, pieces of line one column each, as run does, but merged with the line already in each cell: the cell gets the piece that reaches out wherever either of them does, an arm both have in the weight of the new one. Light (single and rounded), heavy and double lines keep their own weights where Unicode has a piece for the mix — light and heavy always, light and double where the arms across share a weight and so do those down; elsewhere every arm takes the weight of the new piece. The piece drawn, or the one in the cell where the new one adds nothing to it, is kept as it is: a round corner stays round. Dashed lines merge as solid ones. ASCII pieces (-, |, and +, which reaches out all four ways) merge only with each other, box drawing only with box drawing, a piece of one drawn over one of the other as run draws it. A cell that holds text (any glyph but a blank or a piece of line, a wide one whole) keeps it and its style: a line merged over the edge of a box joins its lines and leaves its titles. A glyph in r that is no piece of line is drawn as run draws it.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
reserve(int x, int y, int w, int h) → void
Hands the rectangle to something drawn outside the cell model (an inline image): its cells are marked kSkip, which the presenter never writes, erases or compares, until something is drawn over them again. Wide glyphs cut by its edges are broken up, as by fill.
reset() → void
Origin (0, 0), clip = whole surface, empty save stack.
restore() → void
Brings back the origin and the clip the last save kept.
run(int x, int y, GlyphRun r, int pen) → int
Draws a pre-shaped run; same semantics as text without segmentation, so in stored order too: user text goes through a TextPainter.
runBuffer(int x, int y, GlyphBuffer b, int pen) → int
Draws what shapeInto shaped into b, as run draws a run.
runRange(int x, int y, Uint32List g, int start, int end, int pen) → int
Draws glyph words [start, end) of g as run draws a run of them: a piece of a buffer that holds several (what a retained layout keeps for all its lines), drawn without copying it out.
runRangeStyled(int x, int y, Uint32List g, int start, int end, StyleId style) → int
Draws glyph words [start, end) of g as runStyled draws a run of them: a piece of a buffer, drawn without copying it out.
runStyled(int x, int y, GlyphRun r, StyleId style) → int
Draws r as run does, its cells taking style, a style id of styles (StyleTable.style), as they are, with no pen: for cells whose styles come whole from elsewhere (a terminal emulator's), which a pen each would keep for good.
save() → void
Keeps the origin and the clip, for restore to bring back.
shape(String s) → GlyphRun
Segments s once (for retained text layout); see run.
shapeInto(String s, GlyphBuffer out) → void
Segments s as shape does into out, replacing what it held: its words, GlyphBuffer.length and GlyphBuffer.width together, grown when s needs more room than it has. For a text that keeps its own buffer: no run and no copy per change. Draw it with runBuffer.
text(int x, int y, String s, int pen) → int
Draws s at (x, y) with pen; returns the columns it advanced (0 when the row is clipped out). Tabs draw as one blank, controls and lone combining marks are dropped.
toString() → String
A string representation of this object.
inherited
translate(int dx, int dy) → void
Moves the origin dx cells right and dy down; the clip stays where it is on the surface.

Operators

operator ==(Object other) → bool
The equality operator.
inherited