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

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).

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)

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
• #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

Instance Method Detail