class RatatuiRuby::Widgets::Gauge
Displays a standard progress bar.
Long-running tasks create anxiety. Users need to know that the system is working and how much is left to do.
This widget visualizes completion. It fills a bar based on a percentage.
Use it for downloads, installations, or processing jobs.
Example
Run the interactive demo from the terminal:
ruby examples/widget_gauge/app.rb
Attributes
Optional wrapping block.
Style applied specifically to the filled bar portion (optional).
Text label to display (optional).
Accepts String or Text::Span for rich styling.
If nil, it often displays the percentage automatically depending on renderer logic, but explicit labels are preferred.
Progress ratio from 0.0 to 1.0.
Base style applied to the entire gauge background (optional).
Whether to use Unicode block characters (true) or ASCII characters (false). Default is false (ASCII) to be conservative, though Ratatui defaults to true.
Public Class Methods
Source
# File lib/ratatui_ruby/widgets/gauge.rb, line 69 def initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true) 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 # Float(Numeric) incorrectly returns Float? -- https://github.com/ruby/rbs/issues/2793 ratio = float_percent / 100.0 #: Float end ratio = Float(ratio || 0.0) super(ratio:, label:, style:, gauge_style:, block:, use_unicode:) end
Creates a new Gauge.
- ratio
-
Float (0.0 - 1.0).
- percent
-
Integer (0 - 100), alternative to ratio.
- label
-
String or
Text::Span(optional). - style
-
Styleobject for the background (optional). gauge_style-
Styleobject for the filled bar (optional). - block
-
Blockwidget (optional). use_unicode-
Boolean (default: true).
Raises ArgumentError if percent is not 0..100.
Public Instance Methods
Source
# File lib/ratatui_ruby/widgets/gauge.rb, line 114 def complete? ratio >= 1.0 end
Returns true if the gauge is at 100% or more (ratio >= 1.0).
Example
Widgets::Gauge.new(ratio: 0.99).complete? # => false Widgets::Gauge.new(ratio: 1.0).complete? # => true
Source
# File lib/ratatui_ruby/widgets/gauge.rb, line 96 def filled? ratio > 0 end
Returns true if the gauge has any fill (ratio > 0).
Example
Widgets::Gauge.new(ratio: 0.0).filled? # => false Widgets::Gauge.new(ratio: 0.5).filled? # => true
Source
# File lib/ratatui_ruby/widgets/gauge.rb, line 141 def percent (ratio * 100).to_i end
Returns the progress as an integer percentage (0-100).
Gauge 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
gauge = Widgets::Gauge.new(percent: 75) gauge.percent # => 75 gauge = Widgets::Gauge.new(ratio: 0.456) gauge.percent # => 45