Struct LineGauge

pub struct LineGauge<'a> { /* private fields */ }

A compact widget to display a progress bar over a single thin line.

This can be useful to indicate the progression of a task, like a download.

A LineGauge renders a thin line filled according to the value given to LineGauge::ratio. Unlike Gauge, only the width can be defined by the rendering Rect. The height is always 1.

The associated label is always left-aligned. If not set with LineGauge::label, the label is the percentage of the bar filled.

You can also set the symbols used to draw the bar with LineGauge::line_set.

To style the gauge line use LineGauge::filled_style and LineGauge::unfilled_style which let you pick a color for foreground (i.e. line) and background of the filled and unfilled part of gauge respectively.

Examples:

use ratatui::{
    style::{Style, Stylize},
    symbols,
    widgets::{Block, LineGauge},
};

LineGauge::default()
    .block(Block::bordered().title("Progress"))
    .filled_style(Style::new().white().on_black().bold())
    .line_set(symbols::line::THICK)
    .ratio(0.4);

See also

• Gauge for bigger, higher precision and more configurable progress bar

Implementations

impl<'a> LineGauge<'a>

pub fn block(self, block: Block<'a>) -> Self

Surrounds the LineGauge with a Block.

pub fn ratio(self, ratio: f64) -> Self

Sets the bar progression from a ratio (float).

ratio is the ratio between filled bar over empty bar (i.e. 3/4 completion is 0.75). This is more easily seen as a floating point percentage (e.g. 42% = 0.42).

Panics

This method panics if ratio is not between 0 and 1 inclusively.

pub const fn line_set(self, set: Set) -> Self

Sets the characters to use for the line.

See also

See symbols::line::Set for more information. Predefined sets are also available, see NORMAL, DOUBLE and THICK.

pub fn label<T>(self, label: T) -> Self

where T: Into<Line<'a>>,

Sets the label to display.

With LineGauge, labels are only on the left, see Gauge for a centered label. If the label is not defined, it is the percentage filled.

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the widget style.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This will style everything except the bar itself, so basically the block (if any) and background.

pub fn gauge_style<S: Into<Style>>(self, style: S) -> Self

👎Deprecated since 0.27.0: You should use LineGauge::filled_style instead.

Sets the style of the bar.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

pub fn filled_style<S: Into<Style>>(self, style: S) -> Self

Sets the style of filled part of the bar.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

pub fn unfilled_style<S: Into<Style>>(self, style: S) -> Self

Sets the style of the unfilled part of the bar.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Trait Implementations

impl<'a> Clone for LineGauge<'a>

fn clone(&self) -> LineGauge<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for LineGauge<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for LineGauge<'a>

fn default() -> LineGauge<'a>

Returns the “default value” for a type.

impl<'a> PartialEq for LineGauge<'a>

fn eq(&self, other: &LineGauge<'a>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Styled for LineGauge<'a>

type Item = LineGauge<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for LineGauge<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for LineGauge<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> StructuralPartialEq for LineGauge<'a>