Class: Terminal::KeyEvent

Inherits:
Object
  • Object
show all
Defined in:
lib/terminal/input/key_event.rb

Overview

Represents a keyboard, mouse, or focus event read from the terminal.

Instances are immutable (frozen) and may be cached for performance.

Examples:

Parse a raw escape sequence

event = Terminal::KeyEvent["\r"]
event.key     # => :Enter
event.name    # => "Enter"
event.simple? # => true

Inspect modifier keys

event = Terminal::KeyEvent["\e[1;5A"]
event.key       # => :Up
event.name      # => "Ctrl+Up"
event.modifier? # => true
event.modifiers # => [:Ctrl]

See Also:

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.caching ⇒ true, false

Whether key event caching is enabled. When enabled, parsed events are frozen and reused for identical raw input sequences.

Returns:

  • (true, false) 


129
 
# File 'lib/terminal/input/key_event.rb', line 129

def caching = @cache != nil

Instance Attribute Details

#key ⇒ Symbol, ... (readonly)

The key identifier.

Returns:

  • (Symbol, String, nil) —

    a named key like +:Enter+, +:Tab+, +:MBLeft+ (mouse), or a character string like +"a"+; +nil+ for unknown sequences



29
30
31
 
# File 'lib/terminal/input/key_event.rb', line 29

def key
  @key
end

#modifier? ⇒ true, false (readonly)

Whether any modifier keys are active.

Returns:

  • (true, false)

See Also:



52
 
# File 'lib/terminal/input/key_event.rb', line 52

def modifier? = @modifier_bits != 0

#modifier_bits ⇒ Integer (readonly)

Bitmask of active modifier keys.

Returns:

  • (Integer) —

    modifier_bits bitmask

See Also:



37
38
39
 
# File 'lib/terminal/input/key_event.rb', line 37

def modifier_bits
  @modifier_bits
end

#modifiers ⇒ Array<Symbol> (readonly)

Names of active modifier keys.

Returns:

  • (Array<Symbol>) —

    modifier names

See Also:



44
45
46
 
# File 'lib/terminal/input/key_event.rb', line 44

def modifiers
  @modifiers
end

#name ⇒ String (readonly)

Human-readable name including modifier and key.

Examples:

Terminal::KeyEvent["\e[1;5A"].name # => "Ctrl+Up"

Returns:

  • (String) —

    e.g. "Ctrl+Alt+a" or "Enter"



60
61
62
 
# File 'lib/terminal/input/key_event.rb', line 60

def name
  @name
end

#position ⇒ Array<Integer, Integer>? (readonly)

Mouse position when this is a mouse event.

Returns:

  • (Array<Integer, Integer>, nil) —

    +[row, column]+ for mouse events, +nil+ for keyboard events



66
67
68
 
# File 'lib/terminal/input/key_event.rb', line 66

def position
  @position
end

#raw ⇒ String (readonly)

The raw input sequence as received from the terminal.

Returns:

  • (String) 


71
72
73
 
# File 'lib/terminal/input/key_event.rb', line 71

def raw
  @raw
end

#simple? ⇒ true, false (readonly)

Whether the raw input equals the name (no modifier, no special decoding needed).

Returns:

  • (true, false) 


78
 
# File 'lib/terminal/input/key_event.rb', line 78

def simple? = @raw == @name

Class Method Details

.[](raw) ⇒ KeyEvent

Parse a raw terminal input sequence into a KeyEvent.

Supports single characters, ESC sequences, CSI-u protocol, legacy function keys, and mouse events (VT200 and SGR format).

Examples:

Parse a single character

Terminal::KeyEvent['a'].key # => "a"

Parse escape sequence

Terminal::KeyEvent["\e[A"].key # => :Up

Parse mouse event

Terminal::KeyEvent["\e[<0;10;5M"].key # => :MBLeft

Parameters:

  • raw (String) —

    the raw escape sequence or single character

Returns:

  • (KeyEvent) —

    the parsed event (frozen; cached when caching is enabled)



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/terminal/input/key_event.rb', line 163

def [](raw)
  cached = @cache[raw] and return cached if @cache
  return new(raw, *@single_key[raw.ord]) if raw.size == 1
  return unknown(raw) if raw[0] != "\e"
  return esc1(raw, raw[1]) if raw.size == 2 # ESC ?
  case raw[1]
  when "\e"
    return esc_esc(raw) # ESC ESC ...
  when 'O'
    return new(raw, *@ss3[raw[2].ord]) if raw.size == 3 # ESC O ?
  when '['
    return new(raw, *@ss3[raw[2].ord]) if raw.size == 3 # ESC [ ?
    if raw.size == 6 && raw[2] == 'M'
      return mouse_vt200(raw) # ESC [ M b c r
    end
    if raw.size > 4 && raw[2] == '1' && raw[3] == ';'
      return csi(raw) # ESC [ 1 ; ...
    end
    case raw[-1]
    when '~'
      return legacy(raw) # ESC [ ... ~
    when 'u'
      return csi_u(raw) # ESC [ ... u
    when 'M', 'm'
      # ESC [ ... M
      # ESC [ ... m
      return mouse_sgr(raw) if raw[2] == '<'
    end
  end
  unknown(raw)
end

.key_names ⇒ Array<Symbol>

All recognized key name symbols.

Returns:

  • (Array<Symbol>) —

    sorted unique key names



138
139
140
141
142
143
144
145
146
 
# File 'lib/terminal/input/key_event.rb', line 138

def key_names
  (
    @names ||=
      (@csiu.values + @csi.values + @ss3.values)
        .uniq
        .keep_if { Symbol === it }
        .sort!
  ).dup
end

Instance Method Details

#to_a ⇒ Array<Symbol, String>

Modifier names followed by the key.

Returns:

  • (Array<Symbol, String>) 


83
 
# File 'lib/terminal/input/key_event.rb', line 83

def to_a = @ary.dup

#to_s ⇒ String

Returns the event #name.

Returns:

  • (String) —

    the event #name



93
 
# File 'lib/terminal/input/key_event.rb', line 93

def to_s = @name.dup