Class: RatatuiRuby::Widgets::LineGauge

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

Overview

Displays a compact, single-line progress bar.

Screen space is precious. Standard block gauges are bulky and consume multiple rows.

This widget compresses the feedback. It draws a progress bar using line characters, fitting perfectly into tight layouts or lists.

Use it when you need to show status without stealing focus or space.

Example

Run the interactive demo from the terminal:

ruby examples/widget_line_gauge/app.rb

Instance Method Summary collapse

Methods included from CoerceableWidget

included

Constructor Details

#initialize(ratio: nil, percent: nil, label: nil, style: nil, filled_style: nil, unfilled_style: nil, block: nil, filled_symbol: "█", unfilled_symbol: "░") ⇒ LineGauge

Creates a new LineGauge.

ratio

Float (0.0 - 1.0).

percent

Integer (0 - 100), alternative to ratio.

label

String or Text::Span (optional).

style

Style (optional, base style for the gauge).

filled_style

Style.

unfilled_style

Style.

block

Block.

filled_symbol

String (default: "█").

unfilled_symbol

String (default: "░").

Raises ArgumentError if percent is not 0..100.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/ratatui_ruby/widgets/line_gauge.rb', line 73

def initialize(ratio: nil, percent: nil, label: nil, style: nil, filled_style: nil, unfilled_style: nil, block: nil, filled_symbol: "█", unfilled_symbol: "░")
  if percent
    float_percent = Float(percent)
    unless float_percent.between?(0, 100)
      raise ArgumentError, "percent must be between 0 and 100 (got #{percent.inspect})"
    end
    ratio = float_percent / 100.0
  end
  ratio = Float(ratio || 0.0)
  super(
    ratio:,
    label:,
    style:,
    filled_style:,
    unfilled_style:,
    block:,
    filled_symbol:,
    unfilled_symbol:
  )
end

Instance Method Details

#complete? ⇒ Boolean

Returns true if the gauge is at 100% or more (ratio >= 1.0).

Example

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

Widgets::LineGauge.new(ratio: 0.99).complete?  # => false
Widgets::LineGauge.new(ratio: 1.0).complete?   # => true

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


126
127
128
 
# File 'lib/ratatui_ruby/widgets/line_gauge.rb', line 126

def complete?
  ratio >= 1.0
end

#filled? ⇒ Boolean

Returns true if the gauge has any fill (ratio > 0).

Example

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

Widgets::LineGauge.new(ratio: 0.0).filled?  # => false
Widgets::LineGauge.new(ratio: 0.5).filled?  # => true

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


108
109
110
 
# File 'lib/ratatui_ruby/widgets/line_gauge.rb', line 108

def filled?
  ratio > 0
end

#percent ⇒ Object

Returns the progress as an integer percentage (0-100).

LineGauge stores progress as a ratio (0.0 to 1.0). User-facing code often displays percentages. Converting manually is tedious.

This is the inverse of passing percent: to the constructor. Rounds down to the nearest integer.

Example

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

lg = Widgets::LineGauge.new(percent: 75)
lg.percent  # => 75

lg = Widgets::LineGauge.new(ratio: 0.456)
lg.percent  # => 45

– SPDX-SnippetEnd ++



153
154
155
 
# File 'lib/ratatui_ruby/widgets/line_gauge.rb', line 153

def percent
  (ratio * 100).to_i
end