xnano.events

Base for event payloads.

Attributes:

• type (EventDataType) –

  Payload category.

type: EventDataType = 'other'

Bases: AbstractEventData

Keyboard input and its normalized binding.

Attributes:

• type (Literal['keyboard']) –

  Payload category, always "keyboard".

• binding (KeyboardBinding) –

  Normalized binding such as "ctrl+s".

• key (KeyboardKey | str | None) –

  Primary key.

• kind (KeyboardEventKind) –

  Keyboard transition.

• modifiers (list[KeyboardModifier]) –

  Modifier keys held during the event.

• character (str | None) –

  Typed character, when available.

Examples:

event = KeyboardEventData.from_binding("ctrl+s")
if event.matches("ctrl+s"):
    save()

type: Literal['keyboard'] = 'keyboard'

binding: KeyboardBinding

key: KeyboardKey | str | None

kind: KeyboardEventKind

modifiers: list[KeyboardModifier]

character: str | None

from_binding(
    binding: str,
    *,
    kind: KeyboardEventKind = "press",
    character: str | None = None
) -> "KeyboardEventData"

146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

@classmethod
def from_binding(
    cls,
    binding: str,
    *,
    kind: KeyboardEventKind = "press",
    character: str | None = None,
) -> "KeyboardEventData":
    """Create keyboard data from a binding string.

    Args:
        binding: Keyboard binding to synthesize.
        kind: Keyboard transition.
        character: Text character, when the binding represents one.

    Returns:
        Synthetic keyboard event data.
    """
    _, key = parse_binding_tuple(binding)
    if character is None:
        character = (
            key if len(key) == 1 else (" " if key == "space" else None)
        )
    return cls(_kind=kind, _binding=binding, _character=character)

matches(*bindings: KeyboardBinding) -> bool

243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

def matches(self, *bindings: KeyboardBinding) -> bool:
    """Return whether this event matches any binding.

    Bare modifiers (``"shift"``, ``"ctrl"``, ``"alt"``) match a
    modifier-only key press, not a modified key such as ``"shift+a"``.

    Args:
        *bindings: Candidate keyboard bindings.

    Returns:
        Whether at least one binding matches.
    """
    native_event: Any = self._native_event
    own = normalize_keyboard_binding(str(self.binding))
    for binding in bindings:
        modifiers, key = normalize_keyboard_binding(str(binding))
        if not modifiers and key in _MODIFIER_KEYS:
            if self._matches_bare_modifier(key):
                return True
            continue
        if native_event is not None:
            try:
                if CoreKeyBinding.parse(str(binding)).matches(
                    native_event
                ):
                    return True
            except Exception:
                continue
        elif (modifiers, key) == own:
            return True
    return False

Bases: AbstractEventData

Mouse input at a cell coordinate.

Attributes:

• kind (MouseEventKind) –

  Mouse transition.

• x (int) –

  Zero-based cell column.

• y (int) –

  Zero-based cell row.

• button (MouseButton) –

  Button involved in the transition.

• field (str | None) –

  Field under the pointer for synthetic or web input.

• group (str | None) –

  Field group under the pointer.

Examples:

event = MouseEventData(kind="press", x=12, y=4, button="left")

type: Literal['mouse'] = 'mouse'

kind: MouseEventKind

x: int

y: int

button: MouseButton = 'unknown'

field: str | None = None

group: str | None = None

Bases: AbstractEventData

New viewport dimensions.

Attributes:

• width (int) –

  Viewport width in cells.

• height (int) –

  Viewport height in cells.

type: Literal['resize'] = 'resize'

width: int

height: int

Bases: AbstractEventData

Text received from paste or clipboard input.

Attributes:

• text (str | None) –

  Pasted text, when available.

type: Literal['clipboard'] = 'clipboard'

text: str | None = None

Bases: AbstractEventData

Terminal or field focus transition.

Attributes:

• kind (FocusEventKind) –

  Focus transition.

• field (str | None) –

  Field name for field focus.

• group (str | None) –

  Shared focus group for field focus.

type: Literal['focus'] = 'focus'

kind: FocusEventKind

field: str | None = None

group: str | None = None

Bases: AbstractEventData

Elapsed time reported by the runtime clock.

Attributes:

• elapsed_ms (int) –

  Milliseconds since the previous tick.

type: Literal['tick'] = 'tick'

elapsed_ms: int = 0

Unified event produced by native input, web input, or an action.

Attributes:

• data (EventData) –

  Public event payload.

• type (EventDataType) –

  Payload category.

• keyboard_event (KeyboardEventData | None) –

  Keyboard payload, when present.

• mouse_event (MouseEventData | None) –

  Mouse payload, when present.

• resize_event (ResizeEventData | None) –

  Resize payload, when present.

• clipboard_event (ClipboardEventData | None) –

  Clipboard payload, when present.

• focus_event (FocusEventData | None) –

  Focus payload, when present.

• tick_event (TickEventData | None) –

  Tick payload, when present.

Examples:

event = Event.from_data(KeyboardEventData.from_binding("enter"))
if event.keyboard_event and event.keyboard_event.matches("enter"):
    submit()

data: EventData

type: EventDataType

keyboard_event: KeyboardEventData | None

keyboard_key: KeyboardKey | str | None

keyboard_event_kind: KeyboardEventKind | None

keyboard_modifiers: list[KeyboardModifier]

mouse_event: MouseEventData | None

mouse_position: tuple[int, int] | None

mouse_event_kind: MouseEventKind | None

mouse_button: MouseButton | None

resize_event: ResizeEventData | None

resize_size: tuple[int, int] | None

clipboard_event: ClipboardEventData | None

clipboard_text: str | None

focus_event: FocusEventData | None

tick_event: TickEventData | None

from_data(data: EventData) -> 'Event'

446
447
448
449
450
451
452
453
454
455
456

@classmethod
def from_data(cls, data: EventData) -> "Event":
    """Create an event from a synthetic payload.

    Args:
        data: Public event payload.

    Returns:
        Event wrapping the payload.
    """
    return cls(_event_data=data)

is_clipboard_event() -> bool

474
475
476

def is_clipboard_event(self) -> bool:
    """Return whether this is clipboard input."""
    return self.type == "clipboard"

is_focus_event() -> bool

478
479
480

def is_focus_event(self) -> bool:
    """Return whether this is a focus transition."""
    return self.type == "focus"

is_keyboard_event() -> bool

482
483
484

def is_keyboard_event(self) -> bool:
    """Return whether this is keyboard input."""
    return self.type == "keyboard"

is_mouse_event() -> bool

486
487
488

def is_mouse_event(self) -> bool:
    """Return whether this is mouse input."""
    return self.type == "mouse"

is_resize_event() -> bool

490
491
492

def is_resize_event(self) -> bool:
    """Return whether this is a viewport resize."""
    return self.type == "resize"

is_tick_event() -> bool

494
495
496

def is_tick_event(self) -> bool:
    """Return whether this is a runtime clock tick."""
    return self.type == "tick"