Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(Gauge): add documentation to Gauge #514

Merged
merged 1 commit into from Sep 18, 2023
Merged

docs(Gauge): add documentation to Gauge #514

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
112 changes: 106 additions & 6 deletions src/widgets/gauge.rs
View file
Open in desktop
@@ -1,3 +1,4 @@
#![deny(missing_docs)]
use crate::{
buffer::Buffer,
layout::Rect,
Expand All @@ -7,18 +8,36 @@ use crate::{
widgets::{Block, Widget},
};

/// A widget to display a task progress.
/// A widget to display a progress bar.
///
/// # Examples:
/// A `Gauge` renders a bar filled according to the value given to [`Gauge::percent`] or
/// [`Gauge::ratio`]. The bar width and height are defined by the [`Rect`] it is
/// [rendered](Widget::render) in.
/// The associated label is always centered horizontally and vertically. If not set with
/// [`Gauge::label`], the label is the percentage of the bar filled.
/// You might want to have a higher precision bar using [`Gauge::use_unicode`].
///
/// This can be useful to indicate the progression of a task, like a download.
///
/// # Example
///
/// ```
/// use ratatui::{prelude::*, widgets::*};
///
/// Gauge::default()
/// .block(Block::default().borders(Borders::ALL).title("Progress"))
/// .gauge_style(Style::default().fg(Color::White).bg(Color::Black).add_modifier(Modifier::ITALIC))
/// .gauge_style(
/// Style::default()
/// .fg(Color::White)
/// .bg(Color::Black)
/// .add_modifier(Modifier::ITALIC),
/// )
/// .percent(20);
/// ```
///
/// # See also
///
/// - [`LineGauge`] for a thin progress bar
#[derive(Debug, Clone, PartialEq)]
pub struct Gauge<'a> {
block: Option<Block<'a>>,
Expand All @@ -43,11 +62,24 @@ impl<'a> Default for Gauge<'a> {
}

impl<'a> Gauge<'a> {
/// Surrounds the `Gauge` with a [`Block`].
Valentin271 marked this conversation as resolved.
Show resolved Hide resolved
///
/// The gauge is rendered in the inner portion of the block once space for borders and padding
/// is reserved. Styles set on the block do **not** affect the bar itself.
pub fn block(mut self, block: Block<'a>) -> Gauge<'a> {
self.block = Some(block);
self
}

/// Sets the bar progression from a percentage.
///
/// # Panics
///
/// This method panics if `percent` is **not** between 0 and 100 inclusively.
///
/// # See also
///
/// See [`Gauge::ratio`] to set from a float.
pub fn percent(mut self, percent: u16) -> Gauge<'a> {
Valentin271 marked this conversation as resolved.
Show resolved Hide resolved
assert!(
percent <= 100,
Expand All @@ -57,7 +89,18 @@ impl<'a> Gauge<'a> {
self
}

/// Sets ratio ([0.0, 1.0]) directly.
/// 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.
///
/// # See also
///
/// See [`Gauge::percent`] to set from a percentage.
pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
assert!(
(0.0..=1.0).contains(&ratio),
Expand All @@ -67,6 +110,10 @@ impl<'a> Gauge<'a> {
self
}

/// Sets the label to display in the center of the bar.
///
/// For a left-aligned label, see [`LineGauge`].
/// If the label is not defined, it is the percentage filled.
pub fn label<T>(mut self, label: T) -> Gauge<'a>
where
T: Into<Span<'a>>,
Expand All @@ -75,16 +122,26 @@ impl<'a> Gauge<'a> {
self
}

/// Sets the widget style.
///
/// This will style the block (if any non-styled) and background of the widget (everything
/// except the bar itself). [`Block`] style set with [`Gauge::block`] takes precedence.
pub fn style(mut self, style: Style) -> Gauge<'a> {
self.style = style;
self
}

/// Sets the style of the bar.
pub fn gauge_style(mut self, style: Style) -> Gauge<'a> {
self.gauge_style = style;
self
}

/// Sets whether to use unicode characters to display the progress bar.
///
/// This enables the use of
/// [unicode block characters](https://en.wikipedia.org/wiki/Block_Elements).
/// This is useful to display a higher precision bar (8 extra fractional parts per cell).
pub fn use_unicode(mut self, unicode: bool) -> Gauge<'a> {
self.use_unicode = unicode;
self
Expand Down Expand Up @@ -165,7 +222,16 @@ fn get_unicode_block<'a>(frac: f64) -> &'a str {
}
}

/// A compact widget to display a task progress over a single line.
/// A compact widget to display a progress bar over a single thin line.
///
/// 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](Widget::render) [`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`].
///
/// This can be useful to indicate the progression of a task, like a download.
///
/// # Examples:
///
Expand All @@ -174,10 +240,19 @@ fn get_unicode_block<'a>(frac: f64) -> &'a str {
///
/// LineGauge::default()
/// .block(Block::default().borders(Borders::ALL).title("Progress"))
/// .gauge_style(Style::default().fg(Color::White).bg(Color::Black).add_modifier(Modifier::BOLD))
/// .gauge_style(
/// Style::default()
/// .fg(Color::White)
/// .bg(Color::Black)
/// .add_modifier(Modifier::BOLD),
/// )
/// .line_set(symbols::line::THICK)
/// .ratio(0.4);
/// ```
///
/// # See also
///
/// - [`Gauge`] for bigger, higher precision and more configurable progress bar
#[derive(Debug, Default, Clone, PartialEq)]
pub struct LineGauge<'a> {
block: Option<Block<'a>>,
Expand All @@ -189,11 +264,20 @@ pub struct LineGauge<'a> {
}

impl<'a> LineGauge<'a> {
/// Surrounds the `LineGauge` with a [`Block`].
Valentin271 marked this conversation as resolved.
Show resolved Hide resolved
pub fn block(mut self, block: Block<'a>) -> Self {
self.block = Some(block);
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 fn ratio(mut self, ratio: f64) -> Self {
assert!(
(0.0..=1.0).contains(&ratio),
Expand All @@ -203,11 +287,22 @@ impl<'a> LineGauge<'a> {
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`](symbols::line::NORMAL), [`DOUBLE`](symbols::line::DOUBLE) and
/// [`THICK`](symbols::line::THICK).
pub fn line_set(mut self, set: symbols::line::Set) -> Self {
self.line_set = set;
self
}

/// 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 label<T>(mut self, label: T) -> Self
where
T: Into<Line<'a>>,
Expand All @@ -216,11 +311,16 @@ impl<'a> LineGauge<'a> {
self
}

/// Sets the widget style.
///
/// This will style everything except the bar itself, so basically the block (if any) and
/// background.
pub fn style(mut self, style: Style) -> Self {
self.style = style;
self
}

/// Sets the style of the bar.
pub fn gauge_style(mut self, style: Style) -> Self {
self.gauge_style = style;
self
Expand Down