Skip to content

Add an example of a persistent bottom toolbar drawn by Textual - #1817

Merged
tleonhardt merged 6 commits into
mainfrom
textual-tty-toolbar-example
Nov 17, 2026
Merged

tleonhardt merged 6 commits into
mainfrom
textual-tty-toolbar-example

Conversation

@tleonhardt

Copy link
Copy Markdown
Member

Summary

Adds a second Textual example, examples/textual_tty_toolbar.py, next to textual_tty_embed.py. It shows one way to have a bottom toolbar which stays on the screen, and keeps refreshing, while a command runs (#1743): let Textual draw it.

Nothing under cmd2/ changes. This is an example and its documentation only.

What the example does

  • A small Textual application owns the terminal. It is nothing but a textual-tty terminal pane running the cmd2 application, and a toolbar widget docked below it, so it looks like the cmd2 application running on its own.
  • The cmd2 application is the same script run with --cmd2-only --toolbar-socket PATH. It passes enable_bottom_toolbar=False so that prompt-toolkit draws no toolbar in the pane.
  • A thread in the cmd2 application calls get_bottom_toolbar() every half second, and at once when a command starts or ends, and sends the result to the Textual application over a Unix socket. Being a thread, it keeps going while a command has the main thread.
  • Command output cannot overwrite the toolbar or make it flicker, because it goes to a different widget.

It uses a socket where textual_tty_embed.py uses the window title. A window title written into the terminal's stream from another thread could land in the middle of a command's output.

Run it with uv run examples/textual_tty_toolbar.py. Add --cmd2-only to see what cmd2 does on its own, where the toolbar is gone for as long as a command runs.

What the approach costs

The example's docstring and the new documentation section say this plainly, since it is why cmd2 does not do this itself:

  • No scrollback. The pane keeps none, and Textual uses the alternate screen, so none of the session is in the user's own terminal's scrollback.
  • No Windows, as for the first example.
  • Ctrl-Z does nothing, and the mouse belongs to Textual.

#1816 is a draft, not for merging, which takes the same idea further: inside cmd2 behind one function call, with a scrollback in the pane, and with measurements against the other two approaches to #1743. The documentation links to it.

Changes

  • examples/textual_tty_toolbar.py: the example.
  • docs/examples/embedding_in_textual.md: a section, "A Bottom Toolbar Which Stays While Commands Run".
  • docs/features/prompt.md: the tip under the bottom toolbar points to it.
  • examples/README.md, CHANGELOG.md: entries.
  • examples/textual_tty_embed.py: one line in its docstring pointing to the new example.

Testing

Examples have no unit tests here, so it was run in real terminals by a driver which types into them, resizes them and reads the screen back. A 23-check scenario passes in iTerm2 3.7.7 and tmux 3.8 on macOS, and in tmux 3.3a and xterm 379 on Linux: the toolbar at the prompt and during a command, resizes while a command prints, the pager, read_input(), tab completion, Ctrl-C, a failed application staying on the screen until Ctrl-Q, and the exit code reaching the shell.

make check, make test and make docs-test pass locally on macOS.

… commands run

cmd2's bottom toolbar is part of the prompt, so it is only on the screen
while the prompt is. examples/textual_tty_toolbar.py shows one way to have
a toolbar which stays, and keeps refreshing, while a command runs: a small
Textual application owns the terminal and shows the cmd2 application in a
textual-tty terminal pane with the toolbar in a widget docked below it. The
cmd2 application gives prompt-toolkit no toolbar to draw, and a thread in it
sends what get_bottom_toolbar() returns to the Textual application over a
Unix socket.

It is a sibling of textual_tty_embed.py and needs the same things: a POSIX
system and textual-tty, which is already in the development environment.
Nothing in the cmd2 package changes.

The Embedding in Textual page of the documentation gains a section on it,
which also says what the approach costs: no scrollback, no Windows, no
Ctrl-Z, and the mouse belongs to Textual.
Comment thread examples/textual_tty_toolbar.py Fixed
@codecov

codecov Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.75%. Comparing base (b3579d1) to head (b9a9993).

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1817   +/-   ##
=======================================
  Coverage   99.75%   99.75%           
=======================================
  Files          23       23           
  Lines        6664     6664           
=======================================
  Hits         6648     6648           
  Misses         16       16           
Flag Coverage Δ
unittests 99.75% <ø> (ø)

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.

…attern

CodeQL reported the range "@-l" as overly permissive, since it runs from
the uppercase letters through punctuation into the lowercase ones. It was
meant to: with "n-~" it is every final byte of a control sequence except
the "m" of "select graphic rendition". Write the same set without a range
which crosses those classes, and say what the class is.
@tleonhardt
tleonhardt merged commit e8d5ea3 into main Nov 17, 2026
32 checks passed
@tleonhardt
tleonhardt deleted the textual-tty-toolbar-example branch November 17, 2026 02:35
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