|
13 | 13 | [textual_tty_embed.py](https://github.com/python-cmd2/cmd2/blob/main/examples/textual_tty_embed.py) |
14 | 14 | example shows how to do this. It has a `cmd2` application in a terminal pane on the left. On the |
15 | 15 | 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). |
17 | 19 |
|
18 | 20 | !!! warning |
19 | 21 |
|
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 |
21 | 23 | 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 |
23 | 25 | macOS. |
24 | 26 |
|
25 | 27 | ## Running the Example |
@@ -115,3 +117,63 @@ The example handles several details which are easy to miss when building somethi |
115 | 117 | rows than are visible and its prompt can end up hidden. |
116 | 118 | - The focused `Terminal` sends almost every key press to the `cmd2` application. Textual's built-in |
117 | 119 | ++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. |
0 commit comments