Repository navigation
[Prototype, not for merge] Bottom toolbar drawn by Textual instead of prompt-toolkit - #1816
Draft
tleonhardt wants to merge 9 commits into
Draft
tleonhardt wants to merge 9 commits into
tleonhardt wants to merge 9 commits into
Conversation
…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 Report❌ Patch coverage is
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
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. |
| 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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
mainas a self-contained example, with nothing undercmd2/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.reserved_row_toolbar, #1815)cmd2packageHow it works
cmd2 does not draw the toolbar at all.
cmd2.textual_toolbar.run(MyApp)replacesMyApp().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.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.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, whereexamples/textual_tty_embed.pyuses the window title, because a thread writing escape sequences into the terminal's stream would interleave with command output.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--plainfor 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.
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.What it gives up
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:
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-screenlessdoes 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 testandmake docs-testpass 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.