class RatatuiRuby::Event::Key

Captures a keyboard interaction.

The keyboard is the primary interface for your terminal application. Raw key codes are often cryptic, and handling modifiers manually is error-prone.

This event creates clarity. It encapsulates the interaction, providing a normalized code and a list of active modifiers.

Compare it directly to strings or symbols for rapid development, or use pattern matching for complex control schemes.

Examples

Using predicates:

if event.key? && event.ctrl? && event.code == "c"
  exit
end

Using symbol comparison:

if event == :ctrl_c
  exit
end

Using pattern matching:

case event
in type: :key, code: "c", modifiers: ["ctrl"]
  exit
end

Attributes

code [R]

The key code (e.g., "a", "enter", "up").

puts event.code # => "enter"

modifiers [R]

List of active modifiers ("ctrl", "alt", "shift").

puts event.modifiers # => ["ctrl", "shift"]

Public Class Methods

new (code:, modifiers: [])

Source

# File lib/ratatui_ruby/event/key.rb, line 62
def initialize(code:, modifiers: [])
  @code = code
  @modifiers = modifiers.sort
end

Creates a new Key event.

code: The key code (String).
modifiers: List of modifiers (Array<String>).

Public Instance Methods

== (other)

Source

# File lib/ratatui_ruby/event/key.rb, line 73
def ==(other)
  case other
  when Symbol
    to_sym == other
  when String
    to_s == other
  when Key
    code == other.code && modifiers == other.modifiers
  else
    super
  end
end

Compares the event with another object.

If other is a Symbol, compares against to_sym.
If other is a String, compares against to_s.
Otherwise, performs standard equality check.
Otherwise, compares internal state (code + modifiers).

Calls superclass method

alt? ()

Source

# File lib/ratatui_ruby/event/key.rb, line 143
def alt?
  @modifiers.include?("alt")
end

Returns true if ALT is held.

char ()

Source

# File lib/ratatui_ruby/event/key.rb, line 172
def char
  to_s
end

Returns the key as a printable character (if applicable).

Printable Characters: Returns the character itself (e.g., "a", "1", " ").
Special Keys: Returns an empty string (e.g., "enter", "up", "f1").

This is equivalent to to_s.

RatatuiRuby::Event::Key.new(code: "a").char      # => "a"
RatatuiRuby::Event::Key.new(code: "enter").char  # => ""

ctrl? ()

Source

# File lib/ratatui_ruby/event/key.rb, line 138
def ctrl?
  @modifiers.include?("ctrl")
end

Returns true if CTRL is held.

deconstruct_keys (keys)

Source

# File lib/ratatui_ruby/event/key.rb, line 206
def deconstruct_keys(keys)
  { type: :key, code: @code, modifiers: @modifiers }
end

Deconstructs the event for pattern matching.

case event
in type: :key, code: "c", modifiers: ["ctrl"]
  puts "Ctrl+C pressed"
end

inspect ()

Source

# File lib/ratatui_ruby/event/key.rb, line 133
def inspect
  "#<#{self.class} code=#{@code.inspect} modifiers=#{@modifiers.inspect}>"
end

Returns inspection string.

key? ()

Source

# File lib/ratatui_ruby/event/key.rb, line 52
def key?
  true
end

Returns true for Key events.

event.key?    # => true
event.mouse?  # => false
event.resize? # => false

method_missing (name, *args, &block)

Source

# File lib/ratatui_ruby/event/key.rb, line 187
def method_missing(name, *args, &block)
  if name.to_s.end_with?("?")
    key_sym = name.to_s[0...-1].to_sym
    return self == key_sym
  end
  super
end

Supports dynamic key predicate methods via method_missing.

Allows convenient checking for specific keys or key combinations:

event.ctrl_c?     # => true if Ctrl+C
event.enter?      # => true if Enter
event.shift_up?   # => true if Shift+Up
event.q?          # => true if "q"

The method name is converted to a symbol and compared against the event. This works for any key code or modifier+key combination.

Calls superclass method RatatuiRuby::Event#method_missing

respond_to_missing? (name, *args)

Source

# File lib/ratatui_ruby/event/key.rb, line 196
def respond_to_missing?(name, *args)
  name.to_s.end_with?("?") || super
end

Declares that this class responds to dynamic predicate methods.

Calls superclass method RatatuiRuby::Event#respond_to_missing?

shift? ()

Source

# File lib/ratatui_ruby/event/key.rb, line 148
def shift?
  @modifiers.include?("shift")
end

Returns true if SHIFT is held.

text? ()

Source

# File lib/ratatui_ruby/event/key.rb, line 157
def text?
  @code.length == 1
end

Returns true if the key represents a single printable character.

RatatuiRuby::Event::Key.new(code: "a").text?       # => true
RatatuiRuby::Event::Key.new(code: "enter").text?   # => false
RatatuiRuby::Event::Key.new(code: "space").text?   # => false ("space" is not 1 char, " " is)

to_s ()

Source

# File lib/ratatui_ruby/event/key.rb, line 124
def to_s
  if text?
    @code
  else
    ""
  end
end

Converts the event to its String representation.

Printable Characters: Returns the character itself (e.g., "a", "1", " ").
Special Keys: Returns an empty string (e.g., "enter", "up", "f1" all return "").
Modifiers: Returns the character if printable, ignoring modifiers unless they alter the character code itself. Note that ctrl+c typically returns "c" as the code, so to_s will return "c".

to_sym ()

Source

# File lib/ratatui_ruby/event/key.rb, line 106
def to_sym
  mods = @modifiers.join("_")
  if mods.empty?
    @code.to_sym
  else
    "#{mods}_#{@code}".to_sym
  end
end

Converts the event to a Symbol representation.

The format is [modifiers_]code. Modifiers are sorted alphabetically (alt, ctrl, shift) and joined by underscores.

Supported Keys

Standard: :enter, :backspace, :tab, :esc, :page_up, :page_down, :home, :end, :delete, :insert, :f1..:f12
Navigation: :up, :down, :left, :right
Characters: :a, :b, :1, :space, etc.

Modifier Examples

:ctrl_c
:alt_enter
:shift_left
:ctrl_alt_delete