class RatatuiRuby::Widgets::LineGauge
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
Attributes
Optional wrapping block.
Style for the completed portion.
Character for filled segments.
Optional label (String or Text::Span for rich styling).
Progress ratio from 0.0 to 1.0.
Base style applied to the entire gauge.
Style for the remainder.
Character for empty segments.
Public Class Methods
Source
# 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
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_styleunfilled_style- block
filled_symbol-
String (default:
"█"). unfilled_symbol-
String (default:
"░").
Raises ArgumentError if percent is not 0..100.
Public Instance Methods
Source
# File lib/ratatui_ruby/widgets/line_gauge.rb, line 126 def complete? ratio >= 1.0 end
Returns true if the gauge is at 100% or more (ratio >= 1.0).
Example
Widgets::LineGauge.new(ratio: 0.99).complete? # => false Widgets::LineGauge.new(ratio: 1.0).complete? # => true
Source
# File lib/ratatui_ruby/widgets/line_gauge.rb, line 108 def filled? ratio > 0 end
Returns true if the gauge has any fill (ratio > 0).
Example
Widgets::LineGauge.new(ratio: 0.0).filled? # => false Widgets::LineGauge.new(ratio: 0.5).filled? # => true
Source
# File lib/ratatui_ruby/widgets/line_gauge.rb, line 153 def percent (ratio * 100).to_i end
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
lg = Widgets::LineGauge.new(percent: 75) lg.percent # => 75 lg = Widgets::LineGauge.new(ratio: 0.456) lg.percent # => 45