Skip to content

[Prototype, not for merge] Bottom toolbar drawn by Textual instead of prompt-toolkit - #1816

Draft
tleonhardt wants to merge 9 commits into
mainfrom
textual_toolbar_prototype
Draft

tleonhardt wants to merge 9 commits into
mainfrom
textual_toolbar_prototype

Conversation

@tleonhardt

@tleonhardt tleonhardt commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Not for merging

This is a prototype of a third way to keep the bottom toolbar on the screen while a command runs (#1743). It is here so the three approaches can be compared in one place. I do not intend to merge it, and will close it once #1743 is settled.

#1817 adds the same idea to main as a self-contained example, with nothing under cmd2/ changed and without the scrollback. This PR is the fuller version: inside cmd2 behind one function call, with a scrollback in the emulator, tests, and the measurements below.

#1745 Reserved rows (reserved_row_toolbar, #1815) This prototype
Who draws the toolbar prompt-toolkit prompt-toolkit, in rows held back with a scroll region a Textual application around cmd2
Flicker some none none
The terminal's own scrollback kept kept not used at all
Windows yes yes no
Dependencies added none none textual, textual-tty (and its bittty)
Code added to the cmd2 package about 700 lines about 6,300 lines about 500 lines, 110 of them the scrollback below
Resizing during a command mild the hard part nothing to get wrong

How it works

cmd2 does not draw the toolbar at all.

  • cmd2.textual_toolbar.run(MyApp) replaces MyApp().cmdloop(). In the program the user started, it starts a small Textual application, the host, which owns the terminal: textual-tty's terminal emulator widget with a toolbar widget docked below it.
  • The host runs the same program again inside the emulator. There, run() builds the cmd2 application and runs its command loop, so the application is only created in the process which uses it. It is an ordinary cmd2 application using prompt-toolkit, which is given no toolbar to draw.
  • A thread in that process sends the content of get_bottom_toolbar() to the host over a Unix socket, each refresh interval and at once when a command starts or ends. So it keeps coming while a command has the main thread. A socket, where examples/textual_tty_embed.py uses the window title, because a thread writing escape sequences into the terminal's stream would interleave with command output.
  • Command output cannot reach the toolbar's rows, because they belong to a different widget, and Textual redraws only what changed.

Without textual and textual-tty, on Windows, or when stdin or stdout is not a terminal, run() runs the application as it always did.

Try it with uv run examples/textual_toolbar.py, and --plain for today's behavior.

What was measured

In real terminals, each typed into, resized and read back by a driver: iTerm2 3.7.7, Terminal.app and tmux 3.8 on macOS; tmux 3.3a and xterm 379 on Linux.

  • A 22-check scenario (toolbar at the prompt and during a command, resizes while a command prints, the pager, read_input(), tab completion, Ctrl-C, the exit code) passes in iTerm2, both tmux and xterm. Terminal.app passes 20; one of the other two is a check its scripting cannot do, and the other was one early sample I did not chase.
  • The toolbar was on the bottom row in 76 of 76 intermediate screens while a command printed 20 lines a second, and its row was rewritten only when its text changed.
  • 20,000 lines of output take 0.5 s to print and are on the screen within a second.
  • Starting up takes 0.31 s to the first prompt, against 0.11 s without the host. Idle, the host uses about 2% of a core and 63 MB, beside the application's own 50 MB.
  • A toolbar of two rows works, and takes a row from the program's screen.

What it gives up

  • The terminal's own scrollback. Textual uses the alternate screen, so nothing of the session is in the terminal's scrollback, during it or afterwards.
  • Windows. textual-tty can only start a program by name there, without arguments.
  • Ctrl-Z does nothing: the application has no shell to return to inside the emulator. Ctrl-Q ends the host at once.
  • The mouse is Textual's, so the terminal's own text selection needs its modifier key.
  • Two young dependencies, textual-tty 0.4.0 and bittty 0.1.4, and every byte of output goes through a second terminal emulator.
  • The program starts twice. run() keeps the application's construction to the inner process, but code at module level runs in both.

Scrollback inside the emulator (second commit)

textual-tty's widget keeps no scrollback: a row which scrolls off the top is gone. Its only open issue asks for one. The second commit adds it in the host, as a subclass of the widget:

  • Rows are kept as they leave the top of the program's primary screen, ten thousand of them. The emulator scrolls in one place, which is where they are taken.
  • The mouse wheel moves the view, and so do Shift with Page Up, Page Down, Home and End where the real terminal passes those on. Typing returns to the bottom, the view holds still while output goes on below, and the toolbar says how far back it is.
  • When the window is made shorter, the rows above the cursor go to the scrollback. The emulator cuts rows off the bottom, the cursor's among them.

A 25-check scenario for it passes in iTerm2, both tmux and xterm: all 200 rows of a command are reachable, cmd2's pager (less -RXF, which stays on the primary screen) leaves its rows there as in any terminal, a full-screen less does not, and keeping the rows costs nothing measurable.

Not done: selecting text while looking back, rewrapping kept rows when the width changes, clearing them when the program asks, a scrollbar. And it works by reaching into parts of bittty and textual-tty which are not public, so an upgrade of either could break it. bittty 0.3 has begun a scrollback of its own which textual-tty, pinned below 0.2, does not use yet. The proper home for this is upstream.

What is in the diff

  • cmd2/textual_toolbar.py: the launcher, the reporter which runs in the cmd2 application, the host, and the scrollback widget. Textual is imported only when a host is started.
  • cmd2/cmd2.py: one condition, so that prompt-toolkit draws no toolbar when hosted.
  • examples/textual_toolbar.py: an application to try it with.
  • tests/test_textual_toolbar.py: 22 tests, of which those needing the host are skipped on Windows.

make check, make test and make docs-test pass locally on macOS. No changelog entry, since it is not for release.

In CI everything passes except the two coverage checks: the new module is 88% covered, and the rest of it only runs in a real terminal. A third commit makes the module type-check where Textual is not installed, as in CI's type-check jobs, by importing it by name at run time.

…lkit

A third way to keep the bottom toolbar on the screen while a command runs
(#1743), to compare with the two which have prompt-toolkit draw it. Not for
merging as it is.

Here cmd2 does not draw the toolbar at all. textual_toolbar.run() starts a
small Textual application which owns the real terminal: a terminal emulator
widget (textual-tty's Terminal) with a toolbar widget docked below it. The
cmd2 application runs inside the emulator as a child process, the same
program run again, and sends the content of get_bottom_toolbar() to the host
over a Unix socket from a thread, so it keeps coming while a command has the
main thread. Command output cannot reach the toolbar's rows, because they
belong to a different widget.

- cmd2/textual_toolbar.py: the launcher, the reporter which runs in the cmd2
  application, and the host. Textual is imported only when a host is started.
- cmd2.py: one condition, so prompt-toolkit draws no toolbar when hosted.
- examples/textual_toolbar.py: an application to try it with.

Without textual and textual-tty, on Windows, or when stdin or stdout is not
a terminal, run() runs the application as it always did.

What it gives up, as it stands: the pane has no scrollback, the session
leaves nothing in the terminal's own scrollback, Ctrl-Z does nothing, and it
does not run on Windows.
The session runs on the alternate screen of the real terminal, so none of
it reaches that terminal's scrollback, and textual-tty's Terminal widget
keeps none of its own: a row which scrolled off the top was gone.

The host now uses a subclass of that widget which keeps the rows as they
leave the top of the program's primary screen, ten thousand of them, and
draws from them when the view has been moved back. The emulator scrolls in
one place, Blitter.scroll(), so that is where they are taken. The view
moves with the mouse wheel, or with Shift and Page Up, Page Down, Home or
End where the real terminal passes those on; typing returns to the bottom;
and it holds still while output goes on below. The toolbar says how far
back the view is.

When the widget is made shorter, the emulator cuts rows off at the bottom,
the cursor's among them. The rows above the cursor now go to the scrollback
instead, as they do in a terminal.

Not done: selecting text while looking back, rewrapping kept rows when the
width changes, and clearing the scrollback when the program asks (ED 3).
It reaches into bittty and textual-tty attributes which are not public.
@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 39.31298% with 159 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.47%. Comparing base (e5811a3) to head (332aa05).

Files with missing lines Patch % Lines
cmd2/textual_toolbar.py 39.31% 159 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #1816      +/-   ##
==========================================
- Coverage   99.75%   97.47%   -2.29%     
==========================================
  Files          23       24       +1     
  Lines        6664     6926     +262     
==========================================
+ Hits         6648     6751     +103     
- Misses         16      175     +159     
Flag Coverage Δ
unittests 97.47% <39.31%> (-2.29%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

Comment thread cmd2/textual_toolbar.py
HOST_SOCKET_ENV = "CMD2_TEXTUAL_TOOLBAR"

#: Control sequences other than "select graphic rendition", which is how a style is written.
_NOT_A_STYLE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-ln-~]")
CI checks types in an environment which has cmd2's own dependencies and
not the development ones, so it has no Textual, and the import statements
for it failed there. What a host needs from Textual is now imported by
name at run time and treated as untyped, which checks the same way
whether or not Textual is installed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants