PipelineOwner class final
Lays out and paints a tree of RenderObjects from its root, a frame at a time: what was marked since the last frame, and nothing else.
A frame is flushLayout at the screen size, then flushPaint onto the screen's canvas, whose surface the presenter then turns into bytes. RenderObject.markNeedsLayout and RenderObject.markNeedsPaint queue work here and call onNeedFrame, which schedules the next frame; hasWork says whether there is any. hitTest finds the objects at a cell, and onError hears what an object's layout or paint throws.
A tree on a screen, one frame:
final screen = Screen(20, 1);
final pen = screen.styles.pen(const Pen());
final owner = PipelineOwner(() {}, segmenter: screen.canvas.segmenter)
..root = RenderText('Hello', pen);
final ctx = PaintContext(screen.canvas, screen.surface, screen.presenter);
owner
..flushLayout(20, 1)
..flushPaint(ctx);
final bytes = screen.render(); // what to write to the terminal
See also:
TwkApp, which owns one and runs its frames in a terminal.renderToString, one frame of a tree as text.
- Available extensions
Constructors
- PipelineOwner(void onNeedFrame(), {TextSegmenter? segmenter})
-
An owner with no root yet, which calls
onNeedFramewhen something is marked; text is measured withsegmenter, a TextSegmenter of its own when left out.
Properties
- debugRelayoutHighlight ↔ bool
-
Each repaint outlines the objects in what it covered that were laid
out since the last one: the background of the cells along their
edges, where they are painted, blended with the tint of that frame,
the next of a cycle of its own on each frame that lays anything out.
An outline stays until its cells are repainted. Off by default;
turned on or off, everything is repainted, and on, nothing laid out
before is outlined. Meanwhile a boundary repaints all of its cells,
as under debugRepaintRainbow.
getter/setter pair
- debugRepaintRainbow ↔ bool
-
Each repaint of a repaint boundary, or of the root on its own, blends
the next tint of a cycle over the background of the cells it covered
(its bounds, cut off where its ancestors cut it off), keeping their
glyphs, text colours and attributes: what repaints changes colour,
what keeps its colour did not repaint. Meanwhile a boundary repaints
all of its cells (RenderObject.invalidatePaintCache), so that none
is tinted twice. Off by default; turned on or off, everything is
repainted.
getter/setter pair
- dirtyBoundaries → int
-
How many repaint boundaries, the root among them, are marked for
paint: the next flushPaint repaints each, on its own or with one
marked around it.
no setter
- hashCode → int
-
The hash code for this object.
no setterinherited
- hasWork → bool
-
Whether the next frame has anything to lay out or paint: the root at
a new size or not laid out yet, a relayout boundary marked for
layout, or a repaint boundary marked for paint.
no setter
- onError ↔ void Function(RenderObject object, RenderPhase phase, Object error, StackTrace stack)?
-
Reports an exception a render object threw, and in which phase; the
object shows it in its place (see RenderObject), and is not
reported again while it throws the same one. Unset, the first such
exception of a flushLayout or flushPaint is thrown once the flush
has ended, and one thrown outside a flush is thrown right away.
getter/setter pair
- onLog ↔ void Function(LogRecord record)?
-
Where the tree's own warnings go, such as a RenderFlex whose
children overflow it (in debug): the sink of the app or of the tool
that lays the tree out. Unset, they go to log.
getter/setter pair
- onNeedFrame → void Function()
-
Called each time a render object is marked for layout or paint, and
when root is set: the next frame has work to do. Called again for
each mark, so it schedules a frame, not runs one.
final
- root ↔ RenderObject
-
The tree's root, laid out at the size flushLayout is given; set
before the first frame.
getter/setter pair
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- segmenter → TextSegmenter
-
What layout measures text with: the segmenter of the canvas the tree
is painted with (
screen.canvas.segmenter), so that text is given the columns it is drawn in.final - textOrder ↔ TextOrder
-
Available on PipelineOwner, provided by the PipelineTextOrder extension
The order this owner's tree draws text in: TextOrder.logical until set. Set to another, the tree is laid out and painted again.getter/setter pair
Methods
-
flushLayout(
int w, int h) → void - Lays the root out at the screen size when that is new, then the relayout boundaries marked since, outermost first; a boundary an ancestor laid out on the way is skipped. Then, the same way, those that layout callbacks marked meanwhile, until none is marked: what it paints next has all been laid out. Allocation-free once warmed up, like flushPaint.
-
flushPaint(
PaintContext ctx) → void - Repaints dirty boundaries, outermost first; boundaries inside a dirty boundary, or inside an object that shows an error, are covered by it. A boundary repaints the rows of the objects marked for paint in it (RenderObject.markNeedsPaint), as they are laid out now, and those of the boundaries inside it it covers: all of them when it was marked itself, laid out, or under a debug paint. First the objects RenderObject.checkedBeforePaint mark what they need repainted (RenderObject.beforePaint). Allocation-free once warmed up: the lists are reused and "covered" is a generation mark on the objects.
-
hitTest(
HitTestResult result, int x, int y) → void -
Empties
resultand adds what the tree has atx,yof the root (RenderObject.hitTest) as it was laid out last: the deepest object first, the root last. Allocates nothing onceresulthas held as many objects as the tree is deep. -
markAllDirty(
) → void - Marks the whole tree to be repainted, and the root to be laid out: for when nothing painted before is on the surface any more (the screen resized, the terminal's contents lost).
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited