xnano.input

def is_down(self, keys: KeyNames) -> bool:
    """
    Whether any of the keys or mouse buttons is held down.

    Args:
        keys: One key name such as ``'space'``, or several such as ``('a', 'left')``. A
            mouse button is ``'mouse_left'``, ``'mouse_right'`` or ``'mouse_middle'``.
            A key is spelled as in [`KeyName`][xnano.types.KeyName]; a chord such as
            ``'ctrl+s'`` or a modifier alone is not held input.

    Raises:
        TypeError: A name is not text.
        ValueError: A name is not a key or a mouse button, or is a chord or a modifier.
    """
    held = self.held_keys
    return any(name in held for name in _names(keys))

def axis(self, negative: KeyNames, positive: KeyNames) -> int:
    """
    ``-1``, ``0`` or ``1`` from a pair of keys: the negative one, neither or both, the
    positive one.

    Args:
        negative: The key or keys that push toward ``-1``.
        positive: The key or keys that push toward ``1``.

    Raises:
        TypeError: A name is not text.
        ValueError: A name is not a key or a mouse button, or is a chord or a modifier.
    """
    return int(self.is_down(positive)) - int(self.is_down(negative))

def direction(
    self,
    *,
    left: KeyNames = ('a', 'left'),
    right: KeyNames = ('d', 'right'),
    up: KeyNames = ('w', 'up'),
    down: KeyNames = ('s', 'down'),
) -> tuple[int, int]:
    """
    The way the arrow keys or ``wasd`` point, as ``(step_x, step_y)``.

    Each step is ``-1``, ``0`` or ``1``; ``y`` grows downward, like the screen.

    Args:
        left: The key or keys that mean left.
        right: The key or keys that mean right.
        up: The key or keys that mean up.
        down: The key or keys that mean down.

    Raises:
        TypeError: A name is not text.
        ValueError: A name is not a key or a mouse button, or is a chord or a modifier.
    """
    return self.axis(left, right), self.axis(up, down)

def get(self) -> _core.KeyEvent | None:
    """The key event being handled, or ``None`` when the event is not a key."""
    event = self._event
    return event.key if event is not None else None

def push(self, value: str | _core.KeyEvent) -> None:
    """
    Press a key on the canvas, as if it had been typed.

    The canvas's hooks hear it at its next step, whatever the input gates say.

    Args:
        value: A key name or chord such as ``'q'`` or ``'ctrl+s'``, or a
            [`KeyEvent`][xnano_core.KeyEvent].

    Raises:
        TypeError: ``value`` is neither text nor a key event.
        ValueError: ``value`` is text that does not name a key. The message suggests the
            closest key names.
    """
    if isinstance(value, _core.KeyEvent):
        self._canvas.push(
            _core.Event.key_press(_modifier_text(value), kind=value.kind)
        )
    else:
        if not isinstance(value, str):
            raise TypeError(
                f"keyboard.push takes a key name such as 'q' or 'ctrl+s', or a KeyEvent, "
                f'but got {value!r}. Pass the key as text: keyboard.push("q").'
            )
        from xnano._when import normalize_chord

        normalize_chord(value)
        self._canvas.push(_core.Event.key_press(value))

def get(self) -> _core.MouseEvent | None:
    """The mouse event being handled, or ``None`` for any other event and for the wheel."""
    event = self._event
    if event is None:
        return None
    mouse = event.mouse
    if mouse is None or mouse.kind == 'scroll':
        return None
    return mouse

