Class: RatatuiRuby::TUI

Inherits:

Object

• Object
• RatatuiRuby::TUI

Includes:

BufferFactories, CanvasFactories, Core, LayoutFactories, StateFactories, StyleFactories, TextFactories, WidgetFactories

Defined in:

lib/ratatui_ruby/tui.rb,
lib/ratatui_ruby/tui/core.rb,
lib/ratatui_ruby/tui/text_factories.rb,
lib/ratatui_ruby/tui/state_factories.rb,
lib/ratatui_ruby/tui/style_factories.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

Overview

Manages the terminal lifecycle and provides a concise API for the render loop.

Writing a TUI loop involves repetitive boilerplate. You constantly instantiate widgets (RatatuiRuby::Widgets::Paragraph.new) and call global methods (RatatuiRuby.draw). This is verbose and hard to read.

The Session object simplifies this. It acts as a factory and a facade. It provides short helper methods for every widget and delegates core commands to the main module.

Use it within RatatuiRuby.run to build your interface cleanly.

“Do What I Mean” (DWIM) Coercion

The TUI factories add a *DWIM argument coercion layer* that the underlying Widget classes don’t have. This means:

• tui.table(rows: [...]) coerces types, normalizes arrays, etc.

• RatatuiRuby::Widgets::Table.new(rows: [...]) passes arguments directly

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

to Rust without coercion — invalid types will raise <tt>TypeError</tt>.

– SPDX-SnippetEnd ++ If you bypass the factories and call Widgets::Table.new directly, you’re responsible for providing correctly-typed arguments. This is useful for debugging (to trigger real Rust TypeErrors) or performance-critical code.

Thread/Ractor Safety

Session is an *I/O handle*, not a data object. It has side effects (draw, poll_event) and is intentionally not Ractor-shareable. Caching it in instance variables (@tui = tui) during your application’s run loop is fine. However, do not include it in immutable Models/Messages or pass it to other Ractors.

Included Mixins

Core

Terminal operations: draw, poll_event, get_cell_at, draw_cell.

LayoutFactories

Layout helpers: rect, constraint_*, layout, layout_split.

StyleFactories

Style helpers: style.

WidgetFactories

Widget creation: block, paragraph, list, table, etc. (DWIM coercion)

TextFactories

Text helpers: span, line, text_width.

StateFactories

State objects: list_state, table_state, scrollbar_state.

CanvasFactories

Canvas shapes: shape_map, shape_line, shape_point, etc.

BufferFactories

Buffer inspection: cell.

Examples

Basic Usage (Recommended)

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

RatatuiRuby.run do |tui|
  loop do
    tui.draw \
      tui.paragraph \
          text: "Hello, Ratatui! Press 'q' to quit.",
          alignment: :center,
          block: tui.block(
            title: "My Ruby TUI App",
            borders: [:all],
            border_style: { fg: \"cyan\" }
          )
    event = tui.poll_event
    break if event == "q" || event == :ctrl_c
  end
end

– SPDX-SnippetEnd ++

Defined Under Namespace

Modules: BufferFactories, CanvasFactories, Core, LayoutFactories, StateFactories, StyleFactories, TextFactories, WidgetFactories

Method Summary

Methods included from BufferFactories

#cell

Methods included from CanvasFactories

#label, #shape, #shape_circle, #shape_line, #shape_map, #shape_point, #shape_rectangle

Methods included from StateFactories

#list_state, #scrollbar_state, #state, #table_state

Methods included from TextFactories

#line, #span, #text, #text_line, #text_span, #text_width

Methods included from WidgetFactories

#axis, #bar, #bar_chart, #bar_chart_bar, #bar_chart_bar_group, #bar_group, #block, #calendar, #canvas, #center, #chart, #clear, #cursor, #dataset, #gauge, #line_gauge, #list, #list_item, #overlay, #paragraph, #ratatui_logo, #ratatui_mascot, #row, #scrollbar, #shape_label, #sparkline, #table, #table_cell, #table_row, #tabs, #widget

Methods included from StyleFactories

#style

Methods included from LayoutFactories

#constraint, #constraint_fill, #constraint_length, #constraint_max, #constraint_min, #constraint_percentage, #constraint_ratio, #fixed, #flex, #fr, #layout, #layout_split, #percent, #rect, #split

Methods included from Core

#draw, #draw_cell, #get_cell_at, #insert_before, #poll_event, #terminal_area, #viewport_area