Skip to content

xnano.device

xnano.device

xnano.device

Control the title, display modes, clipboard, and viewport of a runtime.

Flags and title are always tracked locally, so device behaves the same for a live or an offscreen runtime (tests, and every web visitor's session). Only a live runtime issues the real terminal escape codes; an offscreen runtime must not, or it would write control sequences to whatever process owns stdout (wrong for a headless web server) — and enable_raw_mode raises OSError outright when there is no real terminal to configure.

Classes:

  • Device –

    Control device settings for a Runtime session.

Attributes:

ClearType module-attribute 

ClearType: TypeAlias = Literal[
    "all",
    "purge",
    "from_cursor_down",
    "from_cursor_up",
    "current_line",
    "until_new_line",
]

How much of the terminal display Device.clear should erase.

Values

"all": The entire visible screen. "purge": The screen and its scrollback history. "from_cursor_down": From the caret to the bottom of the screen. "from_cursor_up": From the top of the screen to the caret. "current_line": Only the caret's current line. "until_new_line": From the caret to the end of its line.

Device 

Device(runtime: 'Runtime')

Control device settings for a Runtime session.

Title, clear, size, scroll, clipboard, raw mode, alternate screen, mouse capture, and related flags. Obtained from runtime.device — do not construct this class yourself.

Attributes:

Example

from xnano.core.runtime import Runtime runtime = Runtime.offscreen(20, 4, title="Example") runtime.device.size.width 20 runtime.close()

Methods:

Source code in xnano/device.py 
106
107
108
109
110
111
112
113
114
115
def __init__(self, runtime: "Runtime") -> None:
    self._runtime = runtime
    self._raw_mode = False
    self._alternate_screen = False
    self._line_wrap = True
    self._mouse_capture = False
    self._bracketed_paste = False
    self._focus_change = False
    self._synchronized_updates = False
    self._title: str | None = None

raw_mode property writable 

raw_mode: bool

Whether raw input mode is enabled.

alternate_screen property writable 

alternate_screen: bool

Whether the alternate screen buffer is active.

line_wrap property writable 

line_wrap: bool

Whether automatic line wrapping is enabled.

mouse_capture property writable 

mouse_capture: bool

Whether mouse events are captured.

bracketed_paste property writable 

bracketed_paste: bool

Whether bracketed paste mode is enabled.

focus_change property writable 

focus_change: bool

Whether OS-level terminal focus change events are enabled.

synchronized_updates property writable 

synchronized_updates: bool

Whether synchronized output updates are enabled.

title property writable 

title: str | None

Window/page title last set on this device, if any.

size property 

size: Size

Current terminal viewport size in cells.

clear 

clear(kind: ClearType = 'all') -> None

Clear the terminal display.

Source code in xnano/device.py 
241
242
243
244
def clear(self, kind: ClearType = "all") -> None:
    """Clear the terminal display."""
    if self._is_live():
        self._session.clear(_NATIVE_CLEAR_TYPES[kind])

scroll_up 

scroll_up(lines: int = 1) -> None

Scroll the viewport up by lines.

Source code in xnano/device.py 
246
247
248
249
def scroll_up(self, lines: int = 1) -> None:
    """Scroll the viewport up by ``lines``."""
    if self._is_live():
        self._session.scroll_up(lines)

scroll_down 

scroll_down(lines: int = 1) -> None

Scroll the viewport down by lines.

Source code in xnano/device.py 
251
252
253
254
def scroll_down(self, lines: int = 1) -> None:
    """Scroll the viewport down by ``lines``."""
    if self._is_live():
        self._session.scroll_down(lines)

copy_to_clipboard 

copy_to_clipboard(text: str) -> bool

Copy text to the clipboard when supported.

Source code in xnano/device.py 
256
257
258
def copy_to_clipboard(self, text: str) -> bool:
    """Copy ``text`` to the clipboard when supported."""
    return False