class RatatuiRuby::Session

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::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.

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 TEA Models/Messages or pass it to other Ractors.

Available Methods

The session dynamically defines factory methods for all RatatuiRuby constants.

Widget Factories

The session acts as a dynamic factory. It creates a helper method for every class defined in the ‘RatatuiRuby` module.

**The Rule:** To instantiate a class like ‘RatatuiRuby::SomeWidget`, call `tui.some_widget(…)`.

**Common Examples:**

If a new class is added to the library, it is automatically available here.

Nested Helpers

Examples

Basic Usage (Recommended)

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_color: "cyan"
          )
    event = tui.poll_event
    break if event == "q" || event == :ctrl_c
  end
end

Raw API (Verbose)

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

Mixed Usage (Flexible)

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