Mirrors/ratatui
2
0
Fork 0
mirror of https://github.com/ratatui-org/ratatui synced 2024-11-22 04:33:13 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs(barchart): add documentation to BarChart (#449)

Browse source 
Add documentation to the `BarChart` widgets and its sub-modules.
This commit is contained in:
Valentin271 2023-09-02 04:59:35 +02:00 committed by GitHub
parent 5f6aa30be5
commit e098731d6c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 187 additions and 24 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

55
src/widgets/barchart/bar.rs
View file

@ -1,11 +1,19 @@
use crate::{buffer::Buffer, prelude::Rect, style::Style, text::Line};
/// represent a bar to be shown by the Barchart
/// A bar to be shown by the [`BarChart`](crate::widgets::BarChart) widget.
///
/// # Examples
/// the following example creates a bar with the label "Bar 1", a value "10",
/// red background and a white value foreground
/// Here is an explanation of a `Bar`'s components.
/// ```plain
/// ███ ┐
/// █2█ <- text_value or value │ bar
/// foo <- label ┘
/// ```
/// Note that every element can be styled individually.
///
/// # Example
///
/// The following example creates a bar with the label "Bar 1", a value "10",
/// red background and a white value foreground.
/// ```
/// # use ratatui::{prelude::*, widgets::*};
/// Bar::default()
@ -30,34 +38,67 @@ pub struct Bar<'a> {
}
impl<'a> Bar<'a> {
/// Set the value of this bar.
///
/// The value will be displayed inside the bar.
///
/// # See also
///
/// [`Bar::value_style`] to style the value.
/// [`Bar::text_value`] to set the displayed value.
pub fn value(mut self, value: u64) -> Bar<'a> {
self.value = value;
self
}
/// Set the label of the bar.
///
/// For [`Vertical`](crate::layout::Direction::Vertical) bars,
/// display the label **under** the bar.
/// For [`Horizontal`](crate::layout::Direction::Horizontal) bars,
/// display the label **in** the bar.
/// See [`BarChart::direction`](crate::widgets::BarChart::direction) to set the direction.
pub fn label(mut self, label: Line<'a>) -> Bar<'a> {
self.label = Some(label);
self
}
/// Set the style of the bar.
///
/// This will apply to every non-styled element.
/// It can be seen and used as a default value.
pub fn style(mut self, style: Style) -> Bar<'a> {
self.style = style;
self
}
/// Set the style of the value.
///
/// # See also
///
/// [`Bar::value`] to set the value.
pub fn value_style(mut self, style: Style) -> Bar<'a> {
self.value_style = style;
self
}
/// set the text value printed in the bar. (By default self.value is printed)
/// Set the text value printed in the bar.
///
/// If `text_value` is not set, then the [ToString] representation of `value` will be shown on
/// the bar.
///
/// # See also
///
/// [`Bar::value`] to set the value.
pub fn text_value(mut self, text_value: String) -> Bar<'a> {
self.text_value = Some(text_value);
self
}
/// Render the value of the bar. value_text is used if set, otherwise the value is converted to
/// string. The value is rendered using value_style. If the value width is greater than the
/// Render the value of the bar.
///
/// [`text_value`](Bar::text_value) is used if set, otherwise the value is converted to string.
/// The value is rendered using value_style. If the value width is greater than the
/// bar width, then the value is split into 2 parts. the first part is rendered in the bar
/// using value_style. The second part is rendered outside the bar using bar_style
pub(super) fn render_value_with_different_styles(

5
src/widgets/barchart/bar_group.rs
View file

@ -5,9 +5,10 @@ use crate::{
text::Line,
};
/// represent a group of bars to be shown by the Barchart
/// A group of bars to be shown by the Barchart.
///
/// # Examples
///
/// ```
/// # use ratatui::{prelude::*, widgets::*};
/// BarGroup::default()
@ -35,7 +36,7 @@ impl<'a> BarGroup<'a> {
self
}
/// return the maximum bar value of this group
/// The maximum bar value of this group
pub(super) fn max(&self) -> Option<u64> {
self.bars.iter().max_by_key(|v| v.value).map(|v| v.value)
}

151
src/widgets/barchart/mod.rs
View file

@ -1,3 +1,4 @@
#![warn(missing_docs)]
use crate::prelude::*;
mod bar;
@ -8,14 +9,41 @@ pub use bar_group::BarGroup;
use super::{Block, Widget};
/// Display multiple bars in a single widgets
/// A chart showing values as [bars](Bar).
///
/// Here is a possible `BarChart` output.
/// ```plain
/// ┌─────────────────────────────────┐
/// │ ████│
/// │ ▅▅▅▅ ████│
/// │ ▇▇▇▇ ████ ████│
/// │ ▄▄▄▄ ████ ████ ████ ████│
/// │▆10▆ █20█ █50█ █40█ █60█ █90█│
/// │ B1 B2 B1 B2 B1 B2 │
/// │ Group1 Group2 Group3 │
/// └─────────────────────────────────┘
/// ```
///
/// A `BarChart` is composed of a set of [`Bar`] which can be set via [`BarChart::data`].
/// Bars can be styled globally ([`BarChart::bar_style`]) or individually ([`Bar::style`]).
/// There are other methods available to style even more precisely. See [`Bar`] to find out about
/// each bar component.
///
/// The `BarChart` widget can also show groups of bars via [`BarGroup`].
/// A [`BarGroup`] is a set of [`Bar`], multiple can be added to a `BarChart` using
/// [`BarChart::data`] multiple time as demonstrated in the example below.
///
/// The chart can have a [`Direction`] (by default the bars are [`Vertical`](Direction::Vertical)).
/// This is set using [`BarChart::direction`].
///
/// # Examples
/// The following example creates a BarChart with two groups of bars.
/// The first group is added by an array slice (&[(&str, u64)]).
/// The second group is added by a slice of Groups (&[BarGroup]).
///
/// The following example creates a `BarChart` with two groups of bars.
/// The first group is added by an array slice (`&[(&str, u64)]`).
/// The second group is added by a [`BarGroup`] instance.
/// ```
/// # use ratatui::{prelude::*, widgets::*};
/// use ratatui::{prelude::*, widgets::*};
///
/// BarChart::default()
/// .block(Block::default().title("BarChart").borders(Borders::ALL))
/// .bar_width(3)
@ -78,16 +106,18 @@ impl<'a> Default for BarChart<'a> {
impl<'a> BarChart<'a> {
/// Add group of bars to the BarChart
///
/// # Examples
/// The following example creates a BarChart with two groups of bars.
/// The first group is added by an array slice (&[(&str, u64)]).
/// The second group is added by a BarGroup instance.
///
/// The following example creates a BarChart with two groups of bars.
/// The first group is added by an array slice (`&[(&str, u64)]`).
/// The second group is added by a [`BarGroup`] instance.
/// ```
/// # use ratatui::{prelude::*, widgets::*};
/// use ratatui::{prelude::*, widgets::*};
///
/// BarChart::default()
/// .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
/// .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)]));
/// .data(&[("B0", 0), ("B1", 2), ("B2", 4), ("B3", 3)])
/// .data(BarGroup::default().bars(&[Bar::default().value(10), Bar::default().value(20)]));
/// ```
pub fn data(mut self, data: impl Into<BarGroup<'a>>) -> BarChart<'a> {
let group: BarGroup = data.into();
@ -97,66 +127,157 @@ impl<'a> BarChart<'a> {
self
}
/// Surround the [`BarChart`] with a [`Block`].
pub fn block(mut self, block: Block<'a>) -> BarChart<'a> {
self.block = Some(block);
self
}
/// Set the value necessary for a [`Bar`] to reach the maximum height.
///
/// If not set, the maximum value in the data is taken as reference.
///
/// # Examples
///
/// This example shows the default behavior when `max` is not set.
/// The maximum value in the dataset is taken (here, `100`).
/// ```
/// # use ratatui::widgets::BarChart;
/// BarChart::default().data(&[("foo", 1), ("bar", 2), ("baz", 100)]);
/// // Renders
/// // █
/// // █
/// // f b b
/// ```
///
/// This example shows a custom max value.
/// The maximum height being `2`, `bar` & `baz` render as the max.
/// ```
/// # use ratatui::widgets::BarChart;
/// BarChart::default()
/// .data(&[("foo", 1), ("bar", 2), ("baz", 100)])
/// .max(2);
/// // Renders
/// // █ █
/// // █ █ █
/// // f b b
/// ```
pub fn max(mut self, max: u64) -> BarChart<'a> {
self.max = Some(max);
self
}
/// Set the default style of the bar.
/// It is also possible to set individually the style of each Bar.
///
/// It is also possible to set individually the style of each [`Bar`].
/// In this case the default style will be patched by the individual style
pub fn bar_style(mut self, style: Style) -> BarChart<'a> {
self.bar_style = style;
self
}
/// Set the width of the displayed bars.
///
/// For [`Horizontal`](crate::layout::Direction::Horizontal) bars this becomes the height of
/// the bar.
///
/// If not set, this defaults to `1`.
/// The bar label also uses this value as its width.
pub fn bar_width(mut self, width: u16) -> BarChart<'a> {
self.bar_width = width;
self
}
/// Set the gap between each bar.
///
/// If not set, this defaults to `1`.
/// The bar label will never be larger than the bar itself, even if the gap is sufficient.
///
/// # Example
///
/// This shows two bars with a gap of `3`. Notice the labels will always stay under the bar.
/// ```
/// # use ratatui::widgets::BarChart;
/// BarChart::default()
/// .data(&[("foo", 1), ("bar", 2)])
/// .bar_gap(3);
/// // Renders
/// // █
/// // █ █
/// // f b
/// ```
pub fn bar_gap(mut self, gap: u16) -> BarChart<'a> {
self.bar_gap = gap;
self
}
/// The [`bar::Set`](crate::symbols::bar::Set) to use for displaying the bars.
///
/// If not set, the default is [`bar::NINE_LEVELS`](crate::symbols::bar::NINE_LEVELS).
pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> BarChart<'a> {
self.bar_set = bar_set;
self
}
/// Set the default value style of the bar.
/// It is also possible to set individually the value style of each Bar.
///
/// It is also possible to set individually the value style of each [`Bar`].
/// In this case the default value style will be patched by the individual value style
///
/// # See also
///
/// [Bar::value_style] to set the value style individually.
pub fn value_style(mut self, style: Style) -> BarChart<'a> {
self.value_style = style;
self
}
/// Set the default label style of the groups and bars.
/// It is also possible to set individually the label style of each Bar or Group.
///
/// It is also possible to set individually the label style of each [`Bar`] or [`BarGroup`].
/// In this case the default label style will be patched by the individual label style
///
/// # See also
///
/// [Bar::label] to set the label style individually.
pub fn label_style(mut self, style: Style) -> BarChart<'a> {
self.label_style = style;
self
}
/// Set the gap between [`BarGroup`].
pub fn group_gap(mut self, gap: u16) -> BarChart<'a> {
self.group_gap = gap;
self
}
/// Set the style of the entire chart.
///
/// The style will be applied to everything that isn't styled (borders, bars, labels, ...).
pub fn style(mut self, style: Style) -> BarChart<'a> {
self.style = style;
self
}
/// Set the direction of the bars
/// Set the direction of the bars.
///
/// [`Vertical`](crate::layout::Direction::Vertical) bars are the default.
///
/// # Examples
///
/// Vertical bars
/// ```plain
/// █
/// █ █
/// f b
/// ```
///
/// Horizontal bars
/// ```plain
/// █foo██
///
/// █bar██
/// ```
pub fn direction(mut self, direction: Direction) -> BarChart<'a> {
self.direction = direction;
self