Skip to content

Commit 47e675a

Browse files
committed
Merge branch 'main' into consolidated_toolbar
# Conflicts: # CHANGELOG.md # docs/features/prompt.md
2 parents d42d800 + e8d5ea3 commit 47e675a

6 files changed

Lines changed: 483 additions & 3 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,12 @@
3434
[Updating Output in Place](docs/features/generating_output.md#updating-output-in-place)
3535
documentation for details, including why a carriage return embedded in a string passed to
3636
`poutput()` does not move the cursor.
37+
- Added the
38+
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
39+
example, which shows how to keep a bottom toolbar on the screen while commands run by running
40+
a `cmd2` application inside a Textual application which draws the toolbar. See
41+
[Embedding in Textual](docs/examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run)
42+
for how it works and what it costs.
3743
- `enable_bottom_toolbar=True` now keeps the toolbar visible and refreshing during command
3844
execution. Command output appears above it. A line of output left unfinished when a command
3945
ends is ended there, so the next prompt starts on a new line while the toolbar is enabled.

‎docs/examples/embedding_in_textual.md‎

Lines changed: 65 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,15 @@ The
1313
[textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py)
1414
example shows how to do this. It has a `cmd2` application in a terminal pane on the left. On the
1515
right, a status panel shows whether the `cmd2` application is idle or running a command, how many
16-
commands it has run, and how long the last one took, and a clock is updated by Textual on its own.
16+
commands it has run, and how long the last one took, and a clock is updated by Textual on its own. A
17+
second example uses the same technique for
18+
[a bottom toolbar which stays while commands run](#a-bottom-toolbar-which-stays-while-commands-run).
1719

1820
!!! warning
1921

20-
textual-tty is still pre-alpha software, so its API may change. The example was written for
22+
textual-tty is still pre-alpha software, so its API may change. The examples were written for
2123
textual-tty 0.4. Also, on Windows textual-tty can only start a program by name and can't pass
22-
it arguments, so the example's Textual application requires a POSIX system such as Linux or
24+
it arguments, so the examples' Textual applications require a POSIX system such as Linux or
2325
macOS.
2426

2527
## Running the Example
@@ -115,3 +117,63 @@ The example handles several details which are easy to miss when building somethi
115117
rows than are visible and its prompt can end up hidden.
116118
- The focused `Terminal` sends almost every key press to the `cmd2` application. Textual's built-in
117119
++ctrl+q++ binding to quit is a priority binding, so it still works.
120+
121+
## A Bottom Toolbar Which Stays While Commands Run
122+
123+
A [bottom toolbar](../features/prompt.md#bottom-toolbar) is drawn by `prompt-toolkit` as part of the
124+
prompt, so it is only on the screen while the prompt is. The same embedding technique gives you one
125+
which stays, and keeps refreshing, while a command runs. The
126+
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
127+
example is a Textual application which is nothing but a terminal pane running a `cmd2` application
128+
and a toolbar docked below it, so it looks like the `cmd2` application running on its own:
129+
130+
```shell
131+
uv run examples/textual_tty_toolbar.py
132+
```
133+
134+
Try `slow`, `burst 2000 1`, or resizing the window while a command runs. Pass `--cmd2-only` to see
135+
what `cmd2` does without Textual, where the toolbar disappears for as long as a command runs.
136+
137+
Here the `cmd2` application doesn't draw the toolbar at all. It passes `enable_bottom_toolbar=False`
138+
to [cmd2.Cmd.__init__][] when it is running inside the Textual application, and sends what
139+
`get_bottom_toolbar()` returns to the Textual application, which shows it in a widget of its own:
140+
141+
```py
142+
def compose(self) -> ComposeResult:
143+
yield Terminal(command=self._cmd2_command, id="cmd2")
144+
yield Static("", id="toolbar")
145+
146+
147+
def on_toolbar_changed(self, message: ToolbarChanged) -> None:
148+
self.query_one("#toolbar", Static).update(Text.from_ansi(message.rendered))
149+
```
150+
151+
Command output can't overwrite the toolbar or make it flicker, because it goes to a different
152+
widget, and a toolbar of more than one row simply takes rows from the terminal pane.
153+
154+
The first example sends its status through the window title, from hooks which run between one
155+
command's output and the next. A toolbar which refreshes _during_ a command has to be sent from
156+
another thread, and a window title written into the terminal's stream from another thread could land
157+
in the middle of the command's output. So this example uses a Unix socket instead:
158+
159+
- The Textual application listens on a socket in a temporary directory before it starts the `cmd2`
160+
application, and passes it the path with `--toolbar-socket`.
161+
- In the `cmd2` application, a thread calls `get_bottom_toolbar()` every half second, and at once
162+
when a postparsing or command finalization hook says a command has started or ended. It renders
163+
the result to text with ANSI style sequences using `prompt-toolkit`, so anything
164+
`get_bottom_toolbar()` is allowed to return works, and sends it as a line of JSON when it has
165+
changed.
166+
- `get_bottom_toolbar()` is therefore called on that thread while a command is running on the main
167+
thread, so it must only read state which is safe to read from another thread.
168+
169+
This approach has costs which are easy to overlook, and they are why `cmd2` doesn't do it for you:
170+
171+
- There is no scrollback. The terminal pane keeps none, so output which scrolls off its top is gone,
172+
and Textual uses the terminal's alternate screen, so none of the session is in the scrollback of
173+
the user's own terminal either.
174+
- It doesn't work on Windows, for the reason given in the warning above.
175+
- ++ctrl+z++ does nothing, because inside the terminal pane there is no shell to return to.
176+
- Textual takes the mouse, so selecting text the way the user's terminal does it needs that
177+
terminal's modifier key.
178+
- All output passes through a second terminal emulator, and the program is started twice: once as
179+
the Textual application and once, inside it, as the `cmd2` application.

‎docs/features/prompt.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,6 +151,10 @@ once and the command carries on without the toolbar.
151151
widgets which display that information. See
152152
[Embedding in Textual](../examples/embedding_in_textual.md).
153153

154+
The same technique can also draw the toolbar itself, in a widget of the Textual application. See
155+
[A Bottom Toolbar Which Stays While Commands Run](../examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run)
156+
for an example, and for what it costs.
157+
154158
### Commands That Take Over the Terminal
155159

156160
cmd2 temporarily hides the toolbar for pagers, Python environments, and shell commands. It also

‎examples/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,10 @@ each:
100100
application using [textual-tty](https://github.com/ttygroup/textual-tty), with a realtime
101101
status panel next to the terminal. Requires a POSIX system such as Linux or macOS and
102102
`textual-tty`, which is part of the `cmd2` development environment but not a `cmd2` dependency
103+
- [textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
104+
- Shows how to keep a bottom toolbar on the screen while commands run, by running a `cmd2`
105+
application inside a [Textual](https://textual.textualize.io/) application which draws the
106+
toolbar. Requires a POSIX system and `textual-tty`, like `textual_tty_embed.py`
103107
- [tmux_launch.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_launch.sh)
104108
- Shell script that launches two applications using tmux in different windows/tabs
105109
- [tmux_split.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_split.sh)

‎examples/textual_tty_embed.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@
3030
python examples/textual_tty_embed.py --cmd2-only
3131
3232
Use the ``quit`` command in the embedded cmd2 application, or press Ctrl-Q, to exit.
33+
34+
See ``textual_tty_toolbar.py`` for the same technique used to keep a bottom toolbar on the screen while commands run.
3335
"""
3436

3537
import argparse

0 commit comments

Comments
 (0)