Class: RatatuiRuby::Widgets::Block

Inherits:
Object
  • Object
show all
Includes:
CoerceableWidget
Defined in:
lib/ratatui_ruby/widgets/block.rb

Overview

Defines the visual container for a widget.

Widgets often float in void. Without boundaries, interfaces become a chaotic mess of text. Users need structure to parse information.

This widget creates that structure. It wraps content in borders. It labels sections with titles. It paints the background.

Use blocks to define distinct areas. Group related information. Create a visual hierarchy that guides the user’s eye.

Example

Run the interactive demo from the terminal:

ruby examples/widget_box/app.rb

Instance Method Summary collapse

Methods included from CoerceableWidget

included

Constructor Details

#initialize(title: nil, titles: [], title_alignment: nil, title_style: nil, borders: [:all], border_style: nil, border_type: nil, border_set: nil, style: nil, padding: 0, children: []) ⇒ Block

Creates a new Block.

title

Main title string (optional).

titles

Array of additional titles (optional).

title_alignment

Alignment symbol: :left (default), :center, :right.

title_style

Base style for all titles (optional).

borders

Array of borders to show: :top, :bottom, :left, :right, or :all (default).

border_style

Style object or Hash for the border lines.

border_type

Symbol: :plain (default), :rounded, :double, :thick, :hidden, :quadrant_inside, :quadrant_outside.

border_set

Hash: Custom characters for the border lines. Unique characters are interned (leaked) permanently, so avoid infinite dynamic variations.

style

Style object or Hash for the block’s content area.

padding

Integer (uniform) or Array (left, right, top, bottom).

children

Array of widgets to render inside the block (optional).



171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/ratatui_ruby/widgets/block.rb', line 171

def initialize(title: nil, titles: [], title_alignment: nil, title_style: nil, borders: [:all], border_style: nil, border_type: nil, border_set: nil, style: nil, padding: 0, children: [])
  if border_set
    border_set = border_set.dup
    %i[top_left top_right bottom_left bottom_right vertical_left vertical_right horizontal_top horizontal_bottom].each do |long_key|
      short_key = long_key.to_s.split("_").map { |s| s[0] }.join.to_sym
      if (val = border_set.delete(short_key))
        border_set[long_key] = val
      end
    end
  end
  coerced_padding = if padding.is_a?(Array)
    padding.map { |v| Integer(v) }
  else
    Integer(padding)
  end
  super(
    title:,
    titles:,
    title_alignment:,
    title_style:,
    borders:,
    border_style:,
    border_type:,
    border_set:,
    style:,
    padding: coerced_padding,
    children:
  )
end

Instance Method Details

#inner(area) ⇒ Object

Computes the inner content area given an outer area.

This method calculates where content should be placed within a block, accounting for borders and padding. Essential for layout calculations when you need to know the usable space inside a block.

Example

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

block = Block.new(borders: [:all], padding: 1)
outer = Layout::Rect.new(x: 0, y: 0, width: 20, height: 10)
inner = block.inner(outer)
# => Rect(x: 2, y: 2, width: 16, height: 6)

– SPDX-SnippetEnd ++

area

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

The outer Rect to compute the inner area for.

– SPDX-SnippetEnd ++ Returns a new Rect representing the inner content area.



234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/ratatui_ruby/widgets/block.rb', line 234

def inner(area)
  # Calculate border offsets
  has_border = -> (side) { borders.include?(:all) || borders.include?(side) }
  left_border = has_border.call(:left) ? 1 : 0
  right_border = has_border.call(:right) ? 1 : 0
  top_border = has_border.call(:top) ? 1 : 0
  bottom_border = has_border.call(:bottom) ? 1 : 0

  # Calculate padding offsets - ensure all are Integer
  pad_left, pad_right, pad_top, pad_bottom = if padding.is_a?(Array)
    # [left, right, top, bottom]
    [
      Integer(padding[0] || 0),
      Integer(padding[1] || 0),
      Integer(padding[2] || 0),
      Integer(padding[3] || 0),
    ]
  else
    p = Integer(padding)
    [p, p, p, p]
  end

  # Compute inner area
  new_x = area.x + left_border + pad_left
  new_y = area.y + top_border + pad_top
  new_width = [area.width - left_border - right_border - pad_left - pad_right, 0].max
  new_height = [area.height - top_border - bottom_border - pad_top - pad_bottom, 0].max

  Layout::Rect.new(x: new_x, y: new_y, width: new_width, height: new_height)
end