Skip to content

xnano.context

xnano.context

xnano.context

Access the current event, application state, runtime, device, cursor, and layout from an event hook.

Classes:

  • Context –

    Values and controls available inside an event hook.

Context dataclass 

Context(
    event: "Event",
    terminal: "Runtime[StateT]",
    state: StateT,
    request: "Request | None" = None,
)

Bases: Generic[StateT]

Values and controls available inside an event hook.

Use the event-specific shortcuts such as keyboard_event and mouse_event, read or update application state, move focus, or access the current cursor, device, actions, and stage.

Attributes:

  • event ('Event') –

    Event that triggered the hook.

  • terminal ('Runtime[StateT]') –

    Terminal or runtime handling the event.

  • state (StateT) –

    Application state shared with the runtime.

  • host ('Runtime[StateT]') –

    Session handling the event.

  • runtime ('Runtime[StateT]') –

    Runtime handling the event.

  • surface (str) –

    Active presentation surface.

  • request ('Request | None') –

    HTTP request that triggered the hook, if any.

  • tick_event ('TickEventData | None') –

    Tick payload that triggered the hook, if any.

  • keyboard_event ('KeyboardEventData | None') –

    Keyboard payload that triggered the hook, if any.

  • mouse_event ('MouseEventData | None') –

    Mouse payload that triggered the hook, if any.

  • cursor ('Cursor') –

    Cursor controls for the active runtime.

  • device ('Device') –

    Device controls for the active runtime.

  • actions ('Actions') –

    Synthetic action performer.

  • stage ('Stage') –

    Current layout stage.

  • focused_group (str | None) –

    Name of the focused field group.

Example

def handle_key(ctx: Context[dict[str, int]]) -> None: ... if ctx.keyboard_event is not None: ... ctx.state["keys"] += 1

Methods:

  • get_state –

    Return the shared application state.

  • focus –

    Focus the field labeled group on any attached grid.

  • blur –

    Clear field focus on the active runtime.

  • is_focused –

    Return whether the field labeled group currently holds focus.

  • call_soon –

    Schedule callback to run on the UI thread before the next pump.

  • field_area –

    Return the last painted area for field name, if known.

  • scroll –

    Return a scroll handle for Field(scroll=...) labeled group.

  • get_scroll –

    Return scroll state for group, or None if it is unavailable.

  • with_event –

    Return a copy carrying a different event.

  • with_scope –

    Return a shallow copy with the given fields replaced.

  • has_clipboard_event –

    Return whether this context contains a clipboard event.

  • has_focus_event –

    Return whether this is a focus event.

  • has_keyboard_event –

    Return whether this is a keyboard event.

  • has_mouse_event –

    Return whether this is a mouse event.

  • has_resize_event –

    Return whether this is a resize event.

event instance-attribute 

event: 'Event'

Event that triggered the hook.

terminal instance-attribute 

terminal: 'Runtime[StateT]'

Terminal or offscreen session handling the event.

state instance-attribute 

state: StateT

Application state shared with the runtime.

request class-attribute instance-attribute 

request: 'Request | None' = None

HTTP request that triggered the hook, if any.

host property 

host: 'Runtime[StateT]'

Session handling the event.

runtime property 

runtime: 'Runtime[StateT]'

Runtime handling the event.

surface property 

surface: str

Presentation surface: "terminal", "web", or "offscreen".

tick_event property 

tick_event: 'TickEventData | None'

Tick payload when this context was triggered by a tick.

keyboard_event property 

keyboard_event: 'KeyboardEventData | None'

Keyboard sub-event when triggered by a keyboard event.

mouse_event property 

mouse_event: 'MouseEventData | None'

Mouse sub-event when triggered by a mouse event.

tick property 

tick: 'TickEventData | None'

Deprecated alias for :attr:tick_event.

keyboard property 

keyboard: 'KeyboardEventData | None'

Deprecated alias for :attr:keyboard_event.

mouse property 

mouse: 'MouseEventData | None'

Deprecated alias for :attr:mouse_event.

cursor property 

cursor: 'Cursor'

Cursor / caret controls for the active runtime.

device property 

device: 'Device'

Device controls for the active runtime.

actions property 

actions: 'Actions'

Perform synthetic input and requests.

stage property 

stage: 'Stage'

Layout map and cell-level paint helpers.

render_size property 

render_size: 'Breakpoint'

Current viewport breakpoint tier.

The same value grid_render_<size> / compose_<size> dispatch on — one of "extra_small", "small", "medium", "large", "extra_large" — derived from the live window width. Read it from any hook to branch on size without declaring a per-tier render method.

focused_group property 

focused_group: str | None

group of the currently focused field, or None.

get_state 

get_state() -> StateT

Return the shared application state.

Raises:

  • RuntimeError –

    If no state was attached to this context.

Source code in xnano/context.py 
137
138
139
140
141
142
143
144
145
def get_state(self) -> StateT:
    """Return the shared application state.

    Raises:
        RuntimeError: If no state was attached to this context.
    """
    if self.state is None:
        raise RuntimeError("No state attached to this context.")
    return self.state

