Module: RatatuiRuby

Extended by:
OutputGuard, TerminalLifecycle
Defined in:
lib/ratatui_ruby.rb,
lib/ratatui_ruby/tui.rb,
lib/ratatui_ruby/cell.rb,
lib/ratatui_ruby/draw.rb,
lib/ratatui_ruby/labs.rb,
lib/ratatui_ruby/text.rb,
lib/ratatui_ruby/debug.rb,
lib/ratatui_ruby/event.rb,
lib/ratatui_ruby/frame.rb,
lib/ratatui_ruby/style.rb,
lib/ratatui_ruby/buffer.rb,
lib/ratatui_ruby/layout.rb,
lib/ratatui_ruby/backend.rb,
lib/ratatui_ruby/symbols.rb,
lib/ratatui_ruby/version.rb,
lib/ratatui_ruby/widgets.rb,
lib/ratatui_ruby/terminal.rb,
lib/ratatui_ruby/tui/core.rb,
lib/ratatui_ruby/event/key.rb,
lib/ratatui_ruby/labs/a11y.rb,
lib/ratatui_ruby/text/line.rb,
lib/ratatui_ruby/text/span.rb,
lib/ratatui_ruby/event/none.rb,
lib/ratatui_ruby/event/sync.rb,
lib/ratatui_ruby/list_state.rb,
lib/ratatui_ruby/buffer/cell.rb,
lib/ratatui_ruby/event/mouse.rb,
lib/ratatui_ruby/event/paste.rb,
lib/ratatui_ruby/layout/rect.rb,
lib/ratatui_ruby/layout/size.rb,
lib/ratatui_ruby/style/color.rb,
lib/ratatui_ruby/style/style.rb,
lib/ratatui_ruby/table_state.rb,
lib/ratatui_ruby/test_helper.rb,
lib/ratatui_ruby/widgets/row.rb,
lib/ratatui_ruby/event/resize.rb,
lib/ratatui_ruby/output_guard.rb,
lib/ratatui_ruby/widgets/cell.rb,
lib/ratatui_ruby/widgets/list.rb,
lib/ratatui_ruby/widgets/tabs.rb,
lib/ratatui_ruby/layout/layout.rb,
lib/ratatui_ruby/widgets/block.rb,
lib/ratatui_ruby/widgets/chart.rb,
lib/ratatui_ruby/widgets/clear.rb,
lib/ratatui_ruby/widgets/gauge.rb,
lib/ratatui_ruby/widgets/table.rb,
lib/ratatui_ruby/event/key/dwim.rb,
lib/ratatui_ruby/widgets/canvas.rb,
lib/ratatui_ruby/widgets/center.rb,
lib/ratatui_ruby/widgets/cursor.rb,
lib/ratatui_ruby/event/key/media.rb,
lib/ratatui_ruby/layout/position.rb,
lib/ratatui_ruby/scrollbar_state.rb,
lib/ratatui_ruby/widgets/overlay.rb,
lib/ratatui_ruby/event/focus_lost.rb,
lib/ratatui_ruby/event/key/system.rb,
lib/ratatui_ruby/layout/alignment.rb,
lib/ratatui_ruby/synthetic_events.rb,
lib/ratatui_ruby/widgets/calendar.rb,
lib/ratatui_ruby/layout/constraint.rb,
lib/ratatui_ruby/terminal/viewport.rb,
lib/ratatui_ruby/widgets/bar_chart.rb,
lib/ratatui_ruby/widgets/list_item.rb,
lib/ratatui_ruby/widgets/paragraph.rb,
lib/ratatui_ruby/widgets/scrollbar.rb,
lib/ratatui_ruby/widgets/sparkline.rb,
lib/ratatui_ruby/event/focus_gained.rb,
lib/ratatui_ruby/event/key/modifier.rb,
lib/ratatui_ruby/terminal_lifecycle.rb,
lib/ratatui_ruby/tui/text_factories.rb,
lib/ratatui_ruby/widgets/line_gauge.rb,
lib/ratatui_ruby/backend/window_size.rb,
lib/ratatui_ruby/event/key/character.rb,
lib/ratatui_ruby/tui/state_factories.rb,
lib/ratatui_ruby/tui/style_factories.rb,
lib/ratatui_ruby/widgets/shape/label.rb,
lib/ratatui_ruby/event/key/navigation.rb,
lib/ratatui_ruby/test_helper/snapshot.rb,
lib/ratatui_ruby/test_helper/terminal.rb,
lib/ratatui_ruby/tui/buffer_factories.rb,
lib/ratatui_ruby/tui/canvas_factories.rb,
lib/ratatui_ruby/tui/layout_factories.rb,
lib/ratatui_ruby/tui/widget_factories.rb,
lib/ratatui_ruby/widgets/ratatui_logo.rb,
lib/ratatui_ruby/terminal/capabilities.rb,
lib/ratatui_ruby/widgets/bar_chart/bar.rb,
lib/ratatui_ruby/widgets/ratatui_mascot.rb,
lib/ratatui_ruby/labs/frame_a11y_capture.rb,
lib/ratatui_ruby/test_helper/global_state.rb,
lib/ratatui_ruby/test_helper/test_doubles.rb,
lib/ratatui_ruby/widgets/coerceable_widget.rb,
lib/ratatui_ruby/test_helper/event_injection.rb,
lib/ratatui_ruby/widgets/bar_chart/bar_group.rb,
lib/ratatui_ruby/test_helper/style_assertions.rb,
lib/ratatui_ruby/test_helper/subprocess_timeout.rb

Overview

– SPDX-FileCopyrightText: 2026 Kerrick Long <[email protected]> SPDX-License-Identifier: LGPL-3.0-or-later ++

Defined Under Namespace

Modules: Backend, Buffer, Debug, Draw, Labs, Layout, OutputGuard, Style, Symbols, SyntheticEvents, TerminalLifecycle, TestHelper, Text, Widgets Classes: Cell, Error, Event, Frame, ListState, ScrollbarState, TUI, TableState, Terminal

Constant Summary collapse

VERSION =

The version of the ratatui_ruby gem. See semver.org/spec/v2.0.0.html

"1.4.1"

Class Attribute Summary collapse

Class Method Summary collapse

Methods included from OutputGuard

guard_io, headless!, is_headless?

Methods included from TerminalLifecycle

cursor_position, cursor_position=, init_terminal, init_test_terminal, insert_before, restore_terminal, run, terminal_active?

Class Attribute Details

.experimental_warnings ⇒ Object

:attr_accessor: experimental_warnings Whether to show warnings when using experimental features (default: true).



187
188
189
 
# File 'lib/ratatui_ruby.rb', line 187

def experimental_warnings
  @experimental_warnings
end

Class Method Details

.debug_mode! ⇒ Object

Enables full debug mode.

Convenience alias for Debug.enable!.

Example

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

RatatuiRuby.debug_mode!

– SPDX-SnippetEnd ++



266
267
268
 
# File 'lib/ratatui_ruby.rb', line 266

def self.debug_mode!
  Debug.enable!
end

.draw(tree = nil, &block) ⇒ Object

Draws the given UI node tree to the terminal.

TUI applications need to render widgets to the screen. Rendering could happen all at once with a pre-built tree, or incrementally with direct frame access.

This method handles both. Pass a tree for declarative rendering, or pass a block to manipulate the frame directly. The block receives a Frame object for imperative drawing.

tree

A widget tree (Widgets::Paragraph, Layout::Layout, etc.) to render. Optional if

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

a block is given.

– SPDX-SnippetEnd ++

Examples

Legacy declarative style (tree-based):

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

RatatuiRuby.draw(Widgets::Paragraph.new(text: "Hello"))

– SPDX-SnippetEnd ++ New imperative style (block-based):

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

RatatuiRuby.draw do |frame|
  frame.render_widget(Widgets::Paragraph.new(text: "Hello"), frame.area)
end

– SPDX-SnippetEnd ++



320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/ratatui_ruby.rb', line 320

def self.draw(tree = nil, &block)
  if tree && block
    raise ArgumentError, "Cannot provide both a tree and a block to draw"
  end
  unless tree || block
    raise ArgumentError, "Must provide either a tree or a block to draw"
  end

  if tree
    _draw(tree)
  elsif block
    # Wrap user block to flush A11Y capture after user code
    if Labs.enabled?(:a11y)
      _draw do |frame|
        block.call(frame)
        frame.flush_a11y_capture
      end
    else
      _draw(&block)
    end
  end
end

.frame_count ⇒ Object

Number of frames drawn since terminal initialization.

TUI applications track render cycles for animations, FPS counters, or debugging. Manually counting draws is error-prone and clutters app logic.

This method queries the terminal’s internal frame counter. It starts at 0 when the terminal initializes and increments by 1 after each successful draw. Restoring and re-initializing resets the counter.

Raises RatatuiRuby::Error::Invariant if terminal not initialized.



529
530
531
 
# File 'lib/ratatui_ruby.rb', line 529

def self.frame_count
  _frame_count
end

.get_cell_at(x, y) ⇒ Object

Inspects the terminal buffer at specific coordinates.

When writing tests, you need to verify that your widget drew the correct characters and styles. This method provides deep inspection of the cell’s state (symbol, colors, modifiers).

Returns a RatatuiRuby::Buffer::Cell object.

Values depend on what the backend has rendered. If nothing has been rendered to a cell, it may contain defaults (empty symbol, nil colors).

Example

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

cell = RatatuiRuby.get_cell_at(10, 5)
expect(cell.symbol).to eq("X")
expect(cell.fg).to eq(:red)
expect(cell).to be_bold

– SPDX-SnippetEnd ++



449
450
451
452
453
454
455
456
457
458
 
# File 'lib/ratatui_ruby.rb', line 449

def self.get_cell_at(x, y)
  raw = _get_cell_at(x, y)
  Buffer::Cell.new(
    char: raw["char"],
    fg: raw["fg"],
    bg: raw["bg"],
    underline_color: raw["underline_color"],
    modifiers: raw["modifiers"] || []
  )
end

.get_terminal_size ⇒ Layout::Rect Also known as: get_terminal_area, terminal_area, terminal_size

Returns the full terminal backend size.

This is always the full terminal dimensions, regardless of viewport mode.

Example

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

size = RatatuiRuby.get_terminal_size
puts "Terminal: #{size.width}x#{size.height}"

– SPDX-SnippetEnd ++

Returns:



496
497
498
499
500
501
502
503
504
 
# File 'lib/ratatui_ruby.rb', line 496

def self.get_terminal_size
  raw = _get_terminal_size
  Layout::Rect.new(
    x: raw["x"],
    y: raw["y"],
    width: raw["width"],
    height: raw["height"]
  )
end

.get_viewport_area ⇒ Layout::Rect Also known as: get_viewport_size, viewport_area, viewport_size

Returns the current terminal viewport area.

In inline viewports, this returns the viewport dimensions. In fullscreen mode, this returns the full terminal size.

Returns:



467
468
469
470
471
472
473
474
475
 
# File 'lib/ratatui_ruby.rb', line 467

def self.get_viewport_area
  raw = _get_terminal_area
  Layout::Rect.new(
    x: raw["x"],
    y: raw["y"],
    width: raw["width"],
    height: raw["height"]
  )
end

.poll_event(timeout: 0.016) ⇒ Object

Checks for user input.

Interactive apps must respond to input. Loops need to poll without burning CPU.

This method checks for an event. It returns the event if one is found. It returns RatatuiRuby::Event::None if the timeout expires.

timeout

Float seconds to wait (default: 0.016).

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

Pass <tt>nil</tt> to block indefinitely (wait forever).
Pass <tt>0.0</tt> for a non-blocking check.

– SPDX-SnippetEnd ++

Examples

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

# Standard loop (approx 60 FPS)
event = RatatuiRuby.poll_event

# Block until event (pauses execution)
event = RatatuiRuby.poll_event(timeout: nil)

# Non-blocking check (returns immediately)
event = RatatuiRuby.poll_event(timeout: 0.0)

– SPDX-SnippetEnd ++

Raises:

  • (ArgumentError) 


384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'lib/ratatui_ruby.rb', line 384

def self.poll_event(timeout: 0.016)
  raise ArgumentError, "timeout must be non-negative" if timeout && timeout < 0

  raw = _poll_event(timeout)
  return Event::None.new.freeze if raw.nil?

  case raw[:type]
  when :key
    Event::Key.new(
      code: raw[:code],
      modifiers: (raw[:modifiers] || []).freeze,
      kind: raw[:kind] || :standard
    ).freeze
  when :mouse
    Event::Mouse.new(
      kind: raw[:kind].to_s,
      x: raw[:x],
      y: raw[:y],
      button: raw[:button].to_s,
      modifiers: (raw[:modifiers] || []).freeze
    ).freeze
  when :resize
    Event::Resize.new(width: raw[:width], height: raw[:height]).freeze
  when :paste
    Event::Paste.new(content: raw[:content]).freeze
  when :focus_gained
    Event::FocusGained.new.freeze
  when :focus_lost
    Event::FocusLost.new.freeze
  when :sync
    Event::Sync.new.freeze
  else
    # Return None for unknown event types
    Event::None.new.freeze
  end
end

.warn_experimental_feature(feature_name) ⇒ Object

Warns about usage of an experimental feature unless warnings are suppressed.

feature_name

String name of the feature (e.g., “Paragraph#line_count”)

This warns only once per feature name per session.



231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/ratatui_ruby.rb', line 231

def self.warn_experimental_feature(feature_name)
  return unless experimental_warnings

  @warned_features ||= {} #: Hash[String, bool]
  return if @warned_features[feature_name]

  message = "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
  if terminal_active?
    queue_warning(message)
  else
    warn message
  end
  @warned_features[feature_name] = true
end