xnano.context

The attachment of a hook: the hook or component that is running right now.

context.plugin names that one attachment and nothing else. The hook itself is context.hook.

Attributes:

• hook –

  The hook this attachment belongs to.

• state (StateNamespace) –

  State that belongs to this attachment alone, read with get and written with push; see StateNamespace.

Create the attachment of a hook or component. Use context.plugin instead of calling this.

Parameters:

• hook (HookHandle[object, object]) –

  The hook or component driver that is running.

47
48
49
50
51
52
53
54
55

def __init__(self, hook: HookHandle[object, object]) -> None:
    """
    Create the attachment of a hook or component. Use ``context.plugin`` instead of
    calling this.

    Args:
        hook: The hook or component driver that is running.
    """
    self.hook = hook

state: StateNamespace

import xnano
from xnano_core import Event

with xnano.new(width=8, height=1) as canvas:

    @canvas.hook(on='key')
    def count(context: xnano.Context) -> None:
        state = context.plugin.state
        state.push('presses', state.get('presses', default=0) + 1)
        context.root.state.push('latest', state.get('presses'))

    canvas.push(Event.key_press('a'))
    canvas.push(Event.key_press('b'))
    canvas.deliver_events()
    assert canvas.state.get('latest') == 2

What a component read while it was evaluated: the record that decides when it runs again.

A component that read nothing that changes is evaluated once. One that read the time is evaluated again on every frame (or every beat for a playable), one that read the size when the screen is resized, and one that read an input when that input arrives.

Attributes:

• uses_time –

  Whether it read the clock, the event or the held keys.

• uses_size –

  Whether it read the size of the canvas or of a buffer.

• uses_deps –

  Whether it read the dependencies.

• input_kinds (set[str]) –

  The kinds of input it read: 'key', 'mouse', 'scroll' or 'paste'.

Start an empty record.

106
107
108
109
110
111

def __init__(self) -> None:
    """Start an empty record."""
    self.uses_time = False
    self.uses_size = False
    self.uses_deps = False
    self.input_kinds: set[str] = set()

is_dynamic: bool

Bases: Generic[DepsT_co, StateT_co]

What a hook is called with.

The context carries the event and live views of where the hook is attached. Its members are read when you use them, so a context costs almost nothing to receive. A generator hook receives a new context each time it resumes, so context.mouse.position is always the newest event's.

buffer, parent and root are live objects with concrete values: context.parent.width is an int, and context.buffer has the verbs of a placement (move, up, down, left and right). On a placement or canvas themselves, parent and root are formula scopes whose members are expressions, such as placement.parent.width.

keyboard, mouse, scroll and clipboard are always there; each member is None (or 0 for the wheel) unless the event the hook is handling is of that kind. Each has get() and push(value).

Attributes:

• canvas (Canvas[DepsT_co, StateT_co]) –

  The root canvas the hook belongs to.

• event (Event | TerminalStateChange | Frame | Update | None) –

  The event, a Frame for hook(on='frame'), an Update for hook(on='tick'), a TerminalStateChange for hook(on='state'), or None when no event caused the call.

• hook (HookHandle[object, object]) –

  The registration, so the hook can call hook.remove().

• keyboard (KeyboardInput) –

  The key of the event, with key, kind and modifiers.

• mouse (MouseInput) –

  The mouse button or movement of the event, with position, button, kind and is_down.

• scroll (ScrollInput) –

  The wheel steps of the event, x and y.

• clipboard (ClipboardInput) –

  The pasted text of the event.

• buffer (Placement[object, object] | Canvas[object, object]) –

  The placement (or the canvas) the hook is attached to.

• parent (Placement[object, object] | Canvas[object, object]) –

  What contains the placement; the canvas itself for a hook on the canvas.

• root (Canvas[DepsT_co, StateT_co]) –

  The root canvas.

• plugin (Plugin) –

  The attachment of the hook that is running.

• deps (DepsT_co) –

  The dependencies given to new(deps=...).

• fx (EffectController) –

  Applies effects to the hook's buffer while the hook is active.

• time (Time) –

  The canvas's Time.

• audio (AudioDevice) –

  The canvas's AudioDevice.

• cursor (Cursor) –

  The canvas's cursor.

• size (Size) –

  The canvas's size in cells.

• input (Input) –

  The keys and mouse buttons held down right now.

Examples:

import xnano
from xnano_core import Event

