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 onNeedFrame when something is marked; text is measured with segmenter, 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 result and adds what the tree has at x, y of the root (RenderObject.hitTest) as it was laid out last: the deepest object first, the root last. Allocates nothing once result has 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