xnano.events

Something that happened: input, a resize, a timer or a frame.

Hooks and the runtime report everything as an event. Build events with the class methods to test code without a terminal.

Attributes:

• kind (EventKind) –

  What the event reports.

• timestamp_seconds (float) –

  Seconds on the runtime clock when the event happened.

• key (KeyEvent | None) –

  The key details of a key event, otherwise None.

• mouse (MouseEvent | None) –

  The mouse details of a mouse event, otherwise None.

• pasted_text (str | None) –

  The pasted text of a paste event, otherwise None.

• size (Size | None) –

  The new size of a resize event, otherwise None.

• timer_key (str | None) –

  The key of a timer event, otherwise None.

• custom_name (str | None) –

  The name of a custom event, otherwise None.

• custom_data (str | None) –

  The data of a custom event, otherwise None.

Examples:

event = Event.key_press('q')
assert event.kind == 'key'
assert event.key.key == 'q'
assert Event.resize(width=80, height=24).size == Size(80, 24)

Methods:

• key_press –

  A key event for a key name with optional +-joined modifiers.

• paste –

  A paste event.

• resize –

  A resize event.

• mouse_event –

  A mouse event.

• tick –

  Create a tick event, as a runtime with a tick interval reports.

• timer –

  Create a timer event for the timer called key.

• wake –

  Create a wake event, which only makes a runtime run an iteration.

• exit_requested –

  Create the event a runtime reports when the application is asked to exit.

• custom –

  Create an event your application defines.

• focus_gained –

  An event reporting that the terminal window gained focus.

• focus_lost –

  An event reporting that the terminal window lost focus.

kind: EventKind

timestamp_seconds: float

key: KeyEvent | None

mouse: MouseEvent | None

pasted_text: str | None

size: Size | None

timer_key: str | None

custom_name: str | None

custom_data: str | None

key_press(binding: str, *, kind: KeyEventKind = 'press') -> Event

event = Event.key_press('alt+enter')
assert event.key.key == 'enter'
assert event.key.modifiers == {'alt'}

1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748

@classmethod
def key_press(cls, binding: str, *, kind: KeyEventKind = 'press') -> Event:
    """
    A key event for a key name with optional ``+``-joined modifiers.

    Args:
        binding: The key, such as ``'q'``, ``'enter'`` or ``'ctrl+c'``.
        kind: Whether the key is pressed, repeated or released.

    Raises:
        ValueError: ``binding`` is not a valid key or ``kind`` is unknown.

    Examples:
        ```python
        event = Event.key_press('alt+enter')
        assert event.key.key == 'enter'
        assert event.key.modifiers == {'alt'}
        ```
    """

paste(text: str) -> Event

assert Event.paste('hello').pasted_text == 'hello'

1750
1751
1752
1753
1754
1755
1756
1757
1758
1759

@classmethod
def paste(cls, text: str) -> Event:
    """
    A paste event.

    Examples:
        ```python
        assert Event.paste('hello').pasted_text == 'hello'
        ```
    """

resize(*, width: int, height: int) -> Event

assert Event.resize(width=3, height=2).size.height == 2

1761
1762
1763
1764
1765
1766
1767
1768
1769
1770

@classmethod
def resize(cls, *, width: int, height: int) -> Event:
    """
    A resize event.

    Examples:
        ```python
        assert Event.resize(width=3, height=2).size.height == 2
        ```
    """

mouse_event(*, column: int, row: int, kind: MouseEventKind, button: MouseButton | None = None, scroll_x: int = 0, scroll_y: int = 0) -> Event

event = Event.mouse_event(column=0, row=0, kind='scroll', scroll_y=-1)
assert event.mouse.scroll_y == -1

sideways = Event.mouse_event(column=0, row=0, kind='scroll', scroll_x=2)
assert (sideways.mouse.scroll_x, sideways.mouse.scroll_y) == (2, 0)

1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802

@classmethod
def mouse_event(
    cls,
    *,
    column: int,
    row: int,
    kind: MouseEventKind,
    button: MouseButton | None = None,
    scroll_x: int = 0,
    scroll_y: int = 0,
) -> Event:
    """
    A mouse event.

    Args:
        column: The column under the pointer.
        row: The row under the pointer.
        kind: What the mouse did.
        button: The button involved in a press, release or drag.
        scroll_x: Horizontal scroll steps, negative for left and positive for right.
        scroll_y: Vertical scroll steps, negative for up and positive for down.

    Examples:
        ```python
        event = Event.mouse_event(column=0, row=0, kind='scroll', scroll_y=-1)
        assert event.mouse.scroll_y == -1

        sideways = Event.mouse_event(column=0, row=0, kind='scroll', scroll_x=2)
        assert (sideways.mouse.scroll_x, sideways.mouse.scroll_y) == (2, 0)
        ```
    """

tick() -> Event

assert Event.tick().kind == 'tick'

1804
1805
1806
1807
1808
1809
1810
1811
1812
1813

