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:
- Screen.canvas, the canvas of a screen.
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) usingpen. A two-columncpis laid out every other column. Acpthat 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
imagein thecolsxrowscells 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 inrthat 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
gas 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
gas 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
ras run does, its cells takingstyle, 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
sonce (for retained text layout); see run. -
shapeInto(
String s, GlyphBuffer out) → void -
Segments
sas shape does intoout, replacing what it held: its words, GlyphBuffer.length and GlyphBuffer.width together, grown whensneeds 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
sat (x, y) withpen; 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
dxcells right anddydown; the clip stays where it is on the surface.
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited