Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,12 @@
[Updating Output in Place](docs/features/generating_output.md#updating-output-in-place)
documentation for details, including why a carriage return embedded in a string passed to
`poutput()` does not move the cursor.
- Added the
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
example, which shows how to keep a bottom toolbar on the screen while commands run by running
a `cmd2` application inside a Textual application which draws the toolbar. See
[Embedding in Textual](docs/examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run)
for how it works and what it costs.

## 4.4.2 (November 11, 2026)

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

!!! warning

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

## Running the Example
Expand Down Expand Up @@ -115,3 +117,63 @@ The example handles several details which are easy to miss when building somethi
rows than are visible and its prompt can end up hidden.
- The focused `Terminal` sends almost every key press to the `cmd2` application. Textual's built-in
++ctrl+q++ binding to quit is a priority binding, so it still works.

## A Bottom Toolbar Which Stays While Commands Run

A [bottom toolbar](../features/prompt.md#bottom-toolbar) is drawn by `prompt-toolkit` as part of the
prompt, so it is only on the screen while the prompt is. The same embedding technique gives you one
which stays, and keeps refreshing, while a command runs. The
[textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
example is a Textual application which is nothing but a terminal pane running a `cmd2` application
and a toolbar docked below it, so it looks like the `cmd2` application running on its own:

```shell
uv run examples/textual_tty_toolbar.py
```

Try `slow`, `burst 2000 1`, or resizing the window while a command runs. Pass `--cmd2-only` to see
what `cmd2` does without Textual, where the toolbar disappears for as long as a command runs.

Here the `cmd2` application doesn't draw the toolbar at all. It passes `enable_bottom_toolbar=False`
to [cmd2.Cmd.__init__][] when it is running inside the Textual application, and sends what
`get_bottom_toolbar()` returns to the Textual application, which shows it in a widget of its own:

```py
def compose(self) -> ComposeResult:
yield Terminal(command=self._cmd2_command, id="cmd2")
yield Static("", id="toolbar")


def on_toolbar_changed(self, message: ToolbarChanged) -> None:
self.query_one("#toolbar", Static).update(Text.from_ansi(message.rendered))
```

Command output can't overwrite the toolbar or make it flicker, because it goes to a different
widget, and a toolbar of more than one row simply takes rows from the terminal pane.

The first example sends its status through the window title, from hooks which run between one
command's output and the next. A toolbar which refreshes _during_ a command has to be sent from
another thread, and a window title written into the terminal's stream from another thread could land
in the middle of the command's output. So this example uses a Unix socket instead:

- The Textual application listens on a socket in a temporary directory before it starts the `cmd2`
application, and passes it the path with `--toolbar-socket`.
- In the `cmd2` application, a thread calls `get_bottom_toolbar()` every half second, and at once
when a postparsing or command finalization hook says a command has started or ended. It renders
the result to text with ANSI style sequences using `prompt-toolkit`, so anything
`get_bottom_toolbar()` is allowed to return works, and sends it as a line of JSON when it has
changed.
- `get_bottom_toolbar()` is therefore called on that thread while a command is running on the main
thread, so it must only read state which is safe to read from another thread.

This approach has costs which are easy to overlook, and they are why `cmd2` doesn't do it for you:

- There is no scrollback. The terminal pane keeps none, so output which scrolls off its top is gone,
and Textual uses the terminal's alternate screen, so none of the session is in the scrollback of
the user's own terminal either.
- It doesn't work on Windows, for the reason given in the warning above.
- ++ctrl+z++ does nothing, because inside the terminal pane there is no shell to return to.
- Textual takes the mouse, so selecting text the way the user's terminal does it needs that
terminal's modifier key.
- All output passes through a second terminal emulator, and the program is started twice: once as
the Textual application and once, inside it, as the `cmd2` application.
5 changes: 5 additions & 0 deletions docs/features/prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,3 +133,8 @@ example for a demonstration of this technique.
`cmd2` application inside a [Textual](https://textual.textualize.io/) application, next to
widgets which display that information. See
[Embedding in Textual](../examples/embedding_in_textual.md).

The same technique can keep a toolbar on the screen while a command runs, which this one is
not: it is part of the prompt. See
[A Bottom Toolbar Which Stays While Commands Run](../examples/embedding_in_textual.md#a-bottom-toolbar-which-stays-while-commands-run)
for an example, and for what it costs.
4 changes: 4 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,10 @@ each:
application using [textual-tty](https://github.com/ttygroup/textual-tty), with a realtime
status panel next to the terminal. Requires a POSIX system such as Linux or macOS and
`textual-tty`, which is part of the `cmd2` development environment but not a `cmd2` dependency
- [textual_tty_toolbar.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_toolbar.py)
- Shows how to keep a bottom toolbar on the screen while commands run, by running a `cmd2`
application inside a [Textual](https://textual.textualize.io/) application which draws the
toolbar. Requires a POSIX system and `textual-tty`, like `textual_tty_embed.py`
- [tmux_launch.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_launch.sh)
- Shell script that launches two applications using tmux in different windows/tabs
- [tmux_split.sh](https://github.com/python-cmd2/cmd2/blob/main/examples/tmux_split.sh)
Expand Down
2 changes: 2 additions & 0 deletions examples/textual_tty_embed.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,8 @@
python examples/textual_tty_embed.py --cmd2-only

Use the ``quit`` command in the embedded cmd2 application, or press Ctrl-Q, to exit.

See ``textual_tty_toolbar.py`` for the same technique used to keep a bottom toolbar on the screen while commands run.
"""

import argparse
Expand Down
Loading
Loading