def push(self, value: _core.MouseEvent | tuple[int, int]) -> None:
    """
    Move or click the mouse on the canvas, as if the person had.

    Args:
        value: A [`MouseEvent`][xnano_core.MouseEvent] of kind press, release, drag or
            move (or an [`Event`][xnano_core.Event] that holds one), or an ``(x, y)``
            pair, which moves the pointer to that cell. A ``context.scroll.push((x, y))``
            that follows turns the wheel at that cell.

    Raises:
        TypeError: The value is a mouse wheel event, which belongs to
            ``context.scroll.push``, or a pair that is not two whole numbers.
        ValueError: A number of the pair is outside the range of a cell number.
    """
    if isinstance(value, tuple):
        column, row = _cell_pair(value, 'mouse.push')
        state = self._canvas._input_state
        seen = None if state is None else state.pointer_cell
        event = _core.Event.mouse_event(column=column, row=row, kind='move')
        self._canvas._pushed_pointer = (
            (column, row),
            seen,
            self._canvas._time_source.frame,
        )
        self._canvas.push(event)
        return
    if isinstance(value, _core.Event):
        if value.mouse is None:
            raise TypeError(
                f'mouse.push takes a mouse event, but got a {value.kind!r} event. Push '
                f'it with canvas.push(event), or build a mouse event with '
                f'Event.mouse_event(...).'
            )
        value = value.mouse
    if not isinstance(value, _core.MouseEvent):
        raise TypeError(
            f'mouse.push takes a MouseEvent or an (x, y) pair, but got {value!r}.'
        )
    if value.kind == 'scroll':
        raise TypeError(
            'mouse.push cannot send a mouse wheel event, because the wheel belongs to '
            'scroll. Use context.scroll.push((x, y)) to scroll by that many steps.'
        )
    self._canvas.push(
        _core.Event.mouse_event(
            column=value.column, row=value.row, kind=value.kind, button=value.button
        )
    )

def get(self) -> _core.MouseEvent | None:
    """The wheel event being handled, or ``None`` for any other event."""
    event = self._event
    if event is None:
        return None
    mouse = event.mouse
    if mouse is None or mouse.kind != 'scroll':
        return None
    return mouse

def push(self, value: tuple[int, int] | _core.MouseEvent) -> None:
    """
    Turn the mouse wheel on the canvas, as if the person had.

    Args:
        value: The ``(x, y)`` steps to scroll by, at the cell the pointer was last seen
            at (a pointer moved with ``context.mouse.push`` counts as seen there at
            once), or a [`MouseEvent`][xnano_core.MouseEvent] of kind scroll.

    Raises:
        TypeError: The value is a mouse event that is not a wheel report, which belongs
            to ``context.mouse.push``, or a pair that is not two whole numbers.
        ValueError: A number of the pair is outside the range of a step count.
    """
    if isinstance(value, tuple):
        steps_x, steps_y = _cell_pair(
            value, 'scroll.push', description='steps of the wheel, such as (0, 1)'
        )
        state = self._canvas._input_state
        cell = None if state is None else state.pointer_cell
        pushed = self._canvas._pushed_pointer
        if (
            pushed is not None
            and pushed[1] == cell
            and pushed[2] == self._canvas._time_source.frame
        ):
            cell = pushed[0]
        column, row = cell if cell is not None else (0, 0)
    else:
        if not isinstance(value, _core.MouseEvent):
            raise TypeError(
                f'scroll.push takes a MouseEvent of kind scroll or an (x, y) pair of '
                f'steps, but got {value!r}.'
            )
        if value.kind != 'scroll':
            raise TypeError(
                f'scroll.push takes a mouse wheel event, but this is a {value.kind} '
                f'event. Use context.mouse.push(event) for presses, releases, drags and '
                f'moves.'
            )
        column, row = value.column, value.row
        steps_x, steps_y = value.scroll_x, value.scroll_y
    self._canvas.push(
        _core.Event.mouse_event(
            column=column, row=row, kind='scroll', scroll_x=steps_x, scroll_y=steps_y
        )
    )

def get(self) -> str | None:
    """The text that was pasted, or ``None`` when the event is not a paste."""
    event = self._event
    return event.pasted_text if event is not None else None

def push(self, value: str) -> None:
    """
    Paste text on the canvas, as if the person had.

    Args:
        value: The text to paste.

    Raises:
        TypeError: The value is not text.
    """
    if not isinstance(value, str):
        raise TypeError(
            f'clipboard.push takes the text to paste, but received {value!r}. Pass a str, '
            f"such as context.clipboard.push('hello')."
        )
    self._canvas.push(_core.Event.paste(value))