@classmethod
def tick(cls) -> Event:
    """
    Create a tick event, as a runtime with a tick interval reports.

    Examples:
        ```python
        assert Event.tick().kind == 'tick'
        ```
    """

timer(key: str) -> Event

assert Event.timer('blink').timer_key == 'blink'

1815
1816
1817
1818
1819
1820
1821
1822
1823
1824

@classmethod
def timer(cls, key: str) -> Event:
    """
    Create a timer event for the timer called ``key``.

    Examples:
        ```python
        assert Event.timer('blink').timer_key == 'blink'
        ```
    """

wake() -> Event

assert Event.wake().kind == 'wake'

1826
1827
1828
1829
1830
1831
1832
1833
1834
1835

@classmethod
def wake(cls) -> Event:
    """
    Create a wake event, which only makes a runtime run an iteration.

    Examples:
        ```python
        assert Event.wake().kind == 'wake'
        ```
    """

exit_requested() -> Event

assert Event.exit_requested().kind == 'exit_requested'

1837
1838
1839
1840
1841
1842
1843
1844
1845
1846

@classmethod
def exit_requested(cls) -> Event:
    """
    Create the event a runtime reports when the application is asked to exit.

    Examples:
        ```python
        assert Event.exit_requested().kind == 'exit_requested'
        ```
    """

custom(name: str, *, data: str | None = None) -> Event

event = Event.custom('volume_changed', data='40')
assert event.kind == 'custom'
assert (event.custom_name, event.custom_data) == ('volume_changed', '40')

1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869

@classmethod
def custom(cls, name: str, *, data: str | None = None) -> Event:
    """
    Create an event your application defines.

    Inject it with [`Runtime.inject`][xnano_core._xnano_core.Runtime.inject] and listen
    for it with a hook on ``'custom'`` events. Text such as JSON can travel in ``data``.

    Args:
        name: What the event is, such as ``'volume_changed'``.
        data: Optional text that travels with the event.

    Raises:
        ValueError: The name is empty.

    Examples:
        ```python
        event = Event.custom('volume_changed', data='40')
        assert event.kind == 'custom'
        assert (event.custom_name, event.custom_data) == ('volume_changed', '40')
        ```
    """

focus_gained() -> Event

assert Event.focus_gained().kind == 'focus_gained'

1879
1880
1881
1882
1883
1884
1885
1886
1887
1888

@classmethod
def focus_gained(cls) -> Event:
    """
    An event reporting that the terminal window gained focus.

    Examples:
        ```python
        assert Event.focus_gained().kind == 'focus_gained'
        ```
    """

focus_lost() -> Event

assert Event.focus_lost().kind == 'focus_lost'

1890
1891
1892
1893
1894
1895
1896
1897
1898
1899

@classmethod
def focus_lost(cls) -> Event:
    """
    An event reporting that the terminal window lost focus.

    Examples:
        ```python
        assert Event.focus_lost().kind == 'focus_lost'
        ```
    """

A key press, repeat or release.

Get one from Event.key or build an event with Event.key_press.

Attributes:

• key (str) –

  The key name, such as 'a', 'enter' or 'page_up'.

• text (str | None) –

  The text the key types, or None for control keys and chords.

• modifiers (frozenset[KeyModifier]) –

  The modifier keys held.

• kind (KeyEventKind) –

  Whether the key was pressed, repeated or released.

Examples:

key = Event.key_press('ctrl+c').key
assert key.key == 'c'
assert key.modifiers == {'control'}
assert key.matches('ctrl+c')

Methods:

• matches –

  Whether this event is the key and modifiers of binding.

key: str

text: str | None

modifiers: frozenset[KeyModifier]

kind: KeyEventKind

matches(binding: str | KeyBinding) -> bool

key = Event.key_press('shift+tab').key
assert key.matches('shift+tab')
assert not key.matches('tab')

1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624

def matches(self, binding: str | KeyBinding) -> bool:
    """
    Whether this event is the key and modifiers of ``binding``.

    Examples:
        ```python
        key = Event.key_press('shift+tab').key
        assert key.matches('shift+tab')
        assert not key.matches('tab')
        ```
    """

A mouse press, release, drag, move or scroll.

Attributes:

• position (Point) –

  The cell under the pointer.

• column (int) –

  The column under the pointer.

• row (int) –

  The row under the pointer.

• kind (MouseEventKind) –

  What the mouse did.

• button (MouseButton | None) –

  The button involved, or None for moves and scrolls.

• scroll_x (int) –

  Horizontal scroll steps, negative for left and positive for right.

• scroll_y (int) –

  Vertical scroll steps, negative for up and positive for down.

Examples:

mouse = Event.mouse_event(column=4, row=2, kind='press', button='left').mouse
assert (mouse.column, mouse.row) == (4, 2)
assert mouse.button == 'left'

position: Point

column: int

row: int

kind: MouseEventKind

button: MouseButton | None

scroll_x: int

scroll_y: int