Follow the device-config editor's exit-group pattern: once the order has actually changed, an ok-tinted Apply joins an err-tinted "Back — discard changes"; untouched, a lone Back. Enter on a list row now grabs/drops like Space (matching Enter-activates-the-row), and committing happens on the Apply row instead of Enter-anywhere. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
808 lines
32 KiB
Python
808 lines
32 KiB
Python
"""The persistent full-screen session: the heart of the TUI library.
|
|
|
|
A :class:`TuiSession` owns one prompt_toolkit :class:`Application`, a stack of
|
|
:class:`~meshterm.ui.tui.screen.Screen` layers, and the persistent header/footer frame. It
|
|
translates prompt_toolkit key events into normalized *actions* dispatched to the top screen,
|
|
composes the current view (bounded to the terminal, reflowing on resize) via
|
|
:mod:`~meshterm.ui.tui.frame`, and exposes ``async`` helpers (``select``/``text``/
|
|
``confirm``/``autocomplete``/``scroll``/``progress``) that push a screen, await its result,
|
|
and pop it — the push/await/pop model behind every prompt.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
from contextlib import asynccontextmanager
|
|
from typing import Any, AsyncIterator, Callable, Optional
|
|
|
|
from prompt_toolkit.application import Application
|
|
from prompt_toolkit.filters import Condition
|
|
from prompt_toolkit.formatted_text import ANSI
|
|
from prompt_toolkit.key_binding import KeyBindings
|
|
from prompt_toolkit.keys import Keys
|
|
from prompt_toolkit.layout import ConditionalContainer, Float, FloatContainer, Layout, Window
|
|
from prompt_toolkit.layout.controls import FormattedTextControl
|
|
from rich.console import RenderableType
|
|
from rich.text import Text
|
|
|
|
from . import frame
|
|
from .overlay import BusyOverlay
|
|
from .progress import TuiProgress
|
|
from .prompt import (
|
|
AutocompleteScreen,
|
|
ButtonDialog,
|
|
ConfirmScreen,
|
|
PinDialog,
|
|
TextScreen,
|
|
TypedConfirmDialog,
|
|
Validator,
|
|
)
|
|
from .screen import CANCEL, BusyScreen, Screen, ScrollScreen
|
|
from .select import Choice, ReorderScreen, SelectScreen, Separator
|
|
|
|
#: Maps prompt_toolkit keys to the normalized action names screens understand.
|
|
_KEY_ACTIONS: dict[Any, str] = {
|
|
Keys.Up: "up",
|
|
Keys.Down: "down",
|
|
Keys.Left: "left",
|
|
Keys.Right: "right",
|
|
Keys.ShiftUp: "shift_up",
|
|
Keys.ShiftDown: "shift_down",
|
|
Keys.ShiftLeft: "shift_left",
|
|
Keys.ShiftRight: "shift_right",
|
|
Keys.PageUp: "pageup",
|
|
Keys.PageDown: "pagedown",
|
|
Keys.Home: "home",
|
|
Keys.End: "end",
|
|
Keys.ControlHome: "ctrl_home",
|
|
Keys.ControlEnd: "ctrl_end",
|
|
Keys.ControlPageUp: "ctrl_pageup",
|
|
Keys.ControlPageDown: "ctrl_pagedown",
|
|
Keys.ControlLeft: "ctrl_left",
|
|
Keys.ControlRight: "ctrl_right",
|
|
Keys.Enter: "enter",
|
|
Keys.Escape: "escape",
|
|
Keys.Backspace: "backspace",
|
|
Keys.Delete: "delete",
|
|
Keys.Tab: "tab",
|
|
Keys.ControlR: "retry",
|
|
}
|
|
|
|
|
|
def _message_border(message: "Text | str") -> str:
|
|
"""Pick a message dialog's border style from the strongest tone in the text.
|
|
|
|
Outcome notes carry their severity as theme spans (``[err]``, ``[warn]``, ``[ok]``),
|
|
so the dialog frame can echo it: an error message gets the ``err`` border, a warning
|
|
(e.g. "device rebooting") the cautionary one, and anything else — successes included —
|
|
the standard accent. A plain string carries no spans and always reads as neutral.
|
|
|
|
Args:
|
|
message: The dialog's message, styled or plain.
|
|
|
|
Returns:
|
|
The Rich style name for the dialog border.
|
|
"""
|
|
if isinstance(message, Text):
|
|
styles = {str(span.style) for span in message.spans}
|
|
if "err" in styles:
|
|
return "err"
|
|
if "warn" in styles:
|
|
return "warn"
|
|
return "accent"
|
|
|
|
|
|
class TuiSession:
|
|
"""A running full-screen TUI: screen stack, frame, input loop, and async prompts."""
|
|
|
|
def __init__(
|
|
self,
|
|
header: Optional[Callable[[], RenderableType]] = None,
|
|
*,
|
|
input: Any = None, # noqa: A002 - matches prompt_toolkit's Application(input=) name
|
|
output: Any = None,
|
|
) -> None:
|
|
"""Create a session.
|
|
|
|
Args:
|
|
header: Callable returning the persistent header renderable (banner + live
|
|
status), re-invoked on every repaint. Defaults to a plain title.
|
|
input: Optional prompt_toolkit input to drive the app from (tests use a pipe);
|
|
defaults to the real terminal.
|
|
output: Optional prompt_toolkit output to render to (tests use a dummy);
|
|
defaults to the real terminal.
|
|
"""
|
|
self._stack: list[Screen] = []
|
|
self._header = header or (lambda: Text("MeshTerm", style="brand"))
|
|
self._app: Optional[Application] = None
|
|
self._input = input
|
|
self._output = output
|
|
# The top-most floating "working" overlay (a ring spinner), or None when idle. It is
|
|
# deliberately *not* on the screen stack: it hovers above every layer and is shown/
|
|
# hidden by busy_overlay, independent of whatever screens are pushed.
|
|
self._overlay: Optional[BusyOverlay] = None
|
|
|
|
# --- stack ---------------------------------------------------------------
|
|
|
|
@property
|
|
def top(self) -> Optional[Screen]:
|
|
"""The active (top-most) screen, or ``None`` when the stack is empty."""
|
|
return self._stack[-1] if self._stack else None
|
|
|
|
def push(self, screen: Screen) -> None:
|
|
"""Push a screen onto the stack and repaint."""
|
|
self._stack.append(screen)
|
|
self.invalidate()
|
|
|
|
def pop(self, screen: Optional[Screen] = None) -> None:
|
|
"""Pop ``screen`` (or the top) off the stack and repaint."""
|
|
if not self._stack:
|
|
return
|
|
if screen is None or self._stack[-1] is screen:
|
|
self._stack.pop()
|
|
elif screen in self._stack:
|
|
self._stack.remove(screen)
|
|
self._expose_overlay()
|
|
self.invalidate()
|
|
|
|
def reset(self) -> None:
|
|
"""Clear the whole screen stack and repaint.
|
|
|
|
Used to unwind to a blank frame after a cancelled activity — e.g. when a mid-session
|
|
device disconnect abandons whatever screens the interrupted work had pushed, before
|
|
the reconnect dialog is shown over a clean slate. Screens hold no external resources
|
|
(their callers pop them in ``finally``), so dropping any stragglers here is safe.
|
|
"""
|
|
self._stack.clear()
|
|
self._expose_overlay()
|
|
self.invalidate()
|
|
|
|
def _expose_overlay(self) -> None:
|
|
"""Restart the busy overlay's fade whenever a stack change re-exposes it.
|
|
|
|
A prompt pushed over an active overlay hides the ring; popping back to an empty stack
|
|
re-exposes it. Restart the intro then so the black hold and fade-in replay fresh each
|
|
time the ring is shown, rather than snapping back at full brightness (see
|
|
:meth:`~meshterm.ui.tui.overlay.BusyOverlay.restart`).
|
|
"""
|
|
if self._overlay is not None and not self._stack:
|
|
self._overlay.restart()
|
|
|
|
def invalidate(self) -> None:
|
|
"""Request a repaint if the application is running."""
|
|
if self._app is not None:
|
|
self._app.invalidate()
|
|
|
|
def request_full_repaint(self) -> None:
|
|
"""Force the next paint to rewrite every cell, then schedule it.
|
|
|
|
prompt_toolkit repaints differentially: cells equal to the previous frame are left
|
|
untouched. That is normally what we want, but it also means terminal-side corruption
|
|
(a double-width fallback glyph the diff can't see) survives until those exact cells
|
|
change. Callers use this when leaving a screen that could have smeared the terminal —
|
|
the map — so the screen drawn underneath starts from a clean slate.
|
|
"""
|
|
self._invalidate_last_frame()
|
|
self.invalidate()
|
|
|
|
def _invalidate_last_frame(self) -> None:
|
|
"""Drop prompt_toolkit's cached last frame so the next paint rewrites every cell.
|
|
|
|
Touches a prompt_toolkit internal, so it fails soft if the attribute ever moves.
|
|
"""
|
|
renderer = getattr(self._app, "renderer", None)
|
|
if renderer is not None and hasattr(renderer, "_last_screen"):
|
|
renderer._last_screen = None
|
|
|
|
def _scrub_right_columns(self, count: int) -> None:
|
|
"""Force prompt_toolkit to repaint the rightmost ``count`` columns on the next diff.
|
|
|
|
Overwrites those cells in pt's remembered last frame with a sentinel that can't equal
|
|
any real content, so the differential renderer treats them as changed and redraws
|
|
them — scrubbing a double-width fallback glyph that smeared over the panel's right
|
|
edge, without the whole-frame flicker of dropping the entire cached frame. Touches a
|
|
pt internal, so it fails soft if the structure ever moves.
|
|
"""
|
|
renderer = getattr(self._app, "renderer", None)
|
|
last = getattr(renderer, "_last_screen", None)
|
|
if last is None:
|
|
return
|
|
try:
|
|
from prompt_toolkit.layout.screen import Char
|
|
|
|
buffer = last.data_buffer
|
|
cols, _ = self._size()
|
|
sentinel = Char("") # a non-character; never equals real cell content
|
|
for x in range(max(0, cols - count), cols):
|
|
for row in list(buffer.keys()):
|
|
buffer[row][x] = sentinel
|
|
except Exception: # noqa: BLE001 - a cosmetic scrub must never break rendering
|
|
pass
|
|
|
|
# --- async prompt helpers ------------------------------------------------
|
|
|
|
async def run_screen(self, screen: Screen) -> Any:
|
|
"""Push a screen, await its result, then pop it.
|
|
|
|
Args:
|
|
screen: The screen to run.
|
|
|
|
Returns:
|
|
The screen's resolved value, or :data:`~meshterm.ui.tui.screen.CANCEL`.
|
|
"""
|
|
loop = asyncio.get_running_loop()
|
|
screen.future = loop.create_future()
|
|
self.push(screen)
|
|
try:
|
|
return await screen.future
|
|
finally:
|
|
self.pop(screen)
|
|
|
|
async def select(
|
|
self,
|
|
title: str,
|
|
items: list,
|
|
*,
|
|
prompt: str = "",
|
|
default: Any = None,
|
|
wrap: bool = True,
|
|
filterable: bool = True,
|
|
footer_hint: Optional[str] = None,
|
|
) -> Any:
|
|
"""Show a select screen; return the chosen value or ``None`` if cancelled.
|
|
|
|
``prompt`` draws an instruction inside the box above the list; ``filterable`` and
|
|
``footer_hint`` are forwarded for short, fixed lists (a yes-or-no style choice) that
|
|
want no type-to-filter and a tailored hint.
|
|
"""
|
|
kwargs: dict[str, Any] = dict(
|
|
prompt=prompt, default=default, wrap=wrap, filterable=filterable
|
|
)
|
|
if footer_hint is not None:
|
|
kwargs["footer_hint"] = footer_hint
|
|
result = await self.run_screen(SelectScreen(title, items, **kwargs))
|
|
return None if result is CANCEL else result
|
|
|
|
async def select_startup(
|
|
self,
|
|
title: str,
|
|
items: list,
|
|
*,
|
|
default: Any = None,
|
|
banner: Optional[Any] = None,
|
|
footnote: Optional[str] = None,
|
|
footer_hint: str = "↑↓ move · Enter select · Esc quit",
|
|
) -> Any:
|
|
"""Show a chromeless select splash (banner above a content-sized box).
|
|
|
|
Like :meth:`select`, but drawn without the header/footer status bars and centered
|
|
under ``banner`` — the startup device picker's presentation. Type-to-filter is off:
|
|
the device list is short and fixed, so stray keys never narrow it. An optional
|
|
``footnote`` (e.g. a copyright notice) sits muted below the box.
|
|
"""
|
|
screen = SelectScreen(
|
|
title, items, default=default, footer_hint=footer_hint, filterable=False
|
|
)
|
|
screen.chrome = False
|
|
screen.banner = banner
|
|
screen.footnote = footnote
|
|
result = await self.run_screen(screen)
|
|
return None if result is CANCEL else result
|
|
|
|
async def notify_startup(
|
|
self,
|
|
renderable: RenderableType,
|
|
*,
|
|
title: str = "",
|
|
banner: Optional[Any] = None,
|
|
footnote: Optional[str] = None,
|
|
footer_hint: str = "Enter continue",
|
|
) -> None:
|
|
"""Show a chromeless message splash (banner above a boxed renderable) until dismissed."""
|
|
screen = ScrollScreen(renderable, title=title, footer_hint=footer_hint)
|
|
screen.chrome = False
|
|
screen.banner = banner
|
|
screen.footnote = footnote
|
|
await self.run_screen(screen)
|
|
|
|
async def busy_startup(
|
|
self,
|
|
message: str,
|
|
coro: Any,
|
|
*,
|
|
title: str = "",
|
|
banner: Optional[Any] = None,
|
|
footnote: Optional[str] = None,
|
|
interval: float = 0.12,
|
|
) -> Any:
|
|
"""Await ``coro`` while showing an animated spinner on the chromeless splash.
|
|
|
|
Keeps the startup splash on screen (same wordmark and box) and swaps its contents for
|
|
an ASCII spinner beside ``message`` while the awaited task runs, then returns the
|
|
task's result. A background timer advances the spinner and repaints every
|
|
``interval`` seconds; it is always cancelled and the splash popped before returning.
|
|
|
|
Args:
|
|
message: The line shown beside the spinner (e.g. "Talking to Wio on COM5…").
|
|
coro: The awaitable to run (e.g. a device smoke test).
|
|
title: Optional panel title for the splash box.
|
|
banner: Wordmark rows drawn above the box (as on the other startup splashes).
|
|
footnote: Muted line drawn below the box.
|
|
interval: Seconds between spinner frames.
|
|
|
|
Returns:
|
|
Whatever ``coro`` resolves to.
|
|
"""
|
|
screen = BusyScreen(message, title=title)
|
|
screen.chrome = False
|
|
screen.banner = banner
|
|
screen.footnote = footnote
|
|
self.push(screen)
|
|
|
|
async def animate() -> None:
|
|
while True:
|
|
await asyncio.sleep(interval)
|
|
screen.tick()
|
|
self.invalidate()
|
|
|
|
ticker = asyncio.ensure_future(animate())
|
|
try:
|
|
return await coro
|
|
finally:
|
|
ticker.cancel()
|
|
# Await the cancelled ticker so it is never garbage-collected while still
|
|
# pending: that surfaces as a screen-corrupting "Task was destroyed but it is
|
|
# pending!" loop error. The spinner is cosmetic, so any glitch is swallowed.
|
|
try:
|
|
await ticker
|
|
except asyncio.CancelledError:
|
|
pass
|
|
except Exception: # noqa: BLE001 - a spinner hiccup must never break startup
|
|
pass
|
|
self.pop(screen)
|
|
|
|
async def prompt_pin_startup(
|
|
self,
|
|
device_name: str,
|
|
*,
|
|
error: str = "",
|
|
help_text: str = "",
|
|
banner: Optional[Any] = None,
|
|
footnote: Optional[str] = None,
|
|
) -> Optional[str]:
|
|
"""Ask for a companion's Bluetooth PIN on the chromeless startup splash.
|
|
|
|
Drawn like :meth:`notify_startup` / :meth:`select_startup` — a bordered box centered
|
|
under ``banner`` with no status bars — so the PIN request is visually part of the same
|
|
device-selection flow. ``error`` is shown in the box on a re-ask after a rejected code.
|
|
|
|
Args:
|
|
device_name: The companion's display name, shown in the prompt.
|
|
error: A rejected-PIN message to display (empty on the first ask).
|
|
help_text: A muted hint under the field.
|
|
banner: Wordmark rows drawn above the box (as on the other startup splashes).
|
|
footnote: Muted line drawn below the box.
|
|
|
|
Returns:
|
|
The entered PIN, or ``None`` if the user pressed Esc to cancel.
|
|
"""
|
|
screen = PinDialog(device_name, error=error, help_text=help_text)
|
|
screen.chrome = False
|
|
screen.banner = banner
|
|
screen.footnote = footnote
|
|
result = await self.run_screen(screen)
|
|
return None if result is CANCEL else result
|
|
|
|
async def reorder(self, title: str, labels: list[str]) -> list[int]:
|
|
"""Show a drag-with-arrows reorder screen; return the final order of row indices.
|
|
|
|
The Apply action row below the list commits the rearrangement; Back (or Esc)
|
|
cancels, which comes back as the original (identity) order so the caller
|
|
treats it as "no change".
|
|
"""
|
|
result = await self.run_screen(ReorderScreen(title, labels))
|
|
return list(range(len(labels))) if result is CANCEL else result
|
|
|
|
async def text(
|
|
self,
|
|
title: str,
|
|
*,
|
|
prompt: str = "",
|
|
default: str = "",
|
|
validate: Optional[Validator] = None,
|
|
help_text: str = "",
|
|
password: bool = False,
|
|
) -> Optional[str]:
|
|
"""Show a text prompt; return the string or ``None`` if cancelled."""
|
|
result = await self.run_screen(
|
|
TextScreen(
|
|
title,
|
|
prompt=prompt,
|
|
default=default,
|
|
validate=validate,
|
|
help_text=help_text,
|
|
password=password,
|
|
)
|
|
)
|
|
return None if result is CANCEL else result
|
|
|
|
async def confirm(self, title: str, *, default: bool = True) -> Optional[bool]:
|
|
"""Show a yes/no prompt; return the bool or ``None`` if cancelled."""
|
|
result = await self.run_screen(ConfirmScreen(title, default=default))
|
|
return None if result is CANCEL else result
|
|
|
|
async def button_dialog(
|
|
self,
|
|
prompt: "str | Text",
|
|
buttons: list[tuple[str, Any]],
|
|
*,
|
|
title: str = "",
|
|
default: int = 0,
|
|
keys: Optional[dict[str, Any]] = None,
|
|
footer_hint: str = "←→ choose · Enter select · Esc cancel",
|
|
prompt_style: str = "",
|
|
button_style: str = "selected",
|
|
button_idle_style: str = "muted",
|
|
border_style: str = "accent",
|
|
) -> Any:
|
|
"""Show a centered button dialog; return the chosen value or ``None`` if cancelled.
|
|
|
|
A reusable prompt-above-buttons dialog (see :class:`~meshterm.ui.tui.prompt.
|
|
ButtonDialog`): the colours, prompt, buttons, and single-key shortcuts are all
|
|
parametrised, so a caller can theme it (e.g. a destructive action in red) or wire
|
|
instant y/n keys. ``keys`` maps a shortcut character to the value it commits.
|
|
The prompt may be a pre-styled :class:`Text` (see the ButtonDialog docs).
|
|
"""
|
|
screen = ButtonDialog(
|
|
prompt,
|
|
buttons,
|
|
title=title,
|
|
default=default,
|
|
keys=keys,
|
|
footer_hint=footer_hint,
|
|
prompt_style=prompt_style,
|
|
button_style=button_style,
|
|
button_idle_style=button_idle_style,
|
|
border_style=border_style,
|
|
)
|
|
result = await self.run_screen(screen)
|
|
return None if result is CANCEL else result
|
|
|
|
async def typed_confirm(
|
|
self, warning: str, word: str, *, title: str = "Are you sure?"
|
|
) -> bool:
|
|
"""Gate a destructive action behind typing ``word``; return whether it was typed.
|
|
|
|
Shows the error-themed :class:`~meshterm.ui.tui.prompt.TypedConfirmDialog` and
|
|
collapses its result to a plain bool: ``True`` only when the user typed the word,
|
|
``False`` when they backed out with Esc.
|
|
"""
|
|
result = await self.run_screen(TypedConfirmDialog(warning, word, title=title))
|
|
return result is True
|
|
|
|
async def autocomplete(
|
|
self,
|
|
title: str,
|
|
choices: list[str],
|
|
*,
|
|
prompt: str = "",
|
|
default: str = "",
|
|
validate: Optional[Validator] = None,
|
|
) -> Optional[str]:
|
|
"""Show a free-text prompt with suggestions; return text or ``None`` if cancelled."""
|
|
result = await self.run_screen(
|
|
AutocompleteScreen(
|
|
title, choices, prompt=prompt, default=default, validate=validate
|
|
)
|
|
)
|
|
return None if result is CANCEL else result
|
|
|
|
async def message_dialog(self, message: "Text | str", *, title: str = "") -> None:
|
|
"""Show a short outcome in a centered popup with a single OK button.
|
|
|
|
The lightweight acknowledgement counterpart of :meth:`scroll`: a one-line result
|
|
("✓ flood advertisement sent") doesn't warrant a full result window, so it floats
|
|
as a small dialog over whatever screen is beneath — Enter (OK) or Esc dismisses
|
|
it. The border takes the message's strongest tone (see :func:`_message_border`),
|
|
so an error pops red while a success stays in the standard accent.
|
|
|
|
When the screen stack is empty — a tool run straight from the main menu, which is
|
|
popped while the tool executes — a blank base frame is pushed first, because a
|
|
lone floating screen is otherwise drawn *as* the base (full-frame, no popup); the
|
|
same trick the reconnect dialog uses.
|
|
|
|
Args:
|
|
message: The outcome to show — a pre-styled :class:`Text` (note markup
|
|
survives into the dialog) or a plain string.
|
|
title: Optional dialog heading (typically the tool or action name).
|
|
"""
|
|
backdrop: Optional[ScrollScreen] = None
|
|
if not self._stack:
|
|
backdrop = ScrollScreen("", floating=False, footer_hint="")
|
|
self.push(backdrop)
|
|
try:
|
|
await self.button_dialog(
|
|
message,
|
|
[("OK", "ok")],
|
|
title=title,
|
|
footer_hint="Enter OK",
|
|
border_style=_message_border(message),
|
|
)
|
|
finally:
|
|
if backdrop is not None:
|
|
self.pop(backdrop)
|
|
|
|
async def scroll(
|
|
self, renderable: RenderableType, *, title: str = "", footer_hint: str = ""
|
|
) -> None:
|
|
"""Show a dismissable, scrollable view of a renderable (a result window)."""
|
|
screen = ScrollScreen(
|
|
renderable,
|
|
title=title,
|
|
footer_hint=footer_hint or "↑↓ PgUp/PgDn scroll · Esc back",
|
|
)
|
|
await self.run_screen(screen)
|
|
|
|
def progress(self, title: str = "Working") -> TuiProgress:
|
|
"""Return a progress context manager backed by a pushed :class:`ProgressScreen`."""
|
|
return TuiProgress(self, title)
|
|
|
|
@asynccontextmanager
|
|
async def busy_overlay(
|
|
self,
|
|
message: str = "",
|
|
*,
|
|
interval: float = 0.06,
|
|
) -> AsyncIterator[BusyOverlay]:
|
|
"""Float an animated ring spinner on top of everything for the duration of a block.
|
|
|
|
Wrap a slow, screen-affecting operation — most usefully a device menu navigation,
|
|
which can otherwise sit on a blank frame while the companion answers — in::
|
|
|
|
async with session.busy_overlay("Talking to your companion…"):
|
|
await slow_work()
|
|
|
|
A background timer advances the ring, fades it in, and repaints while the block runs;
|
|
the overlay is always cleared and the timer cancelled on exit, even on error. The ring
|
|
fades in from black rather than popping in (see :attr:`BusyOverlay.brightness`), so a
|
|
quick operation only paints a near-black ring and it never appears suddenly. It is
|
|
drawn only in the gaps between screens (see :meth:`_overlay_visible`), so it announces
|
|
the wait without covering a prompt the user is interacting with.
|
|
|
|
Args:
|
|
message: An optional caption drawn beneath the ring.
|
|
interval: Seconds between animation frames (also the fade's repaint cadence).
|
|
|
|
Yields:
|
|
The live :class:`BusyOverlay`, in case the caller wants to update its caption.
|
|
"""
|
|
# A nested busy_overlay keeps the outer one (the outermost wait owns the screen); its
|
|
# own body still runs, it just doesn't install a second ring.
|
|
if self._overlay is not None:
|
|
yield self._overlay
|
|
return
|
|
overlay = BusyOverlay(message)
|
|
self._overlay = overlay
|
|
if self._overlay_visible():
|
|
self.invalidate() # start the fade-in promptly, before the first tick
|
|
|
|
async def animate() -> None:
|
|
while True:
|
|
await asyncio.sleep(interval)
|
|
overlay.tick()
|
|
# Only repaint when the ring is actually on screen, so an overlay waiting
|
|
# behind a live prompt doesn't churn that prompt's repaints for nothing.
|
|
if self._overlay_visible():
|
|
self.invalidate()
|
|
|
|
ticker = asyncio.ensure_future(animate())
|
|
try:
|
|
yield overlay
|
|
finally:
|
|
ticker.cancel()
|
|
try:
|
|
await ticker
|
|
except asyncio.CancelledError:
|
|
pass
|
|
except Exception: # noqa: BLE001 - a cosmetic overlay must never break a flow
|
|
pass
|
|
self._overlay = None
|
|
self.invalidate()
|
|
|
|
# --- application lifecycle ------------------------------------------------
|
|
|
|
async def run(self, main: Any) -> None:
|
|
"""Run ``main`` (the menu loop) inside the full-screen application.
|
|
|
|
Starts the prompt_toolkit event loop, drives ``main`` as a background task on that
|
|
same loop, and exits the application when ``main`` returns. Any exception from
|
|
``main`` is re-raised after the loop unwinds.
|
|
|
|
Args:
|
|
main: The coroutine driving the session (typically the menu loop).
|
|
"""
|
|
self._app = self._build_app()
|
|
box: dict[str, BaseException] = {}
|
|
|
|
async def driver() -> None:
|
|
try:
|
|
await main
|
|
except BaseException as exc: # noqa: BLE001 - re-raised after the app unwinds
|
|
box["exc"] = exc
|
|
finally:
|
|
if self._app is not None and not self._app.is_done:
|
|
self._app.exit()
|
|
|
|
def pre_run() -> None:
|
|
asyncio.ensure_future(driver())
|
|
|
|
# Don't let prompt_toolkit install its own loop exception handler: on any stray
|
|
# background-task error it prints a traceback and a "Press ENTER to continue..."
|
|
# prompt straight over the full-screen UI. With it disabled, asyncio's default
|
|
# handler logs such errors to the ``asyncio`` logger instead, which is routed to the
|
|
# file log (see :func:`meshterm.persistence.logging.configure_logging`) and never
|
|
# touches the screen. Errors from ``main`` still propagate via ``driver``/``box``.
|
|
await self._app.run_async(pre_run=pre_run, set_exception_handler=False)
|
|
if "exc" in box:
|
|
raise box["exc"]
|
|
|
|
def _build_app(self) -> Application:
|
|
"""Construct the prompt_toolkit application, layout, and key bindings."""
|
|
base_control = FormattedTextControl(self._render_base, focusable=True)
|
|
base_window = Window(base_control, always_hide_cursor=True)
|
|
float_window = Window(
|
|
FormattedTextControl(self._render_float), always_hide_cursor=True
|
|
)
|
|
# The busy overlay is the last float, so it draws on top of the dialog float — the
|
|
# top of the z-order. It is a content-sized window (dont_extend_*) with no anchors, so
|
|
# the FloatContainer centres just its ring box over the screen rather than blanking it.
|
|
overlay_window = Window(
|
|
FormattedTextControl(self._render_overlay),
|
|
always_hide_cursor=True,
|
|
dont_extend_width=True,
|
|
dont_extend_height=True,
|
|
)
|
|
root = FloatContainer(
|
|
content=base_window,
|
|
floats=[
|
|
Float(
|
|
ConditionalContainer(
|
|
float_window, filter=Condition(self._has_float)
|
|
)
|
|
),
|
|
Float(
|
|
ConditionalContainer(
|
|
overlay_window, filter=Condition(self._overlay_visible)
|
|
)
|
|
),
|
|
],
|
|
)
|
|
return Application(
|
|
layout=Layout(root, focused_element=base_window),
|
|
key_bindings=self._key_bindings(),
|
|
full_screen=True,
|
|
mouse_support=False,
|
|
refresh_interval=1.0, # keep the live monitor counter in the header ticking
|
|
input=self._input,
|
|
output=self._output,
|
|
)
|
|
|
|
# --- rendering -----------------------------------------------------------
|
|
|
|
def _size(self) -> tuple[int, int]:
|
|
"""Return the current (cols, rows) of the terminal."""
|
|
size = self._app.output.get_size() # type: ignore[union-attr]
|
|
return max(20, size.columns), max(6, size.rows)
|
|
|
|
def base_body_size(self) -> tuple[int, int]:
|
|
"""Return the ``(width, height)`` in cells available to the base screen's body.
|
|
|
|
Mirrors the layout math in :func:`~meshterm.ui.tui.frame.compose_base` so a
|
|
full-screen screen (e.g. the map) can size its own content to fill the frame exactly,
|
|
without waiting a repaint to learn its height.
|
|
|
|
Returns:
|
|
The inner content width and the body viewport height, both in character cells.
|
|
"""
|
|
from .render import render_lines
|
|
|
|
cols, rows = self._size()
|
|
header_h = len(render_lines(self._header(), cols, no_wrap=True))
|
|
viewport = max(1, rows - header_h - 1 - 2) # minus footer(1) and panel border(2)
|
|
return cols - 4, viewport
|
|
|
|
def _base_screen(self) -> Optional[Screen]:
|
|
"""The screen drawn as the background (parent of a floating dialog, else the top)."""
|
|
if not self._stack:
|
|
return None
|
|
if self._has_float() and len(self._stack) >= 2:
|
|
return self._stack[-2]
|
|
return self._stack[-1]
|
|
|
|
def _has_float(self) -> bool:
|
|
"""Whether the top screen should be drawn as a centered dialog over the base."""
|
|
return len(self._stack) >= 2 and bool(getattr(self.top, "floating", False))
|
|
|
|
def _render_base(self) -> ANSI:
|
|
"""Render the persistent frame around the background screen."""
|
|
cols, rows = self._size()
|
|
base = self._base_screen()
|
|
if base is None:
|
|
return ANSI("")
|
|
scrub = base.consume_edge_scrub()
|
|
if scrub:
|
|
self._scrub_right_columns(scrub)
|
|
# A chromeless base (the startup splash) forgoes the header/footer bars and is
|
|
# centered under its banner instead of stretched across the terminal.
|
|
if not base.chrome:
|
|
return ANSI(frame.compose_startup(base, cols, rows))
|
|
footer = self.top.footer_hint if self.top else base.footer_hint
|
|
return ANSI(frame.compose_base(self._header(), base, footer, cols, rows))
|
|
|
|
def _render_float(self) -> ANSI:
|
|
"""Render the top screen as a centered dialog (only when floating)."""
|
|
if not self._has_float() or self.top is None:
|
|
return ANSI("")
|
|
cols, rows = self._size()
|
|
return ANSI(frame.compose_dialog(self.top, cols, rows))
|
|
|
|
def _overlay_visible(self) -> bool:
|
|
"""Whether the busy overlay should be painted this frame.
|
|
|
|
Gated on an empty screen stack so the ring only appears in the "black screen" gaps a
|
|
device operation opens between screens (a menu navigation before the tool's first
|
|
prompt, say) and never buries a dialog the user is meant to be reading. It also stays
|
|
unpainted through the overlay's initial hold (:attr:`BusyOverlay.brightness` is 0), so
|
|
an operation that finishes within the hold shows nothing and never flashes.
|
|
"""
|
|
return self._overlay is not None and not self._stack and self._overlay.brightness > 0
|
|
|
|
def _render_overlay(self) -> ANSI:
|
|
"""Render the busy overlay's ring (only when :meth:`_overlay_visible`)."""
|
|
if self._overlay is None:
|
|
return ANSI("")
|
|
return ANSI(self._overlay.render())
|
|
|
|
# --- input ---------------------------------------------------------------
|
|
|
|
def _key_bindings(self) -> KeyBindings:
|
|
"""Build the global key bindings that dispatch normalized actions to the top."""
|
|
kb = KeyBindings()
|
|
|
|
def bind(key: Any, action: str) -> None:
|
|
@kb.add(key)
|
|
def _(event: Any, action: str = action) -> None: # noqa: ANN401
|
|
self._dispatch(action)
|
|
|
|
for key, action in _KEY_ACTIONS.items():
|
|
bind(key, action)
|
|
|
|
@kb.add(Keys.ControlC)
|
|
def _quit(event: Any) -> None: # noqa: ANN401
|
|
if self._app is not None:
|
|
self._app.exit()
|
|
|
|
@kb.add(Keys.Any)
|
|
def _typed(event: Any) -> None: # noqa: ANN401
|
|
data = event.data
|
|
if data and len(data) == 1 and data.isprintable():
|
|
self._dispatch("text", data)
|
|
|
|
return kb
|
|
|
|
def _dispatch(self, action: str, data: str = "") -> None:
|
|
"""Forward an action to the top screen and repaint."""
|
|
if self.top is not None:
|
|
self.top.handle(action, data)
|
|
self.invalidate()
|
|
|
|
|
|
__all__ = [
|
|
"TuiSession",
|
|
"Choice",
|
|
"Separator",
|
|
"SelectScreen",
|
|
"ReorderScreen",
|
|
"ScrollScreen",
|
|
]
|