Class: RatatuiRuby::Frame

Inherits:
Object
  • Object
show all
Includes:
A11yCapture
Defined in:
lib/ratatui_ruby/frame.rb,
lib/ratatui_ruby/labs/frame_a11y_capture.rb

Overview

Provides access to the terminal buffer for rendering widgets.

Rendering in immediate-mode TUIs requires knowing the terminal dimensions and placing widgets at specific positions. Without explicit control, layout calculations become duplicated between rendering and hit testing.

This class exposes the terminal frame during a draw call. It provides the current area and methods to render widgets at precise locations.

Use it inside a RatatuiRuby.draw block to render widgets with full control over placement.

Thread/Ractor Safety

Frame is an *I/O handle*, not a data object. It has side effects (render_widget, set_cursor_position) and is intentionally not Ractor-shareable. Passing it to helper methods during the draw block is fine. However, do not include it in immutable Models/Messages or pass it to other Ractors. Frame is only valid during the draw block’s execution.

Examples

Basic usage with a single widget:

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

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

– SPDX-SnippetEnd ++ Using Layout.split for multi-region layouts:

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

RatatuiRuby.draw do |frame|
  sidebar, main = RatatuiRuby::Layout.split(
    frame.area,
    direction: :horizontal,
    constraints: [
      RatatuiRuby::Layout::Constraint.length(20),
      RatatuiRuby::Layout::Constraint.fill(1)
    ]
  )

  frame.render_widget(sidebar_widget, sidebar)
  frame.render_widget(main_widget, main)

  # Store rects for hit testing — no duplication!
  @regions = { sidebar: sidebar, main: main }
end

– SPDX-SnippetEnd ++

Defined Under Namespace

Modules: A11yCapture

Method Summary

Methods included from A11yCapture

#flush_a11y_capture, #render_stateful_widget, #render_widget