focus 

focus(group: str) -> bool

Focus the field labeled group on any attached grid.

Source code in xnano/context.py 
167
168
169
170
171
172
def focus(self, group: str) -> bool:
    """Focus the field labeled ``group`` on any attached grid."""
    focus_group = getattr(self.terminal, "focus_group", None)
    if callable(focus_group):
        return bool(focus_group(group))
    return bool(self.terminal.focus(group))

blur 

blur() -> None

Clear field focus on the active runtime.

Source code in xnano/context.py 
174
175
176
177
178
179
180
181
182
def blur(self) -> None:
    """Clear field focus on the active runtime."""
    blur_field = getattr(self.terminal, "blur_field", None)
    if callable(blur_field):
        blur_field()
        return
    blur = getattr(self.terminal, "blur", None)
    if callable(blur):
        blur()

is_focused 

is_focused(group: str) -> bool

Return whether the field labeled group currently holds focus.

Source code in xnano/context.py 
203
204
205
def is_focused(self, group: str) -> bool:
    """Return whether the field labeled ``group`` currently holds focus."""
    return self.focused_group == group

call_soon 

call_soon(
    callback: "Callable[..., Any]", *args: Any
) -> None

Schedule callback to run on the UI thread before the next pump.

The thread-safe bridge for updating grid state from a worker thread: the callback runs on the runtime's own thread, so it can freely mutate components/fields without racing the renderer.

Source code in xnano/context.py 
207
208
209
210
211
212
213
214
def call_soon(self, callback: "Callable[..., Any]", *args: Any) -> None:
    """Schedule ``callback`` to run on the UI thread before the next pump.

    The thread-safe bridge for updating grid state from a worker thread:
    the callback runs on the runtime's own thread, so it can freely mutate
    components/fields without racing the renderer.
    """
    self.terminal.call_soon(callback, *args)

field_area 

field_area(name: str) -> 'Area | None'

Return the last painted area for field name, if known.

Reads the always-on layout map so viewports and chrome math can use measured slot sizes instead of guessing.

Source code in xnano/context.py 
216
217
218
219
220
221
222
def field_area(self, name: str) -> "Area | None":
    """Return the last painted area for field ``name``, if known.

    Reads the always-on layout map so viewports and chrome math can use
    measured slot sizes instead of guessing.
    """
    return self.stage.get_area(name)

scroll 

scroll(group: str) -> 'ScrollHandle | None'

Return a scroll handle for Field(scroll=...) labeled group.

Source code in xnano/context.py 
224
225
226
227
228
def scroll(self, group: str) -> "ScrollHandle | None":
    """Return a scroll handle for ``Field(scroll=...)`` labeled ``group``."""
    from xnano.utils.focus import scroll_handle_for_group

    return scroll_handle_for_group(self.terminal, group)

get_scroll 

get_scroll(group: str) -> 'ScrollHandle | None'

Return scroll state for group, or None if it is unavailable.

Source code in xnano/context.py 
230
231
232
def get_scroll(self, group: str) -> "ScrollHandle | None":
    """Return scroll state for ``group``, or ``None`` if it is unavailable."""
    return self.scroll(group)

with_event 

with_event(event: 'Event') -> 'Context[StateT]'

Return a copy carrying a different event.

Source code in xnano/context.py 
234
235
236
def with_event(self, event: "Event") -> "Context[StateT]":
    """Return a copy carrying a different event."""
    return dataclasses.replace(self, event=event)

with_scope 

with_scope(**kwargs: Any) -> 'Context[StateT]'

Return a shallow copy with the given fields replaced.

Source code in xnano/context.py 
238
239
240
def with_scope(self, **kwargs: Any) -> "Context[StateT]":
    """Return a shallow copy with the given fields replaced."""
    return dataclasses.replace(self, **kwargs)

has_clipboard_event 

has_clipboard_event() -> bool

Return whether this context contains a clipboard event.

Source code in xnano/context.py 
242
243
244
def has_clipboard_event(self) -> bool:
    """Return whether this context contains a clipboard event."""
    return self.event.is_clipboard_event()

has_focus_event 

has_focus_event() -> bool

Return whether this is a focus event.

Source code in xnano/context.py 
246
247
248
def has_focus_event(self) -> bool:
    """Return whether this is a focus event."""
    return self.event.is_focus_event()

has_keyboard_event 

has_keyboard_event() -> bool

Return whether this is a keyboard event.

Source code in xnano/context.py 
250
251
252
def has_keyboard_event(self) -> bool:
    """Return whether this is a keyboard event."""
    return self.event.is_keyboard_event()

has_mouse_event 

has_mouse_event() -> bool

Return whether this is a mouse event.

Source code in xnano/context.py 
254
255
256
def has_mouse_event(self) -> bool:
    """Return whether this is a mouse event."""
    return self.event.is_mouse_event()

has_resize_event 

has_resize_event() -> bool

Return whether this is a resize event.

Source code in xnano/context.py 
258
259
260
def has_resize_event(self) -> bool:
    """Return whether this is a resize event."""
    return self.event.is_resize_event()