Class: RatatuiRuby::ListState

Inherits:
Object
  • Object
show all
Defined in:
lib/ratatui_ruby/list_state.rb

Overview

Mutable state object for List widgets.

When using Frame::A11yCapture#render_stateful_widget, the State object is the *single source of truth* for selection and scroll offset. Widget properties (selected_index, offset) are ignored in stateful mode.

State objects persist across frames, allowing you to:

  • Track selection without manual index management

  • Read back the scroll offset calculated by Ratatui

  • Implement mouse click-to-row hit testing

Thread/Ractor Safety

ListState is not Ractor-shareable. It contains mutable internal state. Store it in instance variables, not in immutable Models.

Example

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

@list_state = RatatuiRuby::ListState.new
@list_state.select(2) # Select third item

RatatuiRuby.draw do |frame|
  list = RatatuiRuby::Widgets::List.new(items: ["A", "B", "C", "D", "E"])
  frame.render_stateful_widget(list, frame.area, @list_state)
end

puts @list_state.offset # Scroll position after render

– SPDX-SnippetEnd ++