class RatatuiRuby::TableState

Mutable state object for Table widgets.

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

Example

@table_state = RatatuiRuby::TableState.new
@table_state.select(1)        # Select second row
@table_state.select_column(0) # Select first column

RatatuiRuby.draw do |frame|
  table = RatatuiRuby::Widgets::Table.new(rows: [...], widths: [...])
  frame.render_stateful_widget(table, frame.area, @table_state)
end

Public Class Methods

with_selected_cell(cell) → TableState

Source

# File lib/ratatui_ruby/table_state.rb, line 242

Creates a new TableState with both row and column selected.

cell: [row, column] array, or nil.

(Native method implemented in Rust)

Public Instance Methods

new(selected = nil) → TableState

Source

# File lib/ratatui_ruby/table_state.rb, line 37

Creates a new TableState with optional initial row selection.

(Native method implemented in Rust)

offset() → Integer

Source

# File lib/ratatui_ruby/table_state.rb, line 77

Returns the current scroll offset.

(Native method implemented in Rust)

scroll_down_by(n) → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 85

Scrolls down by n rows.

(Native method implemented in Rust)

scroll_up_by(n) → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 93

Scrolls up by n rows.

(Native method implemented in Rust)

select(index) → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 45

Sets the selected row index. Pass nil to deselect.

(Native method implemented in Rust)

select_column(index) → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 61

Sets the selected column index. Pass nil to deselect.

(Native method implemented in Rust)

select_first() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 196

Jumps selection to the first row (index 0).

To detect actual selection changes:

return if (state.selected || 0) == 0
state.select_first

(Native method implemented in Rust)

select_first_column() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 126

Selects column 0.

(Native method implemented in Rust)

select_last() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 217

Jumps selection to the last row.

Optimistic Indexing

Sets index to maximum possible value. The renderer clamps to actual last row on draw. To get or check the real last index, track row count:

max_index = rows.size - 1
return if (state.selected || 0) == max_index
state.select(max_index)

(Native method implemented in Rust)

select_last_column() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 134

Selects the last column. The index is clamped during rendering.

(Native method implemented in Rust)

select_next() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 142

Moves selection to the next row. Selects first row if nothing selected.

Optimistic Indexing

Increments the index immediately, even past table bounds. The renderer clamps to valid range on draw. Reading selected between this call and render may return an out-of-bounds value.

To detect actual selection changes, check bounds first:

max_index = rows.size - 1
return if (state.selected || 0) >= max_index
state.select_next

(Native method implemented in Rust)

select_next_column() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 110

Selects the next column, or column 0 if none selected.

(Native method implemented in Rust)

select_previous() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 170

Moves selection to the previous row. Selects last row if nothing selected.

Optimistic Indexing

At index 0, does nothing. With no selection, sets index to maximum value; the renderer clamps to actual last row on draw.

To detect actual selection changes, check bounds first:

return if (state.selected || 0) <= 0
state.select_previous

(Native method implemented in Rust)

select_previous_column() → nil

Source

# File lib/ratatui_ruby/table_state.rb, line 118

Selects the previous column. Saturates at 0.

(Native method implemented in Rust)

selected() → Integer or nil

Source

# File lib/ratatui_ruby/table_state.rb, line 53

Returns the currently selected row index.

(Native method implemented in Rust)

selected_cell() → Array or nil

Source

# File lib/ratatui_ruby/table_state.rb, line 101

Returns the currently selected cell as [row, column]. Returns nil if either row or column is not selected.

(Native method implemented in Rust)

selected_column() → Integer or nil

Source

# File lib/ratatui_ruby/table_state.rb, line 69

Returns the currently selected column index.

(Native method implemented in Rust)