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

NullIO: Re-export NullIO at module root for backward compatibility
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

draw (tree = nil, &block)

Source

# File lib/ratatui_ruby.rb, line 206
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)
  else
    _draw(&block)
  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

get_cell_at (x, y)

Source

# File lib/ratatui_ruby.rb, line 301
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"],
    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

inject_test_event ()

Source

# File lib/ratatui_ruby.rb, line 147

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 246
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
  else
    # Fallback for unknown events, though ideally we cover them all
    nil
  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)

warn_experimental_feature (feature_name)

Source

# File lib/ratatui_ruby.rb, line 162
def self.warn_experimental_feature(feature_name)
  return unless experimental_warnings

  @warned_features ||= {}
  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.