Class: RatatuiRuby::Widgets::Gauge

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

Overview

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

Instance Method Summary collapse

Methods included from CoerceableWidget

included

Constructor Details

#initialize(ratio: nil, percent: nil, label: nil, style: nil, gauge_style: nil, block: nil, use_unicode: true) ⇒ Gauge

Creates a new Gauge.

ratio

Float (0.0 - 1.0).

percent

Integer (0 - 100), alternative to ratio.

label

String or Text::Span (optional).

style

Style object for the background (optional).

gauge_style

Style object for the filled bar (optional).

block

Block widget (optional).

use_unicode

Boolean (default: true).

Raises ArgumentError if percent is not 0..100.



69
70
71
72
73
74
75
76
77
78
79
80
 
# 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

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::Gauge.new(ratio: 0.99).complete?  # => false
Widgets::Gauge.new(ratio: 1.0).complete?   # => true

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/ratatui_ruby/widgets/gauge.rb', line 114

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::Gauge.new(ratio: 0.0).filled?  # => false
Widgets::Gauge.new(ratio: 0.5).filled?  # => true

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/ratatui_ruby/widgets/gauge.rb', line 96

def filled?
  ratio > 0
end

#percent ⇒ Object

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

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

gauge = Widgets::Gauge.new(percent: 75)
gauge.percent  # => 75

gauge = Widgets::Gauge.new(ratio: 0.456)
gauge.percent  # => 45

– SPDX-SnippetEnd ++



141
142
143
 
# File 'lib/ratatui_ruby/widgets/gauge.rb', line 141

def percent
  (ratio * 100).to_i
end