class RatatuiRuby::Widgets::Block

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

Attributes

border_set [R]

Custom characters for the border lines.

A Hash with keys defining the characters for the borders. Keys: :top_left, :top_right, :bottom_left, :bottom_right, :vertical_left, :vertical_right, :horizontal_top, :horizontal_bottom.

Providing this overrides border_type.

Example

Block.new(border_set: { top_left: "1", top_right: "2", bottom_left: "3", bottom_right: "4", vertical_left: "5", vertical_right: "6", horizontal_top: "7", horizontal_bottom: "8" })

border_style [R]

Full style (colors/modifiers) for the border lines.

A Style object or Hash with :fg, :bg, and :modifiers. This allows borders to be bold, italic, colored, etc.

border_type [R]

Visual style of the border lines.

One of :plain, :rounded, :double, :thick, etc.

borders [R]

Visible borders.

An array containing any of :top, :bottom, :left, :right, or :all.

Example

Block.new(borders: [:left, :right]).borders # => [:left, :right]

children [R]

Widgets to render inside the block (optional).

When provided, each child widget is rendered within the block’s area.

Example

Block.new(
  title: "Content",
  borders: [:all],
  children: [Paragraph.new(text: "Hello")]
)

padding [R]

Inner padding.

Can be a single Integer (uniform) or a 4-element Array (left, right, top, bottom).

Example

Block.new(padding: 2).padding # => 2
Block.new(padding: [1, 1, 0, 0]).padding # => [1, 1, 0, 0]

style [R]

Base style (colors/modifiers) for the block content.

title [R]

The main title displayed on the top border.

Example

Block.new(title: "Main").title # => "Main"

title_alignment [R]

Alignment of the main title.

One of :left, :center, or :right.

Example

Block.new(title_alignment: :center).title_alignment # => :center

title_style [R]

Style applied to all titles if not overridden.

Example

Block.new(title_style: Style.new(fg: :red)).title_style

titles [R]

Additional titles for complex labeling.

Each title can be a String or a Hash with keys :content, :alignment, :position (:top or :bottom), and :style.

Example

Block.new(titles: ["Top", { content: "Bottom", position: :bottom }]).titles

Public Class Methods

new (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: [])

Source

# 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

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

Calls superclass method

Public Instance Methods

inner (area)

Source

# 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

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

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)

area: The outer Rect to compute the inner area for.

Returns a new Rect representing the inner content area.