twk 0.3.0
twk: ^0.3.0 copied to clipboard
Flutter's widget model for terminal UIs in Dart: layout, text, focus, the mouse, scrolling, editing, overlays, navigation and animation.
Changelog #
0.3.0 #
Breaking:
-
Renamed:
Was Is LocalizationsTwkLocalizationsTabViewTabBarViewWindowTitleTerminalTitleTaskStatusTaskItemStatusLinkHyperlinkMarkGlyphMarkdebugDumpTreedebugDumpAppDragDetailsDragStartDetails,DragUpdateDetails,DragEndDetailsDragListenerGestureDragStartCallback,GestureDragUpdateCallback,GestureDragEndCallbackGestureDetector:onDragStart,onDragUpdate,onDragEndonPanStart,onPanUpdate,onPanEndListener,RenderListener:onDown,onUp,onMove,onDragonPointerDown,onPointerUp,onPointerHover,onPointerMoveScrollMetrics,ScrollPosition:offset,maxOffset,viewportExtentpixels,maxScrollExtent,viewportDimensionScrollController,ListController,useScrollController:initialOffsetinitialScrollOffsetText,Text.rich,Text.line,Text.richLine:aligntextAlignStatusBar,DescriptionList:gapspacingScrollbar:hideAftertimeToFadeDragTarget:onWillAccept,onAcceptonWillAcceptWithDetails,onAcceptWithDetailsshowDialog:dismissiblebarrierDismissiblePopScope:onPopInvokedonPopInvokedWithResult -
BoxConstraints,Flex,Row,Column,WrapandTerminal: twk_core's changelog. -
TweenAnimationBuildertakes aTween:tween: IntTween(begin: 0, end: total)in place ofvalue:,from:and a constructor. ATweenof an app's own overrides the newTween.withEnds. -
Action.invokereturnsObject?andCallbackAction.onInvokeis anObject? Function(T):onInvoke: (_) {}is(_) => null. -
SemanticsandSemanticsNodetakechecked,selected,expandedandenabledin place ofstate:;SemanticsStateis removed.disabled: !xisenabled: x.Semantics.childis optional. -
ActionsandShortcutstakeactions:andshortcuts:by name.Shortcuts.combosstill takes its map first. -
showDialog,showToastandshowContextMenutakecontextby name, withbuilder,messageanditems:showDialog(context: context, builder: (context) => ...). -
GestureDetectorandPressable:onTap,onDoubleTapandonLongPressareVoidCallbacks.onTapDowntakesTapDownDetailsand the newonTapUpTapUpDetails, withlocalPositionandglobalPositionin cells (CellOffset,dxanddy) and theevent.onLongPressEndstill takes thePointerEvent. -
The drag details have
localPositionandglobalPosition, the updatedelta, and keepevent. -
log,LogLevel,LogRecordandLogSinkmoved topackage:twk/log.dart;formatBytes,formatTookandByteUnitstopackage:twk/format.dart. -
twk.dartno longer exportsModeReport,KeyboardFlagsReport,DeviceAttributes,ColorReport,CursorReportandUnknownSequence:package:twk_core/terminal.darthas them. -
The wheel goes through
ScrollBehaviorandScrollConfiguration:App(scrollBehavior:)for the app,ScrollConfigurationfor a subtree. AScrollableapplies it once a frame, dense events a cell each with an acceleration, sparse ones 3.ScrollBehavior.fixed(3)is a plain step.wheelStep,wheelAccelerationandWheelAccelerationare gone. -
Popover.onDismissis required. -
Ticker.bindingandSteps.bindingtake what they use of it, notAppBinding?; twk_test'sFakeFrameClockis one. -
Cli.currentis gone:Cli.rungives the body itsclias a parameter. -
ThemeData.pointerMode,PointerMode.off,.autoor.on, replacesThemeData.handPointer,HandPointerand thepointerShapesofWindow,SplitView,Table,TreeTableandDraggable.PointerMode.auto, the default, shows the hand in a local session and asks a terminal that shows pointer shapes for the mouse's motion (mode 1003), and for none in a remote one.TerminalStatus.handAsksMotionis the rule. -
A press on a cell a
GestureDetector'stapAtrefuses goes to the detectors around it. -
runAppwhile aClisession has the terminal throws aTerminalException:Cli.suspendaround it, orCli.closefirst.
Added:
TwkStrings, the words twk writes itself anddecimalSeparator:TwkLocalizations(strings:, child:)andTwkStrings.of(context)for widgets,Cli(strings:),Cli.runandCli.runWithArgsfor a console.formatBytes,formatTookandProgressTask.summarytakedecimalSeparator:.runAppandAppBindingtakemaxInputFps.TableandTreeTabletakemarks:, aSelectionController<Object>(multiple: true)that marks rows by key, with a checkbox column.ListView(padding:),Table(padding:)andSingleChildScrollView(padding:), which scroll with the content.Cli.session(),CliTerminal.promptShown(question).AnsiStream.reset().Text.lineandText.richLinetakealignandoverflow.MenuItem(shortcut:).copyToClipboard(context, text).RadioGroupandValueSteppertakecanRequestFocus.Pressable(behavior:), andGestureDetector'scursorandtapAt.FocusManager.autofocusPending.ValueChanged,ValueGetter,ValueSetter,kReleaseMode,kDebugMode.Style.copyWith,SizedBox.square(dimension:),DefaultTextStyle.merge(which merges onto the style above, unlike Flutter's).Focus(onFocusChange:),FocusScope(onFocusChange:),FocusScopeNode.requestFocus([node]).SingleTickerProviderStateMixin.AnimationController.forward,reverse,animateToandrepeatreturn aFuture<void>that completes when the run ends or is stopped;disposeleaves it pending.AnimationController.toggle,isCompletedandisDismissed(also onAnimationStatus).- The rest of Flutter's
Curves. Navigator.pushAndRemoveUntil,pushNamedAndRemoveUntilandpopAndPushNamed, static and onNavigatorState.Slider(onChangeStart:, onChangeEnd:).BlockSemantics(blocking:),State.reassemble,Element.reassembleandAppBinding.reassemble.
Changed:
- A
Textof eight rows or more that is edited without changing its size repaints only the rows that changed. - The pointer follows the press: a
GestureDetectorwithonTapshows the hand byThemeData.pointerMode, over all that a click presses. Rows of a list keep the arrow. - A confirmation takes the first letters of
TwkStrings.yesandnotoo.Cli.confirmsays(y/n), Tab moves the highlight, and Enter with no answer highlighted saysanswer y or n. - Esc cancels a prompt of
package:twk/cli.dart, exit 130; with suggestions open it hides them first. Cli.showof aTable,TreeTableorListViewwith items and no height warns.- A closing dialog, menu or popover gives the focus back to the node that had it,
and Escape closes the layer the focus is in. A dialog or menu opened from a
Popoverno longer dismisses it. twk shellignores and logs a frame of a type it does not know, as the VS Code extension's shell does.- A row
SelectionList.itemEnabledrefuses, in a multiple list, has a blank for its mark; a selected one keeps its[x]. - A row a
ListViewkeeps out of its window builds as it comes back. - What is dirty below a
LayoutBuildergiven a new widget waits for its build. - A key flushes an
autofocusstill waiting. - A
SelectionAreacopies a blank line where rows lie between twoTexts. GestureDetector.onTapDownis told only of a press the detector takes part in.
Fixed:
tailFilereads a look through one handle: a rename over the name loses no lines, and a look with nothing to read opens nothing.- A widget that watched a provider and later only selects is told of what it selects.
Semantics.nodeskeep their hints while theSemanticsis not focused.- A popover closes when a layer over it gives the focus elsewhere.
- A
ProgressListlays out again whenTwkStrings.etaandmoreTaskschange. - A row a
ListViewkept can be marked again before the next build.
0.2.0 #
-
After a Ctrl+C ended the inline session, a program that handles SIGINT and goes on gets a new session for its next prompt or progress. The prompt was cancelled at once with
PromptCancelReason.endOfInput, and a progress was written as lines, because stdin was taken for closed.Cli.close()still ends the console for good.FakeCliTerminalopens its inline terminal again once the last one is closed. -
Cli.suspend(run)hands the terminal to another program whilerunruns, one that reads the terminal itself (sudoasking for a password, a package manager, a pager, an editor), and takes it back after. The inline session's region stays with the cursor on the line below it, raw mode is off and the session's input paused, and the session is drawn again below what was printed. Such a program used to print in the middle of the region and never get what was typed. -
Each pipeline that draws a theme mark the terminal can't draw one column wide (
Glyphs.cursor: '日') is warned once in its own log, where only the first of the pipelines sharing a segmenter was: the verdict is kept for the segmenter, and the warning came only with measuring it. -
Cli.close()closes the terminal when the inline session failed to open, where it threw the open's error again and left the terminal open. -
A line
Clilogs or writes while its inline session is still opening (cli.inforight aftercli.progress) goes above the session once it is open. It was written to stdout while the opening session flushed it, and threw "StreamSink is bound to a stream". -
In visual order the rest of the user's text a widget paints itself reads as a
Textdraws it, each label through aTextPainterthe render object keeps: the labels of aProgressList, the messages and lines of theConsole, the labels ofGaugeandLineGauge, ofBarChartandHeatmap(their legend too), the axis titles, labels and dataset names of aChart, the labels aDotCanvas's draw function sets, the month and weekday names of aCalendarand the key labels of the entries of menus. They drewשלום עולםwhereTextdrawsםלוע םולש. A label too long is cut at its end, where it was, in the same columns. Marks, digits and box glyphs stay onCanvas.text, in stored order. -
An
OptionListrow's label too long for the row is laid out at the room it has and cut at its end with the theme's ellipsis, as aTextwithTextOverflow.ellipsisis; it was laid out at its natural width and the canvas clipped its right edge, so in visual order a right-to-left label lost its start, which is on the right. -
In visual order, where a right-to-left label is drawn as it reads, the rows of an
OptionList(its label with its marks, which are now spans of one run in the mark style and no longer split it, and its detail), the tabs of aTabBarand the titles and entries of aMenuBar's and a context menu's menus read as aTextdraws them: they drewשלום עולםwhereTextdrawsםלוע םולש. Each paints its labels through aTextPainterit keeps while the label is the same, laid out again only when it, the segmenter or the text order changes. Their cuts, widths and the columns a click finds are those of stored order, as before. -
In visual order, where a row of right-to-left text is drawn as it reads, a click finds the target drawn under it: the crumb of
Breadcrumbs, the segment ofSegmentedButton, the page ofPagination, the step ofStepper, the arrow ofValueStepper, the key of a pressableKeyHintsBar, and aChipListchip's×, which a click on the label took for it while the×was drawn on the left. They found it in a table of columns summed in stored order; they now ask the row's paragraph which text it drew there (RenderParagraph.cellAt). The hidden cursor rests on the active one where it is drawn too:ActiveItem(text: (start, end))rests it on the first cell its childTextdraws of that text, found at each layout, ascolumngives a fixed one. -
The drawn mark of a theme field is one module:
Marks(aCellMarkorTextMarkdescriptor for each mark ofGlyphs) andThemeMarks(ThemeMarks.of(context).text(Marks.close); in a render objectThemeMarks.ofObject(this, canvas.segmenter).cell(Marks.cursor, glyphs)), which keeps the one width rule (a mark is used only where it is one column and one code point, else it isGlyphs.ascii's), a cache for each segmenter and the one warning for each (field, glyph).Glyphsstays plain strings. The helperscellRune,optionalCellRune,textMark,checkboxMarks,switchMarks,radioMarks,buttonEdgeMarksandlineMark(internal, hidden from the exports) andrampOfare gone, as are the private copies of the rule in the charts, the dot grid, the skeleton, the scrollbar, the menu, the split, the window and twk_rich. Behaviour that the one rule changes:- a mark in text is checked wherever it is drawn: the close of a
Chip,CalloutandWindow, the arrows of aValueStepper, aPagination(previous,next), theseparatorandcheckof aSegmentedButton, theupanddownof aNumberInput, aSelectand aDatePicker, the kind icons of aStatusMessage, aCalloutand a toast, thecursorof a list and a file picker, theexpandedandcollapsedof anExpansionTile, thenextofBreadcrumbs, thebulletmask of aTextField, the radio brackets, and the marks of twk_rich's markdown (bullets, checkboxes, quote bar, table borders and lines) and diff; one that is two columns wide is the ASCII one, with one warning, where it was drawn as it was and shifted the row; - the dash drawn as text in a row (a
Stepper, aCallout's title, a raisedWindow's minimise) is ASCII where the line is not one column; - a
Window's focus mark with an emptycursordraws nothing, where it drew>; aSliderwith an emptytrackHorizontaldraws a blank, where it drew-, as aScrollbardoes; - a
SkeletonTheme(glyph:)or a light shade that is not one column wide is the ASCII shade.(with one warning), where the skeleton drew a blank in reverse video; LineGauge(type:)underGlyphs.ascii(lines ASCII) is ASCII, as the docs ofGlyphssaid: the ASCII theme beats a widget'sBorderType;- a
Splitand a menu keep a border type whose pieces are all one column (as the charts do), where they kept it by the terminal's ambiguous width.
- a mark in text is checked wherever it is drawn: the close of a
-
FocusNode.takesText(andFocus(takesText:)) says that a node takes the keys that are characters as text:TextFieldandTextAreasay it unless read-only.FocusManagerKeys.activeKeys, so aKeyHintsBarandshowKeyHelp, no longer list a binding of a layer above such a node on a character key (q), which the field takes, and a click on a hint cannot type it into the field; keys with Ctrl or Alt stay. -
KeyBindings(unmatched: UnmatchedKeys.replay)replays the held first keys to the nodes a key walks, past what a dialog'skeysSkipskips, where it gave them to the app's bindings between the navigator and the dialog. -
A cell's style id is a
StyleId(package:twk_core, exported by package:twk), apart from a pen id, which stays an int: the effect cell'sEffectCell.style,childStyleandunderStyleare one, and so are the style arguments of aRenderEffect'seffectCell.
Breaking:
- A
Dialogkeeps to 72 columns by default (Dialog.maxWidth), where it took the width of its child. What is wider is cut on the right, with no error; a dialog that sets its own width givesmaxWidth: null. GaugeandLineGaugeshow no percentage unlessshowPercentage: true; they showed it by default.- A
Sparklinewith fewer values than columns ends at the right edge (fromRight, true by default), where it started at the left;fromRight: falsekeeps that. Scrollbarand the bar ofBoxread the axis from the scrollable inside, as Flutter'sScrollbardoes.Scrollbar(axis:)is nullable and null by default: the outermost scrollable of either axis, where it was vertical by default. SoScrollbar()around content whose outermost scrollable is horizontal now shows that one, in a row at the bottom; to keep the column around content that scrolls both ways, giveaxis: Axis.vertical. A given axis picks that axis's scrollable, the bar to each axis of content that scrolls both. An inner scrollable of the other axis never takes the bar of an outer one.Box(scrollbar:)takes aScrollbarVisibility?, asLogViewdoes, where it took anAxis?:.always,.onScroll(the border's own line shows while the thumb is hidden) or.never; null for none. The bar is on the right side for a vertical scrollable and on the bottom for a horizontal one; the border must have that side and a bottom title cannot share it with a horizontal bar, as asserted.
New:
App, the root that puts the theme over theOverlayover the app.Glyphs, the marks widgets draw by meaning, inThemeData.glyphs, with the presetsGlyphs.unicodeandGlyphs.ascii.ThemeData.handPointer:HandPointer.off,.auto(the default) or.onfor the hand over what a click presses.AppBinding.addPostFrameCallback, called once at the end of a frame;AppBinding.pressKey, a press of a key from code, as if the terminal had sent it;AppBinding.now, the app's wall time on its clock, which a test's fake clock moves;AppBinding.startTimerandstartPeriodic, timers on the app's clock.showConfirm, a yes-or-no dialog;Dialog.trailingandDialog.scrollable;showKeyHelp, a dialog of the keys in force.Chip,ChipListandValueStepper.Text.lineandText.richLine, one line cut with an ellipsis;Button.rich;Span.tap, a click on a piece of text;Callout(borderType:, titleStyle:).KeyHintsBar.fromPairs, a bar of fixed pairs, andKeyHintsBar(pressable: true), a click on a hint presses its key.canRequestFocusonButtonandPressable, for a control of the mouse only.TickerMode, set byOffstageandVisibility, mutes the tickers below it;useInterval, a hook called every period on the app's clock.LogController.listen,addSpans, andaddOutputandfollowFile, which return aLogSource.ScrollPhysicsandNeverScrollableScrollPhysics, taken by aListView,Scrollable,SingleChildScrollViewandTreeView, which leave the wheel and the keys to what is around them.TreeView(separateRoots:, maxIndent:, gutter:, gutterWidth:).- From package:twk:
fitText,padCells,breakLines,segmenterOfandformatByteswithByteUnits, whichDirectoryTree,ProgressListandCli.taskstake asbyteUnits. 'esc'names the Escape key in a binding, as'escape'does.
0.1.0 #
The first release.
- The framework:
Widget,StatelessWidget,StatefulWidgetandState,InheritedWidget, keys andGlobalKey,LayoutBuilder,BuildContext;ChangeNotifier,ValueNotifierandListenable. runApp: fullscreen, inline below the shell's history (Staticcommits finished lines into the scrollback) or in a fixed viewport;AppBindingwith frame callbacks, notifications, the window title and hot reload throughtwk run.- Style and text:
Stylewith colors, attributes, underline colors and links;TextandText.rich, wrapping, ellipsis and bidirectional text;Themewith built-in dark and light themes, the default ones picked by the terminal's background,Theme.adaptiveto choose them andTheme.terminalfor the terminal's own colors. - Layout:
Row,Column,Flex,Stack,Grid,Wrap,Boxwith borders that merge,Padding,Align,SizedBox,SplitView. - Focus and input: the focus tree,
Focus,KeyBindings,Shortcutsand hinted keys; the mouse by hit test (Listener,MouseRegion). - Scrolling and data:
ListView,Scrollbar,Table(also over a data source),TreeView,DirectoryTree, charts, sparklines and gauges. - Editing:
TextField,TextArea,FormandFormField. - Overlays: dialogs, menus,
MenuBar,ContextMenu, toasts, tooltips,CommandPalette. - Navigation and controls:
Navigatorand routes, tabs, buttons, switches, checkboxes, radio groups, sliders,Stepper, progress bars and spinners. - Animation: tickers,
AnimationController, implicit animations. - Semantics and a screen-reader mode; debug aids: the frame overlay, the repaint rainbow, the log console, tree dumps and VM service extensions.
- Program output with ANSI sequences as styled text:
parseAnsi,AnsiStreamas it arrives, andstripAnsi. package:twk/hooks.dart, hooks in the flutter_hooks style, andpackage:twk/provider.dart, Provider's API.package:twk/cli.dart, the console of a command-line tool that is no app: messages by level, any widget printed, prompts, progress and a traceback, as a terminal, a pipe or CI takes them.- A dart2wasm build for the web.
