Files
MeshTerm/meshterm/ui/tui/spinner.py
T
Jean-Pierre MartineauandClaude Opus 5.5 d6d49df0a2 Docstrings and comments of meshterm/ui/tui are in ASD-STE100
The same rewrite as for the core package. A navigation entry is now
"a screen on the stack", the visible part of a page is its viewport, and
the visible rows of a ListWindow are its list window. Two statements now
agree with the theme: the selected chip style is a grey fill.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-10-06 04:17:05 -04:00

95 lines
3.8 KiB
Python

# SPDX-License-Identifier: Apache-2.0
"""A reusable text spinner: one animated glyph for a "working" indicator.
A small animation helper that does not depend on a screen. It holds a cycle of glyphs, one
for each animation step, and a current position. A caller moves it forward with
:meth:`tick` (usually from an animation timer). Then the caller reads the current
animation step as a bare glyph, or as a styled Rich :class:`~rich.text.Text`. The busy
splash uses it. But it is independent of all screens on purpose, so that each "working"
indicator in the toolkit can use the same animation.
"""
from __future__ import annotations
from rich.text import Text
from ...platforms import get_platform
def spinner_interval() -> float:
"""The seconds that a "working" animation waits between animation steps, on this platform.
This function is the only source of the spin rate of the app. Each animated wait sleeps
for this value, not for its own constant. Thus the rate is one decision of the
platform, not five copies that become different over time. The function is called at
each tick, and its value is not read into a module constant. A constant keeps the
platform that was active at import time, and that is always the default platform
(``set_platform`` runs later, in the CLI callback: refer to :mod:`meshterm.platforms`).
Returns:
The :attr:`~meshterm.platforms.Platform.spinner_tick_s` of the active platform.
"""
return get_platform().spinner_tick_s
class Spinner:
"""An animated spinner that cycles through a set of glyphs, one for each animation step.
Attributes:
style: The Rich style that :meth:`text` applies to the current glyph.
"""
#: The default animation steps, in Braille dots: a smooth rotation in one cell.
BRAILLE = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
#: A plain ASCII cycle for terminals or fonts that have no Braille glyphs.
LINE = "|/-\\"
def __init__(self, frames: str | None = None, *, style: str = "accent") -> None:
"""Create a spinner at its first animation step.
Args:
frames: The glyphs to cycle through, one for each animation step. The default
is the cycle of the active platform: :data:`BRAILLE` where effects are on,
and :data:`LINE` (four animation steps) where effects are off. The default
is resolved here, at construction. Thus a spinner that is built after
``set_platform`` gets the correct cycle, and never decides again while it
spins.
style: The Rich style that :meth:`text` applies to the current glyph.
"""
if frames is None:
frames = self.BRAILLE if get_platform().effects else self.LINE
if not frames:
raise ValueError("a spinner needs at least one frame")
self._frames = frames
self.style = style
self._index = 0
@property
def frame(self) -> str:
"""The glyph of the current animation step."""
return self._frames[self._index]
@property
def frames(self) -> str:
"""The glyphs of the full cycle of animation steps, in order."""
return self._frames
def tick(self) -> None:
"""Go to the next animation step. After the end of the cycle, go back to the start."""
self._index = (self._index + 1) % len(self._frames)
def reset(self) -> None:
"""Put the spinner back at its first animation step."""
self._index = 0
def text(self, style: str | None = None) -> Text:
"""Return the current glyph as a styled Rich :class:`~rich.text.Text`.
Args:
style: A style to use instead of the spinner's own :attr:`style`.
Returns:
The current glyph, styled.
"""
return Text(self.frame, style=self.style if style is None else style)