Mirrors/ratatui
2
0
Fork 0
mirror of https://github.com/ratatui-org/ratatui synced 2024-11-10 15:14:27 +00:00
Code Issues Projects Releases Packages Wiki Activity

chore: Correct "builder methods" in docs and add must_use on widgets setters (#655)

Browse source 
Fixes #650

This PR corrects the "builder methods" expressing to simple `setters`
(see #650 #655), and gives a clearer diagnostic notice on setters `must_use`.

`#[must_use = "method moves the value of self and returns the modified value"]`

Details:

    docs: Correct wording in docs from builder methods

    Add `must_use` on layout setters

    chore: add `must_use` on widgets fluent methods

        This commit ignored `table.rs` because it is included in other PRs.

    test(gauge): fix test
This commit is contained in:
tieway59 2023-12-06 22:39:52 +08:00 committed by GitHub
parent 4424637af2
commit dd22e721e3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
14 changed files with 115 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
src/layout.rs
View file

@ -350,6 +350,7 @@ impl Layout {
/// let layout = Layout::default().constraints([Constraint::Min(0)].iter().filter(|_| true));
/// let layout = Layout::default().constraints([1,2,3].iter().map(|&c| Constraint::Length(c)));
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn constraints<I>(mut self, constraints: I) -> Layout
where
I: IntoIterator,
@ -359,7 +360,7 @@ impl Layout {
self
}
/// Builder method to set the margin of the layout.
/// Set the margin of the layout.
///
/// # Examples
///
@ -371,6 +372,7 @@ impl Layout {
/// .split(Rect::new(0, 0, 10, 10));
/// assert_eq!(layout[..], [Rect::new(2, 2, 6, 6)]);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn margin(mut self, margin: u16) -> Layout {
self.margin = Margin {
horizontal: margin,
@ -379,7 +381,7 @@ impl Layout {
self
}
/// Builder method to set the horizontal margin of the layout.
/// Set the horizontal margin of the layout.
///
/// # Examples
///
@ -391,12 +393,13 @@ impl Layout {
/// .split(Rect::new(0, 0, 10, 10));
/// assert_eq!(layout[..], [Rect::new(2, 0, 6, 10)]);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn horizontal_margin(mut self, horizontal: u16) -> Layout {
self.margin.horizontal = horizontal;
self
}
/// Builder method to set the vertical margin of the layout.
/// Set the vertical margin of the layout.
///
/// # Examples
///
@ -408,12 +411,13 @@ impl Layout {
/// .split(Rect::new(0, 0, 10, 10));
/// assert_eq!(layout[..], [Rect::new(0, 2, 10, 6)]);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn vertical_margin(mut self, vertical: u16) -> Layout {
self.margin.vertical = vertical;
self
}
/// Builder method to set the direction of the layout.
/// Set the direction of the layout.
///
/// # Examples
///
@ -431,12 +435,13 @@ impl Layout {
/// .split(Rect::new(0, 0, 10, 10));
/// assert_eq!(layout[..], [Rect::new(0, 0, 10, 5), Rect::new(0, 5, 10, 5)]);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn direction(mut self, direction: Direction) -> Layout {
self.direction = direction;
self
}
/// Builder method to set whether chunks should be of equal size.
/// Set whether chunks should be of equal size.
///
/// This determines how the space is distributed when the constraints are satisfied. By default,
/// the last chunk is expanded to fill the remaining space, but this can be changed to prefer
@ -452,6 +457,7 @@ impl Layout {
reason = "The name for this feature is not final and may change in the future",
issue = "https://github.com/ratatui-org/ratatui/issues/536"
)]
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn segment_size(mut self, segment_size: SegmentSize) -> Layout {
self.segment_size = segment_size;
self

8
src/title.rs
View file

@ -87,7 +87,7 @@ pub enum Position {
}
impl<'a> Title<'a> {
/// Builder pattern method for setting the title content.
/// Set the title content.
pub fn content<T>(mut self, content: T) -> Title<'a>
where
T: Into<Line<'a>>,
@ -96,13 +96,15 @@ impl<'a> Title<'a> {
self
}
/// Builder pattern method for setting the title alignment.
/// Set the title alignment.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn alignment(mut self, alignment: Alignment) -> Title<'a> {
self.alignment = Some(alignment);
self
}
/// Builder pattern method for setting the title position.
/// Set the title position.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn position(mut self, position: Position) -> Title<'a> {
self.position = Some(position);
self

4
src/widgets.rs
View file

@ -1,7 +1,7 @@
//! `widgets` is a collection of types that implement [`Widget`] or [`StatefulWidget`] or both.
//!
//! All widgets are implemented using the builder pattern and are consumable objects. They are not
//! meant to be stored but used as *commands* to draw common figures in the UI.
//! Widgets are created for each frame as they are consumed after rendered.
//! They are not meant to be stored but used as *commands* to draw common figures in the UI.
//!
//! The available widgets are:
//! - [`Block`]: a basic widget that draws a block with optional borders, titles and styles.

11
src/widgets/barchart.rs
View file

@ -127,6 +127,7 @@ impl<'a> BarChart<'a> {
}
/// Surround the [`BarChart`] with a [`Block`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> BarChart<'a> {
self.block = Some(block);
self
@ -161,6 +162,7 @@ impl<'a> BarChart<'a> {
/// // █ █ █
/// // f b b
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn max(mut self, max: u64) -> BarChart<'a> {
self.max = Some(max);
self
@ -170,6 +172,7 @@ impl<'a> BarChart<'a> {
///
/// 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
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bar_style(mut self, style: Style) -> BarChart<'a> {
self.bar_style = style;
self
@ -182,6 +185,7 @@ impl<'a> BarChart<'a> {
///
/// If not set, this defaults to `1`.
/// The bar label also uses this value as its width.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bar_width(mut self, width: u16) -> BarChart<'a> {
self.bar_width = width;
self
@ -205,6 +209,7 @@ impl<'a> BarChart<'a> {
/// // █ █
/// // f b
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bar_gap(mut self, gap: u16) -> BarChart<'a> {
self.bar_gap = gap;
self
@ -213,6 +218,7 @@ impl<'a> BarChart<'a> {
/// 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).
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> BarChart<'a> {
self.bar_set = bar_set;
self
@ -226,6 +232,7 @@ impl<'a> BarChart<'a> {
/// # See also
///
/// [Bar::value_style] to set the value style individually.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn value_style(mut self, style: Style) -> BarChart<'a> {
self.value_style = style;
self
@ -239,12 +246,14 @@ impl<'a> BarChart<'a> {
/// # See also
///
/// [Bar::label] to set the label style individually.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn label_style(mut self, style: Style) -> BarChart<'a> {
self.label_style = style;
self
}
/// Set the gap between [`BarGroup`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn group_gap(mut self, gap: u16) -> BarChart<'a> {
self.group_gap = gap;
self
@ -253,6 +262,7 @@ impl<'a> BarChart<'a> {
/// Set the style of the entire chart.
///
/// The style will be applied to everything that isn't styled (borders, bars, labels, ...).
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> BarChart<'a> {
self.style = style;
self
@ -277,6 +287,7 @@ impl<'a> BarChart<'a> {
///
/// █bar██
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn direction(mut self, direction: Direction) -> BarChart<'a> {
self.direction = direction;
self

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

@ -49,6 +49,7 @@ impl<'a> Bar<'a> {
///
/// [`Bar::value_style`] to style the value.
/// [`Bar::text_value`] to set the displayed value.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn value(mut self, value: u64) -> Bar<'a> {
self.value = value;
self
@ -61,6 +62,7 @@ impl<'a> Bar<'a> {
/// For [`Horizontal`](crate::layout::Direction::Horizontal) bars,
/// display the label **in** the bar.
/// See [`BarChart::direction`](crate::widgets::BarChart::direction) to set the direction.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn label(mut self, label: Line<'a>) -> Bar<'a> {
self.label = Some(label);
self
@ -70,6 +72,7 @@ impl<'a> Bar<'a> {
///
/// This will apply to every non-styled element.
/// It can be seen and used as a default value.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Bar<'a> {
self.style = style;
self
@ -80,6 +83,7 @@ impl<'a> Bar<'a> {
/// # See also
///
/// [`Bar::value`] to set the value.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn value_style(mut self, style: Style) -> Bar<'a> {
self.value_style = style;
self
@ -93,6 +97,7 @@ impl<'a> Bar<'a> {
/// # See also
///
/// [`Bar::value`] to set the value.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn text_value(mut self, text_value: String) -> Bar<'a> {
self.text_value = Some(text_value);
self

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

@ -26,12 +26,14 @@ pub struct BarGroup<'a> {
impl<'a> BarGroup<'a> {
/// Set the group label
#[must_use = "method moves the value of self and returns the modified value"]
pub fn label(mut self, label: Line<'a>) -> BarGroup<'a> {
self.label = Some(label);
self
}
/// Set the bars of the group to be shown
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bars(mut self, bars: &[Bar<'a>]) -> BarGroup<'a> {
self.bars = bars.to_vec();
self

9
src/widgets/block.rs
View file

@ -329,6 +329,7 @@ impl<'a> Block<'a> {
/// Applies the style to all titles.
///
/// If a [`Title`] already has a style, the title's style will add on top of this one.
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn title_style(mut self, style: Style) -> Block<'a> {
self.titles_style = style;
self
@ -352,6 +353,7 @@ impl<'a> Block<'a> {
/// .title("bar")
/// .title_alignment(Alignment::Center);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn title_alignment(mut self, alignment: Alignment) -> Block<'a> {
self.titles_alignment = alignment;
self
@ -381,6 +383,7 @@ impl<'a> Block<'a> {
/// .title("bar")
/// .title_position(Position::Bottom);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn title_position(mut self, position: Position) -> Block<'a> {
self.titles_position = position;
self
@ -399,6 +402,7 @@ impl<'a> Block<'a> {
/// .borders(Borders::ALL)
/// .border_style(Style::new().blue());
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn border_style(mut self, style: Style) -> Block<'a> {
self.border_style = style;
self
@ -411,6 +415,7 @@ impl<'a> Block<'a> {
/// [`Block::border_style`].
///
/// This will also apply to the widget inside that block, unless the inner widget is styled.
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn style(mut self, style: Style) -> Block<'a> {
self.style = style;
self
@ -433,6 +438,7 @@ impl<'a> Block<'a> {
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default().borders(Borders::LEFT | Borders::RIGHT);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn borders(mut self, flag: Borders) -> Block<'a> {
self.borders = flag;
self
@ -455,6 +461,7 @@ impl<'a> Block<'a> {
/// // │ │
/// // ╰─────╯
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn border_type(mut self, border_type: BorderType) -> Block<'a> {
self.border_set = border_type.to_border_set();
self
@ -473,6 +480,7 @@ impl<'a> Block<'a> {
/// // ╔Block╗
/// // ║ ║
/// // ╚═════╝
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn border_set(mut self, border_set: border::Set) -> Block<'a> {
self.border_set = border_set;
self
@ -569,6 +577,7 @@ impl<'a> Block<'a> {
/// // │ content │
/// // └───────────┘
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub const fn padding(mut self, padding: Padding) -> Block<'a> {
self.padding = padding;
self

14
src/widgets/chart.rs
View file

@ -43,6 +43,7 @@ impl<'a> Axis<'a> {
since = "0.10.0",
note = "You should use styling capabilities of `text::Line` given as argument of the `title` method to apply styling to the title."
)]
#[must_use = "method moves the value of self and returns the modified value"]
pub fn title_style(mut self, style: Style) -> Axis<'a> {
if let Some(t) = self.title {
let title = String::from(t);
@ -51,16 +52,19 @@ impl<'a> Axis<'a> {
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bounds(mut self, bounds: [f64; 2]) -> Axis<'a> {
self.bounds = bounds;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn labels(mut self, labels: Vec<Span<'a>>) -> Axis<'a> {
self.labels = Some(labels);
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Axis<'a> {
self.style = style;
self
@ -70,6 +74,7 @@ impl<'a> Axis<'a> {
/// The alignment behaves differently based on the axis:
/// - Y-Axis: The labels are aligned within the area on the left of the axis
/// - X-Axis: The first X-axis label is aligned relative to the Y-axis
#[must_use = "method moves the value of self and returns the modified value"]
pub fn labels_alignment(mut self, alignment: Alignment) -> Axis<'a> {
self.labels_alignment = alignment;
self
@ -110,21 +115,25 @@ impl<'a> Dataset<'a> {
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn data(mut self, data: &'a [(f64, f64)]) -> Dataset<'a> {
self.data = data;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn marker(mut self, marker: symbols::Marker) -> Dataset<'a> {
self.marker = marker;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn graph_type(mut self, graph_type: GraphType) -> Dataset<'a> {
self.graph_type = graph_type;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Dataset<'a> {
self.style = style;
self
@ -215,21 +224,25 @@ impl<'a> Chart<'a> {
}
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Chart<'a> {
self.block = Some(block);
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Chart<'a> {
self.style = style;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn x_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
self.x_axis = axis;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn y_axis(mut self, axis: Axis<'a>) -> Chart<'a> {
self.y_axis = axis;
self
@ -250,6 +263,7 @@ impl<'a> Chart<'a> {
/// let _chart: Chart = Chart::new(vec![])
/// .hidden_legend_constraints(constraints);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn hidden_legend_constraints(mut self, constraints: (Constraint, Constraint)) -> Chart<'a> {
self.hidden_legend_constraints = constraints;
self

18
src/widgets/gauge.rs
View file

@ -66,6 +66,7 @@ impl<'a> Gauge<'a> {
///
/// 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.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Gauge<'a> {
self.block = Some(block);
self
@ -80,6 +81,7 @@ impl<'a> Gauge<'a> {
/// # See also
///
/// See [`Gauge::ratio`] to set from a float.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn percent(mut self, percent: u16) -> Gauge<'a> {
assert!(
percent <= 100,
@ -101,6 +103,7 @@ impl<'a> Gauge<'a> {
/// # See also
///
/// See [`Gauge::percent`] to set from a percentage.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn ratio(mut self, ratio: f64) -> Gauge<'a> {
assert!(
(0.0..=1.0).contains(&ratio),
@ -114,6 +117,7 @@ impl<'a> Gauge<'a> {
///
/// For a left-aligned label, see [`LineGauge`].
/// If the label is not defined, it is the percentage filled.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn label<T>(mut self, label: T) -> Gauge<'a>
where
T: Into<Span<'a>>,
@ -126,12 +130,14 @@ impl<'a> Gauge<'a> {
///
/// 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.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Gauge<'a> {
self.style = style;
self
}
/// Sets the style of the bar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn gauge_style(mut self, style: Style) -> Gauge<'a> {
self.gauge_style = style;
self
@ -142,6 +148,7 @@ impl<'a> Gauge<'a> {
/// 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).
#[must_use = "method moves the value of self and returns the modified value"]
pub fn use_unicode(mut self, unicode: bool) -> Gauge<'a> {
self.use_unicode = unicode;
self
@ -265,6 +272,7 @@ pub struct LineGauge<'a> {
impl<'a> LineGauge<'a> {
/// Surrounds the `LineGauge` with a [`Block`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Self {
self.block = Some(block);
self
@ -278,6 +286,7 @@ impl<'a> LineGauge<'a> {
/// # Panics
///
/// This method panics if `ratio` is **not** between 0 and 1 inclusively.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn ratio(mut self, ratio: f64) -> Self {
assert!(
(0.0..=1.0).contains(&ratio),
@ -294,6 +303,7 @@ impl<'a> LineGauge<'a> {
/// 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).
#[must_use = "method moves the value of self and returns the modified value"]
pub fn line_set(mut self, set: symbols::line::Set) -> Self {
self.line_set = set;
self
@ -315,12 +325,14 @@ impl<'a> LineGauge<'a> {
///
/// This will style everything except the bar itself, so basically the block (if any) and
/// background.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Self {
self.style = style;
self
}
/// Sets the style of the bar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn gauge_style(mut self, style: Style) -> Self {
self.gauge_style = style;
self
@ -419,19 +431,19 @@ mod tests {
#[test]
#[should_panic]
fn gauge_invalid_percentage() {
Gauge::default().percent(110);
let _ = Gauge::default().percent(110);
}
#[test]
#[should_panic]
fn gauge_invalid_ratio_upper_bound() {
Gauge::default().ratio(1.1);
let _ = Gauge::default().ratio(1.1);
}
#[test]
#[should_panic]
fn gauge_invalid_ratio_lower_bound() {
Gauge::default().ratio(-0.5);
let _ = Gauge::default().ratio(-0.5);
}
#[test]

10
src/widgets/list.rs
View file

@ -23,11 +23,13 @@ impl ListState {
&mut self.offset
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn with_selected(mut self, selected: Option<usize>) -> Self {
self.selected = selected;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn with_offset(mut self, offset: usize) -> Self {
self.offset = offset;
self
@ -62,6 +64,7 @@ impl<'a> ListItem<'a> {
}
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> ListItem<'a> {
self.style = style;
self
@ -124,26 +127,31 @@ impl<'a> List<'a> {
}
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> List<'a> {
self.block = Some(block);
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> List<'a> {
self.style = style;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn highlight_symbol(mut self, highlight_symbol: &'a str) -> List<'a> {
self.highlight_symbol = Some(highlight_symbol);
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn highlight_style(mut self, style: Style) -> List<'a> {
self.highlight_style = style;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn repeat_highlight_symbol(mut self, repeat: bool) -> List<'a> {
self.repeat_highlight_symbol = repeat;
self
@ -152,11 +160,13 @@ impl<'a> List<'a> {
/// Set when to show the highlight spacing
///
/// See [`HighlightSpacing`] about which variant affects spacing in which way
#[must_use = "method moves the value of self and returns the modified value"]
pub fn highlight_spacing(mut self, value: HighlightSpacing) -> Self {
self.highlight_spacing = value;
self
}
#[must_use = "method moves the value of self and returns the modified value"]
pub fn start_corner(mut self, corner: Corner) -> List<'a> {
self.start_corner = corner;
self

5
src/widgets/paragraph.rs
View file

@ -138,6 +138,7 @@ impl<'a> Paragraph<'a> {
/// .title("Paragraph")
/// .borders(Borders::ALL));
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Paragraph<'a> {
self.block = Some(block);
self
@ -155,6 +156,7 @@ impl<'a> Paragraph<'a> {
/// let paragraph = Paragraph::new("Hello, world!")
/// .style(Style::new().red().on_white());
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Paragraph<'a> {
self.style = style;
self
@ -171,6 +173,7 @@ impl<'a> Paragraph<'a> {
/// let paragraph = Paragraph::new("Hello, world!")
/// .wrap(Wrap { trim: true });
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn wrap(mut self, wrap: Wrap) -> Paragraph<'a> {
self.wrap = Some(wrap);
self
@ -187,6 +190,7 @@ impl<'a> Paragraph<'a> {
///
/// For more information about future scrolling design and concerns, see [RFC: Design of
/// Scrollable Widgets](https://github.com/ratatui-org/ratatui/issues/174) on GitHub.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn scroll(mut self, offset: (Vertical, Horizontal)) -> Paragraph<'a> {
self.scroll = offset;
self
@ -204,6 +208,7 @@ impl<'a> Paragraph<'a> {
/// let paragraph = Paragraph::new("Hello World")
/// .alignment(Alignment::Center);
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn alignment(mut self, alignment: Alignment) -> Paragraph<'a> {
self.alignment = alignment;
self

15
src/widgets/scrollbar.rs
View file

@ -62,18 +62,21 @@ impl ScrollbarState {
}
}
/// Sets the scroll position of the scrollbar and returns the modified ScrollbarState.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn position(mut self, position: usize) -> Self {
self.position = position;
self
}
/// Sets the length of the scrollable content and returns the modified ScrollbarState.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn content_length(mut self, content_length: usize) -> Self {
self.content_length = content_length;
self
}
/// Sets the length of the viewport content and returns the modified ScrollbarState.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn viewport_content_length(mut self, viewport_content_length: usize) -> Self {
self.viewport_content_length = viewport_content_length;
self
@ -204,6 +207,7 @@ impl<'a> Scrollbar<'a> {
/// Sets the orientation of the scrollbar.
/// Resets the symbols to [`DOUBLE_VERTICAL`] or [`DOUBLE_HORIZONTAL`] based on orientation
#[must_use = "method moves the value of self and returns the modified value"]
pub fn orientation(mut self, orientation: ScrollbarOrientation) -> Self {
self.orientation = orientation;
let set = if self.is_vertical() {
@ -215,54 +219,63 @@ impl<'a> Scrollbar<'a> {
}
/// Sets the orientation and symbols for the scrollbar from a [`Set`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn orientation_and_symbol(mut self, orientation: ScrollbarOrientation, set: Set) -> Self {
self.orientation = orientation;
self.symbols(set)
}
/// Sets the symbol that represents the thumb of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn thumb_symbol(mut self, thumb_symbol: &'a str) -> Self {
self.thumb_symbol = thumb_symbol;
self
}
/// Sets the style that represents the thumb of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn thumb_style(mut self, thumb_style: Style) -> Self {
self.thumb_style = thumb_style;
self
}
/// Sets the symbol that represents the track of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn track_symbol(mut self, track_symbol: Option<&'a str>) -> Self {
self.track_symbol = track_symbol;
self
}
/// Sets the style that is used for the track of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn track_style(mut self, track_style: Style) -> Self {
self.track_style = track_style;
self
}
/// Sets the symbol that represents the beginning of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn begin_symbol(mut self, begin_symbol: Option<&'a str>) -> Self {
self.begin_symbol = begin_symbol;
self
}
/// Sets the style that is used for the beginning of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn begin_style(mut self, begin_style: Style) -> Self {
self.begin_style = begin_style;
self
}
/// Sets the symbol that represents the end of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn end_symbol(mut self, end_symbol: Option<&'a str>) -> Self {
self.end_symbol = end_symbol;
self
}
/// Sets the style that is used for the end of the scrollbar.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn end_style(mut self, end_style: Style) -> Self {
self.end_style = end_style;
self
@ -281,6 +294,7 @@ impl<'a> Scrollbar<'a> {
///
/// Only sets begin_symbol, end_symbol and track_symbol if they already contain a value.
/// If they were set to `None` explicitly, this function will respect that choice.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn symbols(mut self, symbol: Set) -> Self {
self.thumb_symbol = symbol.thumb;
if self.track_symbol.is_some() {
@ -304,6 +318,7 @@ impl<'a> Scrollbar<'a> {
/// │ └──────── thumb
/// └─────────── begin
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Self {
self.track_style = style;
self.thumb_style = style;

8
src/widgets/sparkline.rs
View file

@ -18,7 +18,7 @@ use crate::{
/// `Sparkline` can be styled either using [`Sparkline::style`] or preferably using the methods
/// provided by the [`Stylize`](crate::style::Stylize) trait.
///
/// # Builder methods
/// # Setter methods
///
/// - [`Sparkline::block`] wraps the sparkline in a [`Block`]
/// - [`Sparkline::data`] defines the dataset, you'll almost always want to use it
@ -81,6 +81,7 @@ impl<'a> Default for Sparkline<'a> {
impl<'a> Sparkline<'a> {
/// Wraps the sparkline with the given `block`.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Sparkline<'a> {
self.block = Some(block);
self
@ -89,6 +90,7 @@ impl<'a> Sparkline<'a> {
/// Sets the style of the entire widget.
///
/// The foreground corresponds to the bars while the background is everything else.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Sparkline<'a> {
self.style = style;
self
@ -106,6 +108,7 @@ impl<'a> Sparkline<'a> {
/// frame.render_widget(sparkline, area);
/// # }
/// ```
#[must_use = "method moves the value of self and returns the modified value"]
pub fn data(mut self, data: &'a [u64]) -> Sparkline<'a> {
self.data = data;
self
@ -115,6 +118,7 @@ impl<'a> Sparkline<'a> {
///
/// Every bar will be scaled accordingly. If no max is given, this will be the max in the
/// dataset.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn max(mut self, max: u64) -> Sparkline<'a> {
self.max = Some(max);
self
@ -124,6 +128,7 @@ impl<'a> Sparkline<'a> {
///
/// Can be [`symbols::bar::THREE_LEVELS`], [`symbols::bar::NINE_LEVELS`] (default) or a custom
/// [`Set`](symbols::bar::Set).
#[must_use = "method moves the value of self and returns the modified value"]
pub fn bar_set(mut self, bar_set: symbols::bar::Set) -> Sparkline<'a> {
self.bar_set = bar_set;
self
@ -132,6 +137,7 @@ impl<'a> Sparkline<'a> {
/// Sets the direction of the sparkline.
///
/// [`RenderDirection::LeftToRight`] by default.
#[must_use = "method moves the value of self and returns the modified value"]
pub fn direction(mut self, direction: RenderDirection) -> Sparkline<'a> {
self.direction = direction;
self

4
src/widgets/tabs.rs
View file

@ -100,6 +100,7 @@ impl<'a> Tabs<'a> {
}
/// Surrounds the `Tabs` with a [`Block`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn block(mut self, block: Block<'a>) -> Tabs<'a> {
self.block = Some(block);
self
@ -109,6 +110,7 @@ impl<'a> Tabs<'a> {
///
/// The first tab has index 0 (this is also the default index).
/// The selected tab can have a different style with [`Tabs::highlight_style`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn select(mut self, selected: usize) -> Tabs<'a> {
self.selected = selected;
self
@ -119,6 +121,7 @@ impl<'a> Tabs<'a> {
/// This will set the given style on the entire render area.
/// More precise style can be applied to the titles by styling the ones given to [`Tabs::new`].
/// The selected tab can be styled differently using [`Tabs::highlight_style`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn style(mut self, style: Style) -> Tabs<'a> {
self.style = style;
self
@ -127,6 +130,7 @@ impl<'a> Tabs<'a> {
/// Sets the style for the highlighted tab.
///
/// Highlighted tab can be selected with [`Tabs::select`].
#[must_use = "method moves the value of self and returns the modified value"]
pub fn highlight_style(mut self, style: Style) -> Tabs<'a> {
self.highlight_style = style;
self