TwkApp class final
The app on a terminal. On the alternate screen (TerminalInfo says which) the tree is laid out at the terminal's size. In the inline mode it is laid out in a region of the normal screen that starts on the line the cursor was on (the next one if text was on it) and is as tall as the root's max intrinsic height at the terminal's width, at least 1 row and at most maxInlineRows or the terminal's height: it grows as the content does, scrolling the history up into the scrollback once it reaches the bottom of the screen, and shrinks only when asked (shrinkRegion). Rows above it are never written, except by commit, which puts finished content in above it as lines of the terminal's history. A resize repaints it from scratch at the new width. When run ends the region stays on the screen with the cursor on the line below it, or with clearInlineOnExit is erased.
With a viewport the tree is laid out in that rectangle of the screen
instead, whichever screen the terminal is on (the normal one with
TerminalOptions(alternateScreen: false)), and nothing outside it is
written: no clear, no scroll of the screen, autowrap off only while
a frame draws, the cursor put back where the app found it after each
frame that hides it and when run ends, and the viewport left as it
is then (see Presenter.viewport). The part of it the screen has is
what is laid out: a resize cuts it at the screen's edges, or gives
back what an earlier one cut, and repaints it. Mouse events come
relative to it; those outside it are dropped, but the drags and the
release of a button pressed in it, which come on its nearest cell.
On output that takes plain text only (TerminalInfo.plain: a pipe, a file, CI) frames are laid out and painted as they come, but none is written: when run ends the last one is, as lines of text (styles left out, a wide glyph once, without the blanks that end a row or the blank rows that end the frame), each ending in LF; with clearInlineOnExit in the inline mode it isn't. What is committed (commit) is written as such lines as it is committed. A viewport is laid out at its own size there, and its rows are the lines, with no blanks before them to put them where it is: such output has no screen to place it on or cut it at.
A render tree on the terminal, until q is pressed:
Future<void> main() async {
final app = TwkApp(await Terminal.open());
final pen = app.screen.styles.pen(const Pen(fg: Color.green));
await app.run(RenderText('Press q to quit', pen), (event) {
if (event is KeyEvent && event.char == 'q') {
app.quit();
}
});
}
See also:
- HeadlessTerminal, a terminal in memory to run an app on in a test.
- renderToString, a render tree painted once to text, with no app.
- Screen, the frame's cells and the bytes that draw them, without a render tree.
Constructors
-
TwkApp(TerminalBackend terminal, {int maxFps = 60, int? maxInputFps, LogSink? logs, int? maxInlineRows, bool clearInlineOnExit = false, Viewport? viewport, bool? framesInRow, bool? timeline, bool? serveLogs, Stopwatch? clock, Map<
String, String> ? environment}) -
An app on
terminal, drawn at mostmaxFpsframes a second, 60 by default.factory
Properties
- clearInlineOnExit → bool
-
Inline mode: erase the region when run ends instead of leaving it
on the screen.
final
- clock → Stopwatch
-
What frames are spaced by: the gap of maxFps passes on it. By
default a started Stopwatch; a test gives one its fake clock moves.
final
-
debugNames
→ Set<
String> -
The names
TWK_DEBUGgives in environment, a comma-separated list read once when the app was made, every one of them: those the app reads (debugNamesRead) and any others, for a layer above to read.final -
environment
→ Map<
String, String> -
The environment the app's defaults were read from when it was made:
the one given to the constructor, or the process's with the
terminal's settings over it (TerminalInfo.settings). A layer above
reads its own variables from it, so that one map decides them all.
final
- framesInRow → bool
-
Each frame is written in full below the last one, for reading in a
log, instead of the bytes that draw it in place: a line naming it
(
--- frame 3 (412 bytes) ---, the bytes it took in place; cut to the width), then its rows as text (styles left out, a wide glyph once, without the blanks that end a row), each ending in CR LF; in the inline mode the rows committed with a frame come before it. The first frame starts at the top of the alternate screen, or on the normal one on the line after the cursor's (the cursor's own when it is at the start of one); the inline region is not left at the end. By default whetherTWK_DEBUG, a comma-separated list, namesframes. Never on plain output (TerminalInfo.plain), which gets the last frame only.final - hashCode → int
-
The hash code for this object.
no setterinherited
- logs → LogSink
-
Where
print, log and uncaught errors in run go instead of the screen; by default also appended to the fileTWK_LOGnames, and served fortwk logswith serveLogs.final - maxFps → int
-
The most frames a second: a frame requested sooner after the last
waits for the gap.
final
- maxInlineRows → int?
-
Inline mode: the most rows the region grows to; null for the
terminal's height (which limits it anyway).
final
- maxInputFps → int
-
The most frames a second that input asks for, never below maxFps.
final
- owner ↔ PipelineOwner
-
Lays out and paints the tree. Its debug paints are on from the start
when
TWK_DEBUGnames them:rainbow(PipelineOwner.debugRepaintRainbow),relayout(PipelineOwner.debugRelayoutHighlight). Its text order (PipelineTextOrder.textOrder) starts as the terminal needs it (TerminalInfo.bidi): visual where right-to-left text is left to the app, logical where the terminal reorders it; what is committed is laid out in the order it has then.latefinal - runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- screen ↔ Screen
-
The screen the tree is painted on: its Screen.styles make the pens
render objects paint with.
latefinal
- serveLogs → bool
-
logs is served for
twk logswhile run runs (LogSink.serve, in the project the current directory is in), and stops being served when it ends; a log that can't be served is a warning in it. By default whetherTWK_DEBUGnameslogs: unasked, an app opens no socket and writes no address file.final - stats → FrameStats
-
What the frames have cost so far.
final
- terminal → TerminalBackend
-
The terminal the app draws on and reads input from.
final
- timeline → bool
-
Each frame, and in it the build (run's
beforeLayout), layout, paint, commits (inline mode), present and what runs after it (run'safterPresent, the sliceFinalize), are slices on dart:developer's Timeline (DevTools' Performance tab). Off, the frame makes no Timeline call: the VM records its Dart stream by default, at some 150 ns a slice. By default whetherTWK_DEBUGnamestimeline.final - viewport → Viewport?
-
The rectangle of the screen the app draws in and owns, null for the
terminal's screen mode (see TwkApp).
final
Methods
-
commit(
RenderObject content) → void -
Inline mode:
contentgoes to the terminal's history, above the region, as lines of the terminal's own: never repainted, scrolled and selected by the terminal like anything printed (finished messages, a log, results). When its turn comes it is laid out at the terminal's width, as tall as its max intrinsic height there (a RenderParagraph has its lines wrapped at that width), painted, and its rows are written by the next frames, in the order of the commits and in the synchronized update of the region's frame (see Screen.commit). A frame writes at most 256 committed rows, so a burst of them holds neither input nor the region up; what is still waiting when run ends is written before the region is left. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
quit(
) → void - Ends run: no frame starts after it, and run completes once the terminal is handed back. Calling it again does nothing.
-
requestFrame(
) → void - Schedules a frame, as soon as maxFps allows; frames requested together are one.
-
run(
RenderObject root, void onEvent(InputEvent e), {void beforeLayout()?, void beforePresent()?, void afterPresent()?}) → Future< void> -
Runs until quit;
onEventreceives every input event (resizes and the terminal's default colors, ColorReport, are handled here first: either repaints everything). -
shrinkRegion(
) → void - Inline mode: the next frame sizes the region to its content even when that is less than it has. By itself it only grows, so content that comes and goes (a spinner line, a hint) doesn't make it jump.
-
suspend<
T> (Future< T> run()) → Future<T> -
Hands the terminal to another program while
runruns ($EDITOR, a pager, a shell started withProcessStartMode.inheritStdio) and takes it back whenruncompletes; returns whatrunreturns, or throws what it throws, once the terminal is back. -
suspendToShell(
) → Future< void> -
What Ctrl+Z does with terminal-generated signals on (here it is a
key): the shell the app was started from has the terminal until it
continues the app (
fg), see Terminal.stopForShell; then the app takes it back as after suspend. POSIX only: throws UnsupportedError on Windows. -
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Constants
-
debugNamesRead
→ const Set<
String> -
The names of
TWK_DEBUGthe app reads (debugNames):frames(framesInRow),timeline,logs(serveLogs),rainbowandrelayout(owner's debug paints). A layer above that reads more of them, as twk's debug aids do, takes these as known too.