with xnano.new(width=20, height=3) as canvas:
    label = canvas.write('hi', x=2)
    heard = []

    @label.hook(on='mouse', when="mouse.kind == 'press'")
    def pressed(context: xnano.Context) -> None:
        heard.append((context.mouse.position.x, context.buffer.x))

    canvas.push(Event.mouse_event(column=3, row=0, kind='press', button='left'))
    canvas.deliver_events()
    assert heard == [(3, 2)]

Create a context. The runtime does this for you; hooks receive one.

Parameters:

• canvas (Canvas[DepsT_co, StateT_co]) –

  The root canvas.

• owner (Canvas[object, object] | Placement[object, object]) –

  The canvas or placement the hook is attached to.

• hook (HookHandle[object, object]) –

  The hook that is called.

• event (Event | TerminalStateChange | Frame | Update | None) –

  The event, or None.

• core (CoreContext | None) –

  The runtime's context for the event, or None.

• log (ReadLog | None, default: None ) –

  Where to record what is read, for a component; None for a hook.

Methods:

• local –

  Convert a cell of the screen into a cell of the hook's buffer.

195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220

def __init__(
    self,
    canvas: Canvas[DepsT_co, StateT_co],
    owner: Canvas[object, object] | Placement[object, object],
    hook: HookHandle[object, object],
    event: _core.Event | _core.TerminalStateChange | Frame | Update | None,
    core: _core.CoreContext | None,
    log: ReadLog | None = None,
) -> None:
    """
    Create a context. The runtime does this for you; hooks receive one.

    Args:
        canvas: The root canvas.
        owner: The canvas or placement the hook is attached to.
        hook: The hook that is called.
        event: The event, or ``None``.
        core: The runtime's context for the event, or ``None``.
        log: Where to record what is read, for a component; ``None`` for a hook.
    """
    self.canvas = canvas
    self._owner = owner
    self.hook = hook
    self._event = event
    self._core = core
    self._log = log

canvas: Canvas[DepsT_co, StateT_co] = canvas

hook: HookHandle[object, object] = hook

event: Event | TerminalStateChange | Frame | Update | None

keyboard: KeyboardInput

mouse: MouseInput

scroll: ScrollInput

clipboard: ClipboardInput

buffer: Placement[object, object] | Canvas[object, object]

parent: Placement[object, object] | Canvas[object, object]

root: Canvas[DepsT_co, StateT_co]

plugin: Plugin

deps: DepsT_co

fx: EffectController

time: Time

audio: AudioDevice

cursor: Cursor

size: Size

input: Input

local(point: Point) -> Point

import xnano
from xnano_core import Point

with xnano.new(width=20, height=4) as canvas:
    placement = canvas.write('hi', x=10, y=1)

    @placement.hook(on='mouse')
    def pressed(context: xnano.Context) -> None:
        if context.mouse.position is not None:
            context.local(context.mouse.position)

    assert placement.local(Point(11, 1)) == Point(1, 0)

353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378

def local(self, point: _core.Point) -> _core.Point:
    """
    Convert a cell of the screen into a cell of the hook's buffer.

    Args:
        point: A cell in screen coordinates, such as ``context.mouse.position``.

    Examples:
        ```python
        import xnano
        from xnano_core import Point

        with xnano.new(width=20, height=4) as canvas:
            placement = canvas.write('hi', x=10, y=1)

            @placement.hook(on='mouse')
            def pressed(context: xnano.Context) -> None:
                if context.mouse.position is not None:
                    context.local(context.mouse.position)

            assert placement.local(Point(11, 1)) == Point(1, 0)
        ```
    """
    point = check_point(point)
    bounds = self._owner._buffer._absolute_bounds
    return _core.Point(point.x - bounds.x, point.y - bounds.y)

One frame of a canvas's clock.

Attributes:

• canvas (Canvas[object, object]) –

  The canvas the frame belongs to.

• index (int) –

  The number of steps the canvas's clock has counted, which is Time.frame when the frame was made.

• elapsed_seconds (float) –

  Seconds on the canvas's clock.

• delta_seconds (float) –

  Seconds since the previous frame (0.0 for the first).

• area (Rectangle) –

  The rectangle the frame is drawn into, in cells.

canvas: Canvas[object, object]

index: int

elapsed_seconds: float

delta_seconds: float

area: Rectangle

One step of a simulation, which runs separately from drawing.

Attributes:

• canvas (Canvas[object, object]) –

  The canvas the update belongs to.

• elapsed_seconds (float) –

  Seconds on the update's clock.

• delta_seconds (float) –

  Seconds this update advances.

• is_fixed_step (bool) –

  Whether the update runs at a fixed rate.

canvas: Canvas[object, object]

elapsed_seconds: float

delta_seconds: float

is_fixed_step: bool