Skip to content

xnano.cursor

xnano.cursor

xnano.cursor

Show, hide, style, and move the cursor in live or offscreen sessions.

Position, visibility, and style are always tracked locally, so the caret state a Frame snapshot reports is correct 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.

Classes:

  • Cursor –

    Show, hide, style, and move the caret for a Runtime session.

Attributes:

CursorStyle module-attribute 

CursorStyle: TypeAlias = Literal[
    "default",
    "blinking_block",
    "steady_block",
    "blinking_underline",
    "steady_underline",
    "blinking_bar",
    "steady_bar",
]

The caret rendering style.

Values

"default": The terminal's default caret style. "blinking_block": A blinking block. (█) "steady_block": A steady (non-blinking) block. (█) "blinking_underline": A blinking underline. (_) "steady_underline": A steady (non-blinking) underline. (_) "blinking_bar": A blinking vertical bar. (|) "steady_bar": A steady (non-blinking) vertical bar. (|)

Cursor 

Cursor(runtime: 'Runtime')

Show, hide, style, and move the caret for a Runtime session.

Obtained from runtime.cursor — do not construct this class yourself.

Attributes:

Example

from xnano.core.runtime import Runtime runtime = Runtime.offscreen(20, 4) runtime.cursor.position = (3, 1) runtime.cursor.position (3, 1) runtime.close()

Methods:

  • get_position –

    The locally tracked (x, y) caret position.

  • move –

    Move the caret to (x, y).

  • move_up –

    Move the caret up by count rows.

  • move_down –

    Move the caret down by count rows.

  • move_left –

    Move the caret left by count columns.

  • move_right –

    Move the caret right by count columns.

  • save –

    Save the current caret position.

  • restore –

    Restore the previously saved caret position.

  • enable_blinking –

    Enable caret blinking.

  • disable_blinking –

    Disable caret blinking.

Source code in xnano/cursor.py 
78
79
80
81
82
83
84
85
def __init__(self, runtime: "Runtime") -> None:
    self._runtime = runtime
    self._visible = True
    self._style: CursorStyle = "default"
    self._x = 0
    self._y = 0
    self._saved_position: Coordinate | None = None
    self._blinking = True

visible property writable 

visible: bool

Whether the caret is currently shown.

style property writable 

style: CursorStyle

The caret's rendering style.

position property writable 

position: Coordinate

The current (x, y) caret position.

get_position 

get_position() -> Coordinate

The locally tracked (x, y) caret position.

Source code in xnano/cursor.py 
140
141
142
def get_position(self) -> Coordinate:
    """The locally tracked ``(x, y)`` caret position."""
    return (self._x, self._y)

move 

move(x: int, y: int) -> None

Move the caret to (x, y).

Source code in xnano/cursor.py 
153
154
155
156
157
def move(self, x: int, y: int) -> None:
    """Move the caret to ``(x, y)``."""
    self._x, self._y = x, y
    if self._is_live():
        self._session.move_cursor_to(x, y)

move_up 

move_up(count: int = 1) -> None

Move the caret up by count rows.

Source code in xnano/cursor.py 
159
160
161
162
def move_up(self, count: int = 1) -> None:
    """Move the caret up by ``count`` rows."""
    self._y = max(0, self._y - count)
    self.move(self._x, self._y)

move_down 

move_down(count: int = 1) -> None

Move the caret down by count rows.

Source code in xnano/cursor.py 
164
165
166
167
def move_down(self, count: int = 1) -> None:
    """Move the caret down by ``count`` rows."""
    self._y += count
    self.move(self._x, self._y)

move_left 

move_left(count: int = 1) -> None

Move the caret left by count columns.

Source code in xnano/cursor.py 
169
170
171
172
def move_left(self, count: int = 1) -> None:
    """Move the caret left by ``count`` columns."""
    self._x = max(0, self._x - count)
    self.move(self._x, self._y)

move_right 

move_right(count: int = 1) -> None

Move the caret right by count columns.

Source code in xnano/cursor.py 
174
175
176
177
def move_right(self, count: int = 1) -> None:
    """Move the caret right by ``count`` columns."""
    self._x += count
    self.move(self._x, self._y)

save 

save() -> None

Save the current caret position.

Source code in xnano/cursor.py 
179
180
181
182
183
def save(self) -> None:
    """Save the current caret position."""
    self._saved_position = (self._x, self._y)
    if self._is_live():
        self._session.save_cursor_position()

restore 

restore() -> None

Restore the previously saved caret position.

Source code in xnano/cursor.py 
185
186
187
188
189
190
def restore(self) -> None:
    """Restore the previously saved caret position."""
    if self._saved_position is not None:
        self._x, self._y = self._saved_position
    if self._is_live():
        self._session.restore_cursor_position()

enable_blinking 

enable_blinking() -> None

Enable caret blinking.

Source code in xnano/cursor.py 
192
193
194
195
196
197
198
199
200
201
202
203
204
205
def enable_blinking(self) -> None:
    """Enable caret blinking."""
    self._blinking = True
    if self._style in {"steady_block", "steady_underline", "steady_bar"}:
        self._set_style(
            cast(
                CursorStyle,
                {
                    "steady_block": "blinking_block",
                    "steady_underline": "blinking_underline",
                    "steady_bar": "blinking_bar",
                }[self._style],
            )
        )

disable_blinking 

disable_blinking() -> None

Disable caret blinking.

Source code in xnano/cursor.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def disable_blinking(self) -> None:
    """Disable caret blinking."""
    self._blinking = False
    if self._style.startswith("blinking_"):
        self._set_style(
            cast(
                CursorStyle,
                {
                    "blinking_block": "steady_block",
                    "blinking_underline": "steady_underline",
                    "blinking_bar": "steady_bar",
                }[self._style],
            )
        )