module RatatuiRuby

Main entry point for the library.

Terminal UIs require low-level control using C/Rust and high-level abstraction in Ruby.

This module bridges the gap. It provides the native methods to initialize the terminal, handle raw mode, and render the widget tree.

Use ‘RatatuiRuby.run` to start your application.

Constants

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

Attributes

experimental_warnings [RW]

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

Public Class Methods

debug_mode! ()

Source

# File lib/ratatui_ruby.rb, line 266
def self.debug_mode!
  Debug.enable!
end

Enables full debug mode.

Convenience alias for Debug.enable!.

Example

RatatuiRuby.debug_mode!

draw (tree = nil, &block)

Source

# 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

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 a block is given.

Examples

Legacy declarative style (tree-based):

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

New imperative style (block-based):

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

frame_count ()

Source

# File lib/ratatui_ruby.rb, line 529
def self.frame_count
  _frame_count
end

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.

get_cell_at (x, y)

Source

# 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

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 {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

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

get_terminal_area ()

Aliases for get_terminal_size (full backend size)

Alias for: get_terminal_size

get_terminal_size ()

Source

# 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

Returns the full terminal backend size.

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

Example

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

@return [Layout::Rect] The full terminal size

Also aliased as: get_terminal_area, terminal_area, terminal_size

get_viewport_area ()

Source

# 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

Returns the current terminal viewport area.

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

@return [Layout::Rect] The rendering viewport area

Also aliased as: get_viewport_size, viewport_area, viewport_size

get_viewport_size ()

Aliases for get_viewport_area (viewport rendering area)

Alias for: get_viewport_area

inject_test_event ()

Source

# File lib/ratatui_ruby.rb, line 208

Injects a mock event into the event queue for testing purposes.

event_type: “key” or “mouse”
data: a Hash containing event data

inject_test_event("key", { code: "a" })

(Native method implemented in Rust)

poll_event (timeout: 0.016)

Source

# 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

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). Pass nil to block indefinitely (wait forever). Pass 0.0 for a non-blocking check.

Examples

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

terminal_area ()

Alias for: get_terminal_size

terminal_size ()

Alias for: get_terminal_size

viewport_area ()

Alias for: get_viewport_area

viewport_size ()

Alias for: get_viewport_area

warn_experimental_feature (feature_name)

Source

# 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

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.