Class: RatatuiRuby::Event::Mouse

Inherits:
RatatuiRuby::Event show all
Defined in:
lib/ratatui_ruby/event/mouse.rb

Overview

Reports a mouse interaction.

Modern terminals support rich pointer input, but the protocols are complex and varied. Handling clicks, drags, and scrolls requires robust parsing.

This event simplifies the complexity. It tells you exactly what happened (kind), where it happened (x, y), and which button was involved.

Use this to build interactive UIs. Implement click handlers, draggable sliders, or scrollable viewports with confidence.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2025 Kerrick Long SPDX-License-Identifier: MIT-0 ++

if event.mouse? && event.down? && event.button == "left"
  puts "Left click at #{event.x}, #{event.y}"
end

– SPDX-SnippetEnd ++

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from RatatuiRuby::Event

#focus_gained?, #focus_lost?, #key?, #method_missing, #none?, #paste?, #resize?, #respond_to_missing?, #sync?

Constructor Details

#initialize(kind:, x:, y:, button:, modifiers: []) ⇒ Mouse

Creates a new Mouse event.

kind

Event kind (String).

x

X coordinate (Integer).

y

Y coordinate (Integer).

button

Button name (String or nil).

modifiers

List of modifiers (Array<String>).



95
96
97
98
99
100
101
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 95

def initialize(kind:, x:, y:, button:, modifiers: [])
  @kind = kind.freeze
  @x = x
  @y = y
  @button = (button || "none").freeze
  @modifiers = modifiers.map(&:freeze).sort.freeze
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class RatatuiRuby::Event

Instance Attribute Details

#button ⇒ Object (readonly)

The button pressed ("left", "right", "middle", "none").

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2025 Kerrick Long SPDX-License-Identifier: MIT-0 ++

puts event.button # => "left"

– SPDX-SnippetEnd ++ Can be nil, which is treated as "none".



60
61
62
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 60

def button
  @button
end

#kind ⇒ Object (readonly)

The kind of event ("down", "up", "drag", "moved", "scroll_up", "scroll_down").

puts event.kind # => "down"



38
39
40
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 38

def kind
  @kind
end

#modifiers ⇒ Object (readonly)

List of active modifiers.

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



64
65
66
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 64

def modifiers
  @modifiers
end

#x ⇒ Object (readonly)

X coordinate (column).

puts event.x # => 10



42
43
44
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 42

def x
  @x
end

#y ⇒ Object (readonly)

Y coordinate (row).

puts event.y # => 5



46
47
48
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 46

def y
  @y
end

Instance Method Details

#==(other) ⇒ Object

Compares the event with another object.

  • If other is a Symbol, compares against #to_sym.

  • If other is a Mouse, compares as a value object.

  • Otherwise, returns false.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

if event == :mouse_left_down
  handle_click(event)
end

– SPDX-SnippetEnd ++



249
250
251
252
253
254
255
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 249

def ==(other)
  case other
  when Symbol then to_sym == other
  when Mouse then kind == other.kind && x == other.x && y == other.y && button == other.button && modifiers == other.modifiers
  else false
  end
end

#deconstruct_keys(keys) ⇒ Object

Deconstructs the event for pattern matching.

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2025 Kerrick Long SPDX-License-Identifier: MIT-0 ++

case event
in type: :mouse, kind: "down", x:, y:
  puts "Click at #{x}, #{y}"
end

– SPDX-SnippetEnd ++



176
177
178
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 176

def deconstruct_keys(keys)
  { type: :mouse, kind: @kind, x: @x, y: @y, button: @button, modifiers: @modifiers }
end

#down? ⇒ Boolean Also known as: mouse_down?, press?, pressed?

Returns true if mouse button was pressed down.

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 104

def down?
  @kind == "down"
end

#drag? ⇒ Boolean Also known as: dragging?

Returns true if mouse is being dragged.

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 117

def drag?
  @kind == "drag"
end

#left? ⇒ Boolean Also known as: left_button?, primary?

Returns true if event involves the left mouse button.

Returns:

  • (Boolean) 


144
145
146
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 144

def left?
  @button == "left"
end

#middle? ⇒ Boolean Also known as: middle_button?, aux?

Returns true if event involves the middle mouse button.

Returns:

  • (Boolean) 


154
155
156
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 154

def middle?
  @button == "middle"
end

#mouse? ⇒ Boolean

Returns true for Mouse events.

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2025 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 79

def mouse?
  true
end

#moved? ⇒ Boolean Also known as: hover?, hovering?, move?

Returns true for mouse movement without button press.

event.moved? # => true for moved (no button)

Returns:

  • (Boolean) 


276
277
278
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 276

def moved?
  @kind == "moved"
end

#right? ⇒ Boolean Also known as: right_button?, secondary?, context_menu?

Returns true if event involves the right mouse button.

Returns:

  • (Boolean) 


149
150
151
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 149

def right?
  @button == "right"
end

#scroll? ⇒ Boolean

Returns true for any scroll event.

event.scroll? # => true for scroll_up or scroll_down

Returns:

  • (Boolean) 


263
264
265
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 263

def scroll?
  scroll_up? || scroll_down?
end

#scroll_down? ⇒ Boolean Also known as: wheel_down?

Returns true if scroll wheel moved down.

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2025 Kerrick Long SPDX-License-Identifier: MIT-0 ++

if event.scroll_down?
  scroll_offset += 1
end

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 139

def scroll_down?
  @kind == "scroll_down"
end

#scroll_up? ⇒ Boolean Also known as: wheel_up?

Returns true if scroll wheel moved up.

Returns:

  • (Boolean) 


122
123
124
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 122

def scroll_up?
  @kind == "scroll_up"
end

#to_sym ⇒ Object

Converts the event to a Symbol representation.

The format varies by event type:

Left Button

:mouse_left_down, :mouse_left_up, :mouse_left_drag

Right Button

:mouse_right_down, :mouse_right_up, :mouse_right_drag

Middle Button

:mouse_middle_down, :mouse_middle_up, :mouse_middle_drag

Scroll

:scroll_up, :scroll_down

Move

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

<tt>:mouse_moved</tt>

– SPDX-SnippetEnd ++

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

event = Event::Mouse.new(kind: "down", x: 10, y: 5, button: "left")
event.to_sym  # => :mouse_left_down

scroll = Event::Mouse.new(kind: "scroll_up", x: 0, y: 0, button: "none")
scroll.to_sym # => :scroll_up

– SPDX-SnippetEnd ++



219
220
221
222
223
224
225
226
227
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 219

def to_sym
  if @kind.start_with?("scroll")
    @kind.to_sym
  elsif @button == "none"
    :"mouse_#{@kind}"
  else
    :"mouse_#{@button}_#{@kind}"
  end
end

#up? ⇒ Boolean Also known as: mouse_up?, release?, released?

Returns true if mouse button was released.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/ratatui_ruby/event/mouse.rb', line 109

def up?
  @kind == "up"
end