struct Tput::KeyEvent

• Tput::KeyEvent
• Struct
• Value
• Object

Overview

A single, normalized key event — the keyboard counterpart of Tput::Mouse::Event.

The legacy parser (Tput::Key.read_control) collapses every keystroke into a flat Key enum value, which can't carry a modifier bitmask, a key release, auto-repeat, or a lone modifier press. When the terminal speaks an enhanced keyboard protocol (kitty, or xterm modifyOtherKeys), Tput::Input#listen parses those into a KeyEvent alongside the legacy Key.

The encodings understood (all re-parsed from the raw sequence by Input#parse_key_event):

• kitty / modifyOtherKeys format 1 — CSI number ; mods : event ; text u
• modifyOtherKeys format 0 — CSI 27 ; mods ; number ~
• kitty modified nav/function keys — a legacy final byte (A-H, ~) carrying an event-type sub-parameter, e.g. CSI 1 ; 5 : 3 A (Ctrl+Up release).

Defined in:

tput/key_event.cr

Constant Summary

KEYPAD = 57399..57427

kitty functional key codes for the numeric keypad, KP_0 (57399) through KP_BEGIN (57427). Under the kitty protocol the keypad reports these; Input#listen gives an application-keypad (DECKPAM) key the same code (.from_ss3_keypad), so #keypad? tells a keypad key apart whichever way it arrived, as Qt marks one with Qt::KeypadModifier.

MODIFIER_KEYS = {57441 => :left_shift, 57442 => :left_control, 57443 => :left_alt, 57444 => :left_super, 57445 => :left_hyper, 57446 => :left_meta, 57447 => :right_shift, 57448 => :right_control, 57449 => :right_alt, 57450 => :right_super, 57451 => :right_hyper, 57452 => :right_meta}

kitty functional key codes for the standalone modifier keys. A u-final event whose #number is one of these is a lone modifier press/release — the basis for gestures like "tap Alt" (see #modifier_key).

SS3_KEYPAD = {'M' => 57414, 'X' => 57415, 'j' => 57411, 'k' => 57413, 'l' => 57416, 'm' => 57412, 'n' => 57409, 'o' => 57410, 'p' => 57399, 'q' => 57400, 'r' => 57401, 's' => 57402, 't' => 57403, 'u' => 57404, 'v' => 57405, 'w' => 57406, 'x' => 57407, 'y' => 57408}

kitty's keypad code for the final byte of an application-keypad SS3 sequence (\eO + final), after xterm's table.

Constructors

• .from_csi(final : Char, g0_0 : Int32 | Nil, g0_1 : Int32 | Nil, g0_2 : Int32 | Nil, g1_0 : Int32 | Nil, g1_1 : Int32 | Nil, g2 : Array(Int32 | Nil) | Nil) : KeyEvent

  Builds a KeyEvent from the parsed CSI sub-parameters and the final byte: first three sub-params of group 0 (number : shifted : base), first two of group 1 (mods : event), group 2 in full (associated-text codepoints).

• .new(number : Int32, final : Char, mods : Tput::Modifiers = Modifiers::None, type : Tput::KeyEvent::Type = Type::Press, shifted : Int32 | Nil = nil, base : Int32 | Nil = nil, text : Nil | String = nil)

Class Method Summary

• .from_ss3_keypad(final : Char) : KeyEvent | Nil

  The event for an application-keypad key, \eO followed by final (M for Enter, p for 0, …): a press of kitty's code for that key, or nil for a final that is no keypad key.

Instance Method Summary

• #alt? : Bool
• #base : Int32 | Nil
• #char : Char | Nil

  The printable character this key would produce, for press/repeat events with no control-style modifier held — so plain typing keeps flowing through Input#listen's #char argument even under an enhanced protocol.

• #codepoint : Int32

  The Unicode codepoint for u-final events.

• #ctrl? : Bool
• #final : Char

  The CSI final byte of the originating sequence ('u', '~', or a cursor letter such as 'A').

• #hyper? : Bool
• #keypad? : Bool

  Whether this is a numeric-keypad key (kitty's KP_* codes), Qt's Qt::KeypadModifier.

• #main_key : KeyEvent | Nil

  For a keypad key, the main-keyboard key it stands for, with the same modifiers, type and text: Enter for KP_ENTER, the character for the digits and operators, the cursor and editing keys for the keypad's navigation keys (NumLock off).

• #meta? : Bool
• #modifier_key : Symbol | Nil

  Which standalone modifier key this is (:left_alt, :right_ctrl, …), or nil if not a lone modifier.

• #modifier_key? : Bool

  Whether this event is a standalone modifier key press (Left/Right Shift, Ctrl, Alt, Super, Hyper, Meta) — only reported under kitty's report all keys flag.

• #mods : Modifiers

  The active modifiers.

• #number : Int32

  The primary key number from the sequence.

• #press? : Bool
• #release? : Bool
• #repeat? : Bool
• #shift? : Bool
• #shifted : Int32 | Nil

  kitty alternate keys: shifted and base-layout codepoints, when reported (report alternate keys flag).

• #super? : Bool
• #text : String | Nil

  kitty associated text: the text the key would produce, when reported (report associated text flag).

• #to_legacy_bytes : String | Nil

  Re-encodes this event as the legacy byte sequence a terminal with no enhanced protocol active would have sent — what a child process that never negotiated kitty/modifyOtherKeys expects on its tty: Ctrl+C → 0x03, Esc → "\e", Alt+x → "\ex", nav/function keys → their legacy CSI/SS3 forms, plain text → the character itself.

• #to_legacy_key : Key | Nil

  Projects this event back onto the flat Key enum, for consumers that only understand legacy keys.

• #type : Type

  Press / repeat / release.

Constructor Detail

Class Method Detail

Instance Method Detail