Module event

Expand description

Support for keyboard, mouse, and query response events.

§Background

Prettytty’s [Scan] trait reads so-called Tokens from terminal input, largely to distinguish between runs of UTF-8 encoded text and ANSI escape sequences. To avoid the overhead of heap allocation for every single token, their payloads draw on the scanner’s internal buffer. That necessitates processing a token’s payload before reading the next.

By contrast, this module’s Events are higher-level abstractions, which often stem from entire ANSI escape sequences. They also are self-contained, i.e., not restricted by explicit lifetimes, yet lightweight enough to implement Copy. They include key, mouse, window, and response-to-query events. Since not all valid ANSI escape sequences map to this module’s events, [ScanEvent::read_event] method returns TokenOrEvent, with tokens serving as fallback. Consistent with how hardware terminals treat unknown escape sequences, an application may simply ignore such tokens.

Tokens should suffice for applications that only need to process key presses for letters, numbers, and common symbols—or the occasional ANSI escape sequence. Applications that need to process modifier keys, mouse input, and ANSI escape sequences should prefer events.

§Keyboard Input

Unfortunately, there are several conventions for encoding keyboard and mouse input from terminals. Legacy encodings for keyboard events share some patterns, such as CSI P_key ; P_mod ~ or SS3 key. But they also differ for PC, VT-220, VT-52, Sun, and HP keyboards, as covered in xterm’s documentation and highlighted by this table. Worse, legacy encodings are incomplete and ambiguous. For example, there is no way to distinguish between ctrl-i and shift-ctrl-i. alt-c may really be esc and c typed too quickly after each other. alt-c also overlaps with the first byte in the UTF-8 encoding of many extended Latin characters such as é.

There are a number of attempts to fix these short-comings:

Fixterms
kitty’s terminal protocol extensions, which build on fixterms
xterm’s modifyOtherKeys enables a partially overlapping encoding
win32-input-mode, which encodes the Windows-specific KEY_EVENT_RECORD structure

Currently, prettytty supports common legacy encodings as well as the encoding based on CSI⋯u shared between fixterms, kitty, and xterm. No configuration is necessary, all of them are recognized by default. Prettytty does not yet support kitty’s progressive enhancements. While many of the enhancements are useful, their encoding is rather awkward, distinguishing between semicolons and colons. While that may be consistent with the letter of some ISO standards, it also is wilfully different from all other ANSI escape sequences and well-established terminal practice.

§The `event` Feature

This module is entirely optional and requires that the event feature is enabled.

Structs§

ColorEvent: An event to indicate a concrete color.
CursorEvent: An event to indicate a cursor position.
KeyEvent: A key event.
ModifierIter: An iterator over modifiers.
Modifiers: A key’s logical modifiers.
MouseEvent: A mouse event.
WindowEvent: An event to indicate a change in terminal size.

Enums§

Event: An input event.
Key: A key.
KeyEventKind: The kind of key event.
MediaKey: A media key.
Modifier: A logical modifier of keys and mouse button presses.
ModifierKey: A physical modifier key.
MouseButton: The mouse button.
MouseEventKind: The kind of mouse event.
TokenOrEvent: A token or an event.