Skip to content

Commit 6674b5e

Browse files
committed
Merge branch 'consolidated_toolbar' into builtin_pager
2 parents a0191c9 + b7dd0fd commit 6674b5e

2 files changed

Lines changed: 21 additions & 15 deletions

File tree

‎docs/examples/embedding_in_textual.md‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -120,9 +120,12 @@ The example handles several details which are easy to miss when building somethi
120120

121121
## A Bottom Toolbar Which Stays While Commands Run
122122

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
123+
`cmd2` can keep its own [bottom toolbar](../features/prompt.md#bottom-toolbar) on the screen while a
124+
command runs. It draws that toolbar in the terminal which the command is using, so it has to hide it
125+
whenever something else
126+
[takes over the terminal](../features/prompt.md#commands-that-take-over-the-terminal), as a shell
127+
command does. The same embedding technique gives you a toolbar which is drawn outside that terminal,
128+
so it stays, and keeps refreshing, whatever runs there. The
126129
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
127130
example is a Textual application which is nothing but a terminal pane running a `cmd2` application
128131
and a toolbar docked below it, so it looks like the `cmd2` application running on its own:
@@ -131,8 +134,9 @@ and a toolbar docked below it, so it looks like the `cmd2` application running o
131134
uv run examples/textual_tty_toolbar.py
132135
```
133136

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.
137+
Try `slow`, `burst 2000 1`, `shell sleep 5`, or resizing the window while a command runs. Pass
138+
`--cmd2-only` to compare it with the toolbar `cmd2` draws itself, without Textual, which is hidden
139+
for as long as the shell command runs.
136140

137141
Here the `cmd2` application doesn't draw the toolbar at all. It passes `enable_bottom_toolbar=False`
138142
to [cmd2.Cmd.__init__][] when it is running inside the Textual application, and sends what
@@ -166,7 +170,8 @@ in the middle of the command's output. So this example uses a Unix socket instea
166170
- `get_bottom_toolbar()` is therefore called on that thread while a command is running on the main
167171
thread, so it must only read state which is safe to read from another thread.
168172

169-
This approach has costs which are easy to overlook, and they are why `cmd2` doesn't do it for you:
173+
This approach has costs which are easy to overlook, and they are why `cmd2` draws its own toolbar in
174+
the user's terminal instead:
170175

171176
- There is no scrollback. The terminal pane keeps none, so output which scrolls off its top is gone,
172177
and Textual uses the terminal's alternate screen, so none of the session is in the scrollback of

‎examples/textual_tty_toolbar.py‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
#!/usr/bin/env python3
22
"""Keep a bottom toolbar on the screen while commands run, by letting Textual draw it using textual-tty.
33
4-
cmd2's bottom toolbar is drawn by prompt-toolkit as part of the prompt, so it is only there while the prompt is.
5-
This example shows a way to have one which stays, and keeps refreshing, while a command runs: the cmd2
6-
application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows the
7-
cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar.
4+
cmd2 can keep its own bottom toolbar on the screen while a command runs. It draws that toolbar in the terminal
5+
which the command is using, so it has to hide it whenever something else takes over the terminal, as a shell
6+
command does. This example shows a way to have one which stays, and keeps refreshing, whatever runs there: the
7+
cmd2 application doesn't draw the toolbar at all. A small Textual application owns the terminal instead. It shows
8+
the cmd2 application in a terminal pane which fills the screen except for the bottom, where it draws the toolbar.
89
910
How it works:
1011
- [textual-tty](https://github.com/ttygroup/textual-tty) provides the ``Terminal`` widget, a terminal
@@ -22,7 +23,7 @@
2223
output. A toolbar which refreshes during a command is sent from another thread, and a window title written into
2324
the terminal's stream from another thread could land in the middle of the command's output.
2425
25-
Things this approach gives up, which is why cmd2 doesn't do it for you:
26+
Things this approach gives up, which is why cmd2 draws its own toolbar in your terminal instead:
2627
- Scrollback. The terminal pane keeps none, so output which scrolls off its top is gone, and Textual uses
2728
the terminal's alternate screen, so none of the session is in your terminal's own scrollback either.
2829
Pipe long output to a pager.
@@ -38,8 +39,9 @@
3839
Otherwise, install textual-tty into your own environment with ``pip install textual-tty`` and then run
3940
``python examples/textual_tty_toolbar.py``.
4041
41-
Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, resizing the window while a command runs, and
42-
Ctrl-C during ``slow``. To compare with what cmd2 does on its own, run just the cmd2 application, on any platform:
42+
Things to try: ``slow``, ``burst 2000 1``, ``page``, ``ask``, ``shell sleep 5``, resizing the window while a
43+
command runs, and Ctrl-C during ``slow``. To compare with the toolbar cmd2 draws itself, run just the cmd2
44+
application, on any platform:
4345
4446
python examples/textual_tty_toolbar.py --cmd2-only
4547
@@ -171,8 +173,7 @@ def __init__(self, toolbar_socket: str | None) -> None:
171173
"""Initialize the cmd2 application.
172174
173175
:param toolbar_socket: the Unix socket of the Textual application which draws the toolbar, or None if this
174-
application isn't running inside one. Then prompt-toolkit draws the toolbar as usual,
175-
which means only while the prompt is on the screen.
176+
application isn't running inside one. Then cmd2 draws the toolbar itself.
176177
"""
177178
refresh_interval = 0.5
178179
super().__init__(

0 commit comments

Comments
 (0)