CliSession class final

One inline twk app on a CliTerminal for the life of a Cli: stdin is single-subscription, so the interactive mode opens it the first time something needs it and keeps it until close.

The app's root is a host that mounts what is live (mount: a prompt, a progress) in the inline region, one below another, those mounted as last (progress) below the others, and commits finished output (commit) to the terminal's history above it (Static). With nothing live the region is empty. A Ctrl+C that nothing live takes ends the app, the terminal restored, and the session calls its onInterrupt.

This is the seam the prompts and progress of the package build on, and a program reaches it by Cli.session (in the interactive mode only: check Cli.mode) to show a live widget below the lines it logs. A program that has no need of it talks to its Cli: Cli.show, Cli.tasks and Cli.progress work in every mode.

Several widgets may be mounted at once, one below another. A session that isOpen no more, closed by the program or ended by a Ctrl+C, takes nothing: mount returns a CliLive that is not CliLive.isMounted and commit completes at once, both without an error; Cli.session opens a new one for the next asking. Once the Cli is closed (Cli.close, which Cli.run calls) its session ends with it and Cli.session throws a StateError. Unlike Cli.tasks and Cli.progress, mounting writes no progress report to the terminal (OSC 9;4).

Properties

binding → AppBinding
The binding of the app, for what reaches it from outside a widget.
no setter
done → Future<void>
Completes once the app has ended and the terminal is restored, with the error that ended it where one did.
no setter
hashCode → int
The hash code for this object.
no setterinherited
isOpen → bool
Whether the app still runs: neither closed nor ended by Ctrl+C or an error.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
styledUnderlines → bool
Whether the terminal shows the underline styles, as the session's probe of it found (TerminalCaps.styledUnderlines): what it declares, its environment, and its secondary device attributes, which tell Terminal.app over ssh too.
no setter

Methods

close() → Future<void>
Ends the app once what is committed is written: the region is cleared and the terminal restored. Completes once it is, with the error that ended the app where one did; calling it again waits for the same.
commit(Widget widget) → Future<void>
Commits widget to the terminal's history above the region: laid out at the terminal's width, as tall as it is there, written by the next frame. Completes once its rows are written; at once once the session has ended.
mount(Widget widget, {bool last = false}) → CliLive
Mounts widget in the region below what is live already, until CliLive.remove; what is committed meanwhile goes above it.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
suspend<T>(Future<T> run()) → Future<T>
Hands the terminal to another program while run runs and takes it back after (TwkApp.suspend): the region stays on the screen with the cursor on the line below it, raw mode off and input paused, the frames waiting, until run completes; then the region is drawn again below what the other program printed. Returns what run returns, or throws what it throws, once the terminal is back. Once the session has ended, run just runs.
toString() → String
A string representation of this object.
inherited

Operators

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

Static Methods

open(CliTerminal terminal, {ThemeData? theme, TwkStrings strings = const TwkStrings(), void onInterrupt()?, void onWarning(String message)?}) → Future<CliSession>
Opens the session on terminal's inline terminal (CliTerminal.openInline), the app's frames timed by its clock; widgets are shown under theme where there is one, else under the terminal's colors, and in the words strings. onInterrupt is called once the app has ended on a Ctrl+C nothing live took. onWarning gets what the session warns of (a list committed with items and no rows); without one it goes to log as a warning.