Mirrors/ratatui
2
0
Fork 0
mirror of https://github.com/ratatui-org/ratatui synced 2025-02-16 14:08:44 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: import prelude::* in doc examples (#490)

Browse source 
This commit adds `prelude::*` all doc examples and widget::* to those
that need it. This is done to highlight the use of the prelude and
simplify the examples.

- Examples in Type and module level comments show all imports and use
  `prelude::*` and `widget::*` where possible.
- Function level comments hide imports unless there are imports other
  than `prelude::*` and `widget::*`.
This commit is contained in:
Josh McKinney 2023-09-11 18:01:57 -07:00 • committed by GitHub
parent 1947c58c60
commit 1414fbcc05
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
30 changed files with 160 additions and 222 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
src/backend/test.rs
View file

@ -25,7 +25,7 @@ use crate::{
/// # Example
///
/// ```rust
/// use ratatui::{prelude::*, backend::TestBackend};
/// use ratatui::{backend::TestBackend, prelude::*};
///
/// let mut backend = TestBackend::new(10, 2);
/// backend.clear()?;

16
src/buffer.rs
View file

@ -129,9 +129,7 @@ impl Default for Cell {
/// # Examples:
///
/// ```
/// use ratatui::buffer::{Buffer, Cell};
/// use ratatui::layout::Rect;
/// use ratatui::style::{Color, Style, Modifier};
/// use ratatui::{prelude::*, buffer::Cell};
///
/// let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5});
/// buf.get_mut(0, 2).set_symbol("x");
@ -228,8 +226,7 @@ impl Buffer {
/// # Examples
///
/// ```
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// # use ratatui::prelude::*;
/// let rect = Rect::new(200, 100, 10, 10);
/// let buffer = Buffer::empty(rect);
/// // Global coordinates to the top corner of this buffer's area
@ -241,8 +238,7 @@ impl Buffer {
/// Panics when given an coordinate that is outside of this Buffer's area.
///
/// ```should_panic
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// # use ratatui::prelude::*;
/// let rect = Rect::new(200, 100, 10, 10);
/// let buffer = Buffer::empty(rect);
/// // Top coordinate is outside of the buffer in global coordinate space, as the Buffer's area
@ -268,8 +264,7 @@ impl Buffer {
/// # Examples
///
/// ```
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// # use ratatui::prelude::*;
/// let rect = Rect::new(200, 100, 10, 10);
/// let buffer = Buffer::empty(rect);
/// assert_eq!(buffer.pos_of(0), (200, 100));
@ -281,8 +276,7 @@ impl Buffer {
/// Panics when given an index that is outside the Buffer's content.
///
/// ```should_panic
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// # use ratatui::prelude::*;
/// let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
/// let buffer = Buffer::empty(rect);
/// // Index 100 is the 101th cell, which lies outside of the area of this Buffer.

14
src/layout.rs
View file

@ -38,7 +38,7 @@ pub enum Constraint {
/// Converts the given percentage to a f32, and then converts it back, trimming off the decimal
/// point (effectively rounding down)
/// ```
/// # use ratatui::prelude::Constraint;
/// # use ratatui::prelude::*;
/// assert_eq!(0, Constraint::Percentage(50).apply(0));
/// assert_eq!(2, Constraint::Percentage(50).apply(4));
/// assert_eq!(5, Constraint::Percentage(50).apply(10));
@ -50,7 +50,7 @@ pub enum Constraint {
/// Converts the given numbers to a f32, and then converts it back, trimming off the decimal
/// point (effectively rounding down)
/// ```
/// # use ratatui::prelude::Constraint;
/// # use ratatui::prelude::*;
/// assert_eq!(0, Constraint::Ratio(4, 3).apply(0));
/// assert_eq!(4, Constraint::Ratio(4, 3).apply(4));
/// assert_eq!(10, Constraint::Ratio(4, 3).apply(10));
@ -65,7 +65,7 @@ pub enum Constraint {
/// Apply no more than the given amount (currently roughly equal to [Constraint::Max], but less
/// consistent)
/// ```
/// # use ratatui::prelude::Constraint;
/// # use ratatui::prelude::*;
/// assert_eq!(0, Constraint::Length(4).apply(0));
/// assert_eq!(4, Constraint::Length(4).apply(4));
/// assert_eq!(4, Constraint::Length(4).apply(10));
@ -75,7 +75,7 @@ pub enum Constraint {
///
/// also see [std::cmp::min]
/// ```
/// # use ratatui::prelude::Constraint;
/// # use ratatui::prelude::*;
/// assert_eq!(0, Constraint::Max(4).apply(0));
/// assert_eq!(4, Constraint::Max(4).apply(4));
/// assert_eq!(4, Constraint::Max(4).apply(10));
@ -85,7 +85,7 @@ pub enum Constraint {
///
/// also see [std::cmp::max]
/// ```
/// # use ratatui::prelude::Constraint;
/// # use ratatui::prelude::*;
/// assert_eq!(4, Constraint::Min(4).apply(0));
/// assert_eq!(4, Constraint::Min(4).apply(4));
/// assert_eq!(10, Constraint::Min(4).apply(10));
@ -302,8 +302,8 @@ pub(crate) enum SegmentSize {
/// # Example
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::Paragraph;
/// use ratatui::{prelude::*, widgets::*};
///
/// fn render<B: Backend>(frame: &mut Frame<B>, area: Rect) {
/// let layout = Layout::default()
/// .direction(Direction::Vertical)

18
src/lib.rs
View file

@ -36,7 +36,7 @@
//!
//! ```rust,no_run
//! use std::io;
//! use ratatui::{backend::CrosstermBackend, Terminal};
//! use ratatui::prelude::*;
//!
//! fn main() -> Result<(), io::Error> {
//! let stdout = io::stdout();
@ -51,7 +51,7 @@
//!
//! ```rust,ignore
//! use std::io;
//! use ratatui::{backend::TermionBackend, Terminal};
//! use ratatui::prelude::*;
//! use termion::raw::IntoRawMode;
//!
//! fn main() -> Result<(), io::Error> {
@ -79,11 +79,7 @@
//!
//! ```rust,no_run
//! use std::{io, thread, time::Duration};
//! use ratatui::{
//! backend::CrosstermBackend,
//! widgets::{Block, Borders},
//! Terminal
//! };
//! use ratatui::{prelude::*, widgets::*};
//! use crossterm::{
//! event::{self, DisableMouseCapture, EnableMouseCapture},
//! execute,
@ -134,12 +130,8 @@
//! full customization. And `Layout` is no exception:
//!
//! ```rust,no_run
//! use ratatui::{
//! backend::Backend,
//! layout::{Constraint, Direction, Layout},
//! widgets::{Block, Borders},
//! Frame,
//! };
//! use ratatui::{prelude::*, widgets::*};
//!
//! fn ui<B: Backend>(f: &mut Frame<B>) {
//! let chunks = Layout::default()
//! .direction(Direction::Vertical)

1
src/prelude.rs
View file

@ -9,7 +9,6 @@
//!
//! ```rust
//! use ratatui::{prelude::*, widgets::*};
//! use ratatui::widgets::{Block, Borders};
//!
//! #[derive(Debug, Default, PartialEq, Eq)]
//! struct Line;

28
src/style.rs
View file

@ -11,6 +11,7 @@
//! readable for most use cases.
//!
//! ## Example
//!
//! ```
//! use ratatui::prelude::*;
//!
@ -76,7 +77,7 @@ bitflags! {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::Modifier;
/// use ratatui::{prelude::*};
///
/// let m = Modifier::BOLD | Modifier::ITALIC;
/// ```
@ -112,7 +113,8 @@ impl fmt::Debug for Modifier {
/// Style lets you control the main characteristics of the displayed elements.
///
/// ```rust
/// # use ratatui::style::{Color, Modifier, Style};
/// use ratatui::{prelude::*};
///
/// Style::default()
/// .fg(Color::Black)
/// .bg(Color::Green)
@ -133,9 +135,8 @@ impl fmt::Debug for Modifier {
/// just S3.
///
/// ```rust
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// use ratatui::{prelude::*};
///
/// let styles = [
/// Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC),
/// Style::default().bg(Color::Red).add_modifier(Modifier::UNDERLINED),
@ -164,9 +165,8 @@ impl fmt::Debug for Modifier {
/// reset all properties until that point use [`Style::reset`].
///
/// ```
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::buffer::Buffer;
/// # use ratatui::layout::Rect;
/// use ratatui::{prelude::*};
///
/// let styles = [
/// Style::default().fg(Color::Blue).add_modifier(Modifier::BOLD | Modifier::ITALIC),
/// Style::reset().fg(Color::Yellow),
@ -244,7 +244,7 @@ impl Style {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::{Color, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Blue);
/// let diff = Style::default().fg(Color::Red);
/// assert_eq!(style.patch(diff), Style::default().fg(Color::Red));
@ -259,7 +259,7 @@ impl Style {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::{Color, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().bg(Color::Blue);
/// let diff = Style::default().bg(Color::Red);
/// assert_eq!(style.patch(diff), Style::default().bg(Color::Red));
@ -279,7 +279,7 @@ impl Style {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().underline_color(Color::Blue).add_modifier(Modifier::UNDERLINED);
/// let diff = Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED);
/// assert_eq!(style.patch(diff), Style::default().underline_color(Color::Red).add_modifier(Modifier::UNDERLINED));
@ -297,7 +297,7 @@ impl Style {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().add_modifier(Modifier::BOLD);
/// let diff = Style::default().add_modifier(Modifier::ITALIC);
/// let patched = style.patch(diff);
@ -317,7 +317,7 @@ impl Style {
/// ## Examples
///
/// ```rust
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().add_modifier(Modifier::BOLD | Modifier::ITALIC);
/// let diff = Style::default().remove_modifier(Modifier::ITALIC);
/// let patched = style.patch(diff);
@ -335,7 +335,7 @@ impl Style {
///
/// ## Examples
/// ```
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style_1 = Style::default().fg(Color::Yellow);
/// let style_2 = Style::default().bg(Color::Red);
/// let combined = style_1.patch(style_2);

8
src/style/color.rs
View file

@ -38,8 +38,9 @@ use std::{
/// # Example
///
/// ```
/// use ratatui::style::Color;
/// use std::str::FromStr;
/// use ratatui::prelude::*;
///
/// assert_eq!(Color::from_str("red"), Ok(Color::Red));
/// assert_eq!("red".parse(), Ok(Color::Red));
/// assert_eq!("lightred".parse(), Ok(Color::LightRed));
@ -145,8 +146,9 @@ impl std::error::Error for ParseColorError {}
/// # Examples
///
/// ```
/// # use std::str::FromStr;
/// # use ratatui::style::Color;
/// use std::str::FromStr;
/// use ratatui::prelude::*;
///
/// let color: Color = Color::from_str("blue").unwrap();
/// assert_eq!(color, Color::Blue);
///

16
src/terminal.rs
View file

@ -85,10 +85,7 @@ where
/// # Examples
///
/// ```rust
/// # use ratatui::Terminal;
/// # use ratatui::backend::TestBackend;
/// # use ratatui::layout::Rect;
/// # use ratatui::widgets::Block;
/// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
/// # let backend = TestBackend::new(5, 5);
/// # let mut terminal = Terminal::new(backend).unwrap();
/// let block = Block::default();
@ -111,10 +108,7 @@ where
/// # Examples
///
/// ```rust
/// # use ratatui::Terminal;
/// # use ratatui::backend::TestBackend;
/// # use ratatui::layout::Rect;
/// # use ratatui::widgets::{List, ListItem, ListState};
/// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
/// # let backend = TestBackend::new(5, 5);
/// # let mut terminal = Terminal::new(backend).unwrap();
/// let mut state = ListState::default();
@ -403,11 +397,7 @@ where
/// ## Insert a single line before the current viewport
///
/// ```rust
/// # use ratatui::widgets::{Paragraph, Widget};
/// # use ratatui::text::{Line, Span};
/// # use ratatui::style::{Color, Style};
/// # use ratatui::{Terminal};
/// # use ratatui::backend::TestBackend;
/// # use ratatui::{backend::TestBackend, prelude::*, widgets::*};
/// # let backend = TestBackend::new(10, 10);
/// # let mut terminal = Terminal::new(backend).unwrap();
/// terminal.insert_before(1, |buf| {

23
src/text/line.rs
View file

@ -16,8 +16,7 @@ impl<'a> Line<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::text::Line;
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// Line::styled("My text", style);
/// Line::styled(String::from("My text"), style);
@ -34,8 +33,7 @@ impl<'a> Line<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Line};
/// # use ratatui::style::{Color, Style};
/// # use ratatui::prelude::*;
/// let line = Line::from(vec![
/// Span::styled("My", Style::default().fg(Color::Yellow)),
/// Span::raw(" text"),
@ -54,9 +52,9 @@ impl<'a> Line<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Line, StyledGrapheme};
/// # use ratatui::style::{Color, Modifier, Style};
/// # use std::iter::Iterator;
/// use std::iter::Iterator;
/// use ratatui::{prelude::*, text::StyledGrapheme};
///
/// let line = Line::styled("Text", Style::default().fg(Color::Yellow));
/// let style = Style::default().fg(Color::Green).bg(Color::Black);
/// assert_eq!(
@ -83,8 +81,7 @@ impl<'a> Line<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Line};
/// # use ratatui::style::{Color, Style, Modifier};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// let mut raw_line = Line::from(vec![
/// Span::raw("My"),
@ -112,8 +109,7 @@ impl<'a> Line<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Line};
/// # use ratatui::style::{Color, Style, Modifier};
/// # use ratatui::prelude::*;
/// let mut line = Line::from(vec![
/// Span::styled("My", Style::default().fg(Color::Yellow)),
/// Span::styled(" text", Style::default().add_modifier(Modifier::BOLD)),
@ -135,10 +131,7 @@ impl<'a> Line<'a> {
/// ## Examples
///
/// ```rust
/// # use std::borrow::Cow;
/// # use ratatui::layout::Alignment;
/// # use ratatui::text::{Span, Line};
/// # use ratatui::style::{Color, Style, Modifier};
/// # use ratatui::prelude::*;
/// let mut line = Line::from("Hi, what's up?");
/// assert_eq!(None, line.alignment);
/// assert_eq!(Some(Alignment::Right), line.alignment(Alignment::Right).alignment)

2
src/text/masked.rs
View file

@ -13,7 +13,7 @@ use super::Text;
/// # Examples
///
/// ```rust
/// use ratatui::{buffer::Buffer, layout::Rect, text::Masked, widgets::{Paragraph, Widget}};
/// use ratatui::{prelude::*, widgets::*};
///
/// let mut buffer = Buffer::empty(Rect::new(0, 0, 5, 1));
/// let password = Masked::new("12345", 'x');

5
src/text/mod.rs
View file

@ -19,9 +19,8 @@
//! its `title` property (which is a [`Line`] under the hood):
//!
//! ```rust
//! # use ratatui::widgets::Block;
//! # use ratatui::text::{Span, Line};
//! # use ratatui::style::{Color, Style};
//! use ratatui::{prelude::*, widgets::*};
//!
//! // A simple string with no styling.
//! // Converted to Line(vec![
//! // Span { content: Cow::Borrowed("My title"), style: Style { .. } }

16
src/text/span.rs
View file

@ -17,7 +17,8 @@ use crate::style::{Style, Styled};
/// any type convertible to [`Cow<str>`].
///
/// ```rust
/// # use ratatui::prelude::*;
/// use ratatui::prelude::*;
///
/// let span = Span::raw("test content");
/// let span = Span::raw(String::from("test content"));
/// let span = Span::from("test content");
@ -30,7 +31,8 @@ use crate::style::{Style, Styled};
/// the [`Stylize`] trait.
///
/// ```rust
/// # use ratatui::prelude::*;
/// use ratatui::prelude::*;
///
/// let span = Span::styled("test content", Style::new().green());
/// let span = Span::styled(String::from("test content"), Style::new().green());
/// let span = "test content".green();
@ -41,7 +43,8 @@ use crate::style::{Style, Styled};
/// applied are additive.
///
/// ```rust
/// # use ratatui::prelude::*;
/// use ratatui::prelude::*;
///
/// let span = Span::raw("test content").green().on_yellow().italic();
/// let span = Span::raw(String::from("test content")).green().on_yellow().italic();
/// ```
@ -63,7 +66,7 @@ impl<'a> Span<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::text::Span;
/// # use ratatui::prelude::*;
/// Span::raw("test content");
/// Span::raw(String::from("test content"));
/// ```
@ -110,8 +113,9 @@ impl<'a> Span<'a> {
/// # Example
///
/// ```rust
/// # use ratatui::{prelude::*, text::StyledGrapheme};
/// # use std::iter::Iterator;
/// use std::iter::Iterator;
/// use ratatui::{prelude::*, text::StyledGrapheme};
///
/// let span = Span::styled("Test", Style::new().green().italic());
/// let style = Style::new().red().on_yellow();
/// assert_eq!(

18
src/text/spans.rs
View file

@ -19,8 +19,8 @@ impl<'a> Spans<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Spans};
/// # use ratatui::style::{Color, Style};
/// use ratatui::{prelude::*, text::Spans};
///
/// let spans = Spans::from(vec![
/// Span::styled("My", Style::default().fg(Color::Yellow)),
/// Span::raw(" text"),
@ -36,8 +36,8 @@ impl<'a> Spans<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Spans};
/// # use ratatui::style::{Color, Style, Modifier};
/// use ratatui::{prelude::*, text::Spans};
///
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// let mut raw_spans = Spans::from(vec![
/// Span::raw("My"),
@ -65,8 +65,8 @@ impl<'a> Spans<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Spans};
/// # use ratatui::style::{Color, Style, Modifier};
/// use ratatui::{prelude::*, text::Spans};
///
/// let mut spans = Spans::from(vec![
/// Span::styled("My", Style::default().fg(Color::Yellow)),
/// Span::styled(" text", Style::default().add_modifier(Modifier::BOLD)),
@ -88,10 +88,8 @@ impl<'a> Spans<'a> {
/// ## Examples
///
/// ```rust
/// # use std::borrow::Cow;
/// # use ratatui::layout::Alignment;
/// # use ratatui::text::{Span, Spans};
/// # use ratatui::style::{Color, Style, Modifier};
/// use ratatui::{prelude::*, text::Spans};
///
/// let mut line = Spans::from("Hi, what's up?").alignment(Alignment::Right);
/// assert_eq!(Some(Alignment::Right), line.alignment)
/// ```

19
src/text/text.rs
View file

@ -12,8 +12,8 @@ use crate::style::Style;
/// [`core::iter::Extend`] which enables the concatenation of several [`Text`] blocks.
///
/// ```rust
/// # use ratatui::text::Text;
/// # use ratatui::style::{Color, Modifier, Style};
/// use ratatui::prelude::*;
///
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
///
/// // An initial two lines of `Text` built from a `&str`
@ -39,7 +39,7 @@ impl<'a> Text<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::Text;
/// # use ratatui::prelude::*;
/// Text::raw("The first line\nThe second line");
/// Text::raw(String::from("The first line\nThe second line"));
/// ```
@ -62,8 +62,7 @@ impl<'a> Text<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::text::Text;
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// Text::styled("The first line\nThe second line", style);
/// Text::styled(String::from("The first line\nThe second line"), style);
@ -82,7 +81,7 @@ impl<'a> Text<'a> {
/// ## Examples
///
/// ```rust
/// use ratatui::text::Text;
/// # use ratatui::prelude::*;
/// let text = Text::from("The first line\nThe second line");
/// assert_eq!(15, text.width());
/// ```
@ -95,7 +94,7 @@ impl<'a> Text<'a> {
/// ## Examples
///
/// ```rust
/// use ratatui::text::Text;
/// # use ratatui::prelude::*;
/// let text = Text::from("The first line\nThe second line");
/// assert_eq!(2, text.height());
/// ```
@ -108,8 +107,7 @@ impl<'a> Text<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::text::Text;
/// # use ratatui::style::{Color, Modifier, Style};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// let mut raw_text = Text::raw("The first line\nThe second line");
/// let styled_text = Text::styled(String::from("The first line\nThe second line"), style);
@ -130,8 +128,7 @@ impl<'a> Text<'a> {
/// ## Examples
///
/// ```rust
/// # use ratatui::text::{Span, Line, Text};
/// # use ratatui::style::{Color, Style, Modifier};
/// # use ratatui::prelude::*;
/// let style = Style::default().fg(Color::Yellow).add_modifier(Modifier::ITALIC);
/// let mut text = Text::styled("The first line\nThe second line", style);
///

19
src/title.rs
View file

@ -13,22 +13,22 @@ use crate::{layout::Alignment, text::Line};
///
/// Title with no style.
/// ```
/// # use ratatui::widgets::block::Title;
/// use ratatui::widgets::block::Title;
///
/// Title::from("Title");
/// ```
///
/// Blue title on a white background (via [`Stylize`](crate::style::Stylize) trait).
/// ```
/// # use ratatui::widgets::block::Title;
/// # use ratatui::style::Stylize;
/// use ratatui::{prelude::*, widgets::block::*};
///
/// Title::from("Title".blue().on_white());
/// ```
///
/// Title with multiple styles (see [`Line`] and [`Stylize`](crate::style::Stylize)).
/// ```
/// # use ratatui::widgets::block::Title;
/// # use ratatui::style::Stylize;
/// # use ratatui::text::Line;
/// use ratatui::{prelude::*, widgets::block::*};
///
/// Title::from(
/// Line::from(vec!["Q".white().underlined(), "uit".gray()])
/// );
@ -36,8 +36,8 @@ use crate::{layout::Alignment, text::Line};
///
/// Complete example
/// ```
/// # use ratatui::widgets::block::{Title, Position};
/// # use ratatui::layout::Alignment;
/// use ratatui::{prelude::*, widgets::{*, block::*}};
///
/// Title::from("Title")
/// .position(Position::Top)
/// .alignment(Alignment::Right);
@ -69,7 +69,8 @@ pub struct Title<'a> {
/// # Example
///
/// ```
/// # use ratatui::widgets::{Block, block::{Title, Position}};
/// use ratatui::widgets::{*, block::*};
///
/// Block::new().title(
/// Title::from("title").position(Position::Bottom)
/// );

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

@ -15,7 +15,8 @@ use crate::{buffer::Buffer, prelude::Rect, style::Style, text::Line};
/// 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::*};
/// use ratatui::{prelude::*, widgets::*};
///
/// Bar::default()
/// .label("Bar 1".into())
/// .value(10)

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

@ -10,7 +10,8 @@ use crate::{
/// # Examples
///
/// ```
/// # use ratatui::{prelude::*, widgets::*};
/// use ratatui::{prelude::*, widgets::*};
///
/// BarGroup::default()
/// .label("Group 1".into())
/// .bars(&[Bar::default().value(200), Bar::default().value(150)]);

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

@ -113,8 +113,7 @@ impl<'a> BarChart<'a> {
/// 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)]));
@ -142,7 +141,7 @@ impl<'a> BarChart<'a> {
/// 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;
/// # use ratatui::{prelude::*, widgets::*};
/// BarChart::default().data(&[("foo", 1), ("bar", 2), ("baz", 100)]);
/// // Renders
/// // █
@ -153,7 +152,7 @@ impl<'a> BarChart<'a> {
/// This example shows a custom max value.
/// The maximum height being `2`, `bar` & `baz` render as the max.
/// ```
/// # use ratatui::widgets::BarChart;
/// # use ratatui::{prelude::*, widgets::*};
/// BarChart::default()
/// .data(&[("foo", 1), ("bar", 2), ("baz", 100)])
/// .max(2);
@ -197,7 +196,7 @@ impl<'a> BarChart<'a> {
///
/// This shows two bars with a gap of `3`. Notice the labels will always stay under the bar.
/// ```
/// # use ratatui::widgets::BarChart;
/// # use ratatui::{prelude::*, widgets::*};
/// BarChart::default()
/// .data(&[("foo", 1), ("bar", 2)])
/// .bar_gap(3);

40
src/widgets/block.rs
View file

@ -96,7 +96,8 @@ impl BorderType {
/// # Example
///
/// ```
/// use ratatui::widgets::block::Padding;
/// use ratatui::{prelude::*, widgets::*};
///
/// Padding::uniform(1);
/// Padding::horizontal(2);
/// ```
@ -179,10 +180,7 @@ impl Padding {
/// # Examples
///
/// ```
/// use ratatui::{
/// style::{Color, Style},
/// widgets::{Block, BorderType, Borders},
/// };
/// use ratatui::{prelude::*, widgets::*};
///
/// Block::default()
/// .title("Block")
@ -194,13 +192,7 @@ impl Padding {
///
/// You may also use multiple titles like in the following:
/// ```
/// use ratatui::{
/// style::{Color, Style},
/// widgets::{
/// block::title::{Position, Title},
/// Block, BorderType, Borders,
/// },
/// };
/// use ratatui::{prelude::*, widgets::{*, block::*}};
///
/// Block::default()
/// .title("Title 1")
@ -282,8 +274,8 @@ impl<'a> Block<'a> {
/// the leftover space)
/// - Two titles with the same alignment (notice the left titles are separated)
/// ```
/// # use ratatui::widgets::{Block, block::title::Title};
/// # use ratatui::layout::Alignment;
/// use ratatui::{prelude::*, widgets::{*, block::*}};
///
/// Block::default()
/// .title("Title") // By default in the top left corner
/// .title(Title::from("Left").alignment(Alignment::Left)) // also on the left
@ -324,8 +316,8 @@ impl<'a> Block<'a> {
/// This example aligns all titles in the center except the "right" title which explicitly sets
/// [`Alignment::Right`].
/// ```
/// # use ratatui::widgets::{Block, block::title::Title};
/// # use ratatui::layout::Alignment;
/// use ratatui::{prelude::*, widgets::{*, block::*}};
///
/// Block::default()
/// // This title won't be aligned in the center
/// .title(Title::from("right").alignment(Alignment::Right))
@ -353,7 +345,8 @@ impl<'a> Block<'a> {
/// This example positions all titles on the bottom except the "top" title which explicitly sets
/// [`Position::Top`].
/// ```
/// # use ratatui::widgets::{Block, BorderType, Borders, block::title::{Position, Title}};
/// use ratatui::{prelude::*, widgets::{*, block::*}};
///
/// Block::default()
/// // This title won't be aligned in the center
/// .title(Title::from("top").position(Position::Top))
@ -374,8 +367,7 @@ impl<'a> Block<'a> {
///
/// This example shows a `Block` with blue borders.
/// ```
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::{Block, Borders};
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default()
/// .borders(Borders::ALL)
/// .border_style(Style::new().blue());
@ -405,13 +397,13 @@ impl<'a> Block<'a> {
///
/// Simply show all borders.
/// ```
/// # use ratatui::widgets::{Borders, Block};
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default().borders(Borders::ALL);
/// ```
///
/// Display left and right borders.
/// ```
/// # use ratatui::widgets::{Borders, Block};
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default().borders(Borders::LEFT | Borders::RIGHT);
/// ```
pub const fn borders(mut self, flag: Borders) -> Block<'a> {
@ -434,7 +426,7 @@ impl<'a> Block<'a> {
///
/// Draw a block nested within another block
/// ```
/// # use ratatui::{prelude::*, widgets::{Block, Borders}};
/// # use ratatui::{prelude::*, widgets::*};
/// # fn render_nested_block<B: Backend>(frame: &mut Frame<B>) {
/// let outer_block = Block::default().title("Outer").borders(Borders::ALL);
/// let inner_block = Block::default().title("Inner").borders(Borders::ALL);
@ -490,7 +482,7 @@ impl<'a> Block<'a> {
///
/// This renders a `Block` with no padding (the default).
/// ```
/// # use ratatui::widgets::{Block, Borders, Padding};
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default()
/// .borders(Borders::ALL)
/// .padding(Padding::zero());
@ -503,7 +495,7 @@ impl<'a> Block<'a> {
/// This example shows a `Block` with padding left and right ([`Padding::horizontal`]).
/// Notice the two spaces before and after the content.
/// ```
/// # use ratatui::widgets::{Block, Borders, Padding};
/// # use ratatui::{prelude::*, widgets::*};
/// Block::default()
/// .borders(Borders::ALL)
/// .padding(Padding::horizontal(2));

16
src/widgets/canvas/mod.rs
View file

@ -187,7 +187,7 @@ impl<'a, 'b> Painter<'a, 'b> {
///
/// # Examples:
/// ```
/// use ratatui::{symbols, widgets::canvas::{Painter, Context}};
/// use ratatui::{prelude::*, widgets::canvas::*};
///
/// let mut ctx = Context::new(2, 2, [1.0, 2.0], [0.0, 2.0], symbols::Marker::Braille);
/// let mut painter = Painter::from(&mut ctx);
@ -224,7 +224,7 @@ impl<'a, 'b> Painter<'a, 'b> {
///
/// # Examples:
/// ```
/// use ratatui::{style::Color, symbols, widgets::canvas::{Painter, Context}};
/// use ratatui::{prelude::*, widgets::canvas::*};
///
/// let mut ctx = Context::new(1, 1, [0.0, 2.0], [0.0, 2.0], symbols::Marker::Braille);
/// let mut painter = Painter::from(&mut ctx);
@ -333,10 +333,8 @@ impl<'a> Context<'a> {
/// # Examples
///
/// ```
/// # use ratatui::widgets::{Block, Borders};
/// # use ratatui::layout::Rect;
/// # use ratatui::widgets::canvas::{Canvas, Shape, Line, Rectangle, Map, MapResolution};
/// # use ratatui::style::Color;
/// use ratatui::{style::Color, widgets::{*, canvas::*}};
///
/// Canvas::default()
/// .block(Block::default().title("Canvas").borders(Borders::ALL))
/// .x_bounds([-180.0, 180.0])
@ -438,12 +436,10 @@ where
/// # Examples
///
/// ```
/// # use ratatui::widgets::canvas::Canvas;
/// # use ratatui::symbols;
/// use ratatui::{prelude::*, widgets::canvas::*};
///
/// Canvas::default().marker(symbols::Marker::Braille).paint(|ctx| {});
///
/// Canvas::default().marker(symbols::Marker::Dot).paint(|ctx| {});
///
/// Canvas::default().marker(symbols::Marker::Block).paint(|ctx| {});
/// ```
pub fn marker(mut self, marker: symbols::Marker) -> Canvas<'a, F> {

9
src/widgets/chart.rs
View file

@ -158,10 +158,8 @@ struct ChartLayout {
/// # Examples
///
/// ```
/// # use ratatui::symbols;
/// # use ratatui::widgets::{Block, Borders, Chart, Axis, Dataset, GraphType};
/// # use ratatui::style::{Style, Color};
/// # use ratatui::text::Span;
/// use ratatui::{prelude::*, widgets::*};
///
/// let datasets = vec![
/// Dataset::default()
/// .name("data1")
@ -242,8 +240,7 @@ impl<'a> Chart<'a> {
/// # Examples
///
/// ```
/// # use ratatui::widgets::Chart;
/// # use ratatui::layout::Constraint;
/// # use ratatui::{prelude::*, widgets::*};
/// let constraints = (
/// Constraint::Ratio(1, 3),
/// Constraint::Ratio(1, 4)

6
src/widgets/clear.rs
View file

@ -8,10 +8,8 @@ use crate::{buffer::Buffer, layout::Rect, widgets::Widget};
/// # Examples
///
/// ```
/// # use ratatui::widgets::{Clear, Block, Borders};
/// # use ratatui::layout::Rect;
/// # use ratatui::Frame;
/// # use ratatui::backend::Backend;
/// use ratatui::{prelude::*, widgets::*};
///
/// fn draw_on_clear<B: Backend>(f: &mut Frame<B>, area: Rect) {
/// let block = Block::default().title("Block").borders(Borders::ALL);
/// f.render_widget(Clear, area); // <- this will clear/reset the area first

9
src/widgets/gauge.rs
View file

@ -12,8 +12,8 @@ use crate::{
/// # Examples:
///
/// ```
/// # use ratatui::widgets::{Widget, Gauge, Block, Borders};
/// # use ratatui::style::{Style, Color, Modifier};
/// 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))
@ -170,9 +170,8 @@ fn get_unicode_block<'a>(frac: f64) -> &'a str {
/// # Examples:
///
/// ```
/// # use ratatui::widgets::{Widget, LineGauge, Block, Borders};
/// # use ratatui::style::{Style, Color, Modifier};
/// # use ratatui::symbols;
/// use ratatui::{prelude::*, widgets::*};
///
/// LineGauge::default()
/// .block(Block::default().borders(Borders::ALL).title("Progress"))
/// .gauge_style(Style::default().fg(Color::White).bg(Color::Black).add_modifier(Modifier::BOLD))

4
src/widgets/list.rs
View file

@ -81,8 +81,8 @@ impl<'a> ListItem<'a> {
/// # Examples
///
/// ```
/// # use ratatui::widgets::{Block, Borders, List, ListItem};
/// # use ratatui::style::{Style, Color, Modifier};
/// use ratatui::{prelude::*, widgets::*};
///
/// let items = [ListItem::new("Item 1"), ListItem::new("Item 2"), ListItem::new("Item 3")];
/// List::new(items)
/// .block(Block::default().title("List").borders(Borders::ALL))

10
src/widgets/mod.rs
View file

@ -126,10 +126,8 @@ pub trait Widget {
/// ## Examples
///
/// ```rust,no_run
/// # use std::io;
/// # use ratatui::Terminal;
/// # use ratatui::backend::{Backend, TestBackend};
/// # use ratatui::widgets::{Widget, List, ListItem, ListState};
/// use std::io;
/// use ratatui::{backend::TestBackend, prelude::*, widgets::*};
///
/// // Let's say we have some events to display.
/// struct Events {
@ -231,9 +229,7 @@ pub trait StatefulWidget {
/// ## Examples
///
///```
/// # use ratatui::widgets::{Block, Borders};
/// # use ratatui::style::{Style, Color};
/// # use ratatui::border;
/// use ratatui::{border, prelude::*, widgets::*};
///
/// Block::default()
/// //Construct a `Borders` object and use it in place

24
src/widgets/paragraph.rs
View file

@ -24,8 +24,8 @@ fn get_line_offset(line_width: u16, text_area_width: u16, alignment: Alignment)
/// # Example
///
/// ```
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::*;
/// use ratatui::{prelude::*, widgets::*};
///
/// let text = vec![
/// Line::from(vec![
/// Span::raw("First"),
@ -64,8 +64,8 @@ pub struct Paragraph<'a> {
/// ## Examples
///
/// ```
/// # use ratatui::widgets::{Paragraph, Wrap};
/// # use ratatui::text::Text;
/// use ratatui::{prelude::*, widgets::*};
///
/// let bullet_points = Text::from(r#"Some indented points:
/// - First thing goes here and is long so that it wraps
/// - Here is another point that is long enough to wrap"#);
@ -104,8 +104,7 @@ impl<'a> Paragraph<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::Paragraph;
/// # use ratatui::{prelude::*, widgets::*};
/// let paragraph = Paragraph::new("Hello, world!");
/// let paragraph = Paragraph::new(String::from("Hello, world!"));
/// let paragraph = Paragraph::new(Text::raw("Hello, world!"));
@ -133,8 +132,7 @@ impl<'a> Paragraph<'a> {
/// # Example
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::{Block, Borders, Paragraph};
/// # use ratatui::{prelude::*, widgets::*};
/// let paragraph = Paragraph::new("Hello, world!")
/// .block(Block::default()
/// .title("Paragraph")
@ -153,8 +151,7 @@ impl<'a> Paragraph<'a> {
/// # Example
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::Paragraph;
/// # use ratatui::{prelude::*, widgets::*};
/// let paragraph = Paragraph::new("Hello, world!")
/// .style(Style::new().red().on_white());
/// ```
@ -170,8 +167,7 @@ impl<'a> Paragraph<'a> {
/// # Example
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::{Paragraph, Wrap};
/// # use ratatui::{prelude::*, widgets::*};
/// let paragraph = Paragraph::new("Hello, world!")
/// .wrap(Wrap { trim: true });
/// ```
@ -204,9 +200,7 @@ impl<'a> Paragraph<'a> {
/// # Example
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::{Paragraph, Wrap};
/// # use ratatui::layout::Alignment;
/// # use ratatui::{prelude::*, widgets::*};
/// let paragraph = Paragraph::new("Hello World")
/// .alignment(Alignment::Center);
/// ```

4
src/widgets/scrollbar.rs
View file

@ -141,8 +141,8 @@ pub enum ScrollbarOrientation {
/// # Examples
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::*;
/// use ratatui::{prelude::*, widgets::*};
///
/// # fn render_paragraph_with_scrollbar<B: Backend>(frame: &mut Frame<B>, area: Rect) {
///
/// let vertical_scroll = 0; // from app state

4
src/widgets/sparkline.rs
View file

@ -15,8 +15,8 @@ use crate::{
/// # Examples
///
/// ```
/// # use ratatui::widgets::{Block, Borders, Sparkline};
/// # use ratatui::style::{Style, Color};
/// use ratatui::{prelude::*, widgets::*};
///
/// Sparkline::default()
/// .block(Block::default().title("Sparkline").borders(Borders::ALL))
/// .data(&[0, 2, 3, 4, 1, 4, 10])

28
src/widgets/table.rs
View file

@ -13,10 +13,9 @@ use crate::{
///
/// It can be created from anything that can be converted to a [`Text`].
/// ```rust
/// # use ratatui::widgets::Cell;
/// # use ratatui::style::{Style, Modifier};
/// # use ratatui::text::{Span, Line, Text};
/// # use std::borrow::Cow;
/// use std::borrow::Cow;
/// use ratatui::{prelude::*, widgets::*};
///
/// Cell::from("simple string");
///
/// Cell::from(Span::from("span"));
@ -75,14 +74,15 @@ impl<'a> Styled for Cell<'a> {
///
/// A [`Row`] is a collection of cells. It can be created from simple strings:
/// ```rust
/// # use ratatui::widgets::Row;
/// use ratatui::{prelude::*, widgets::*};
///
/// Row::new(vec!["Cell1", "Cell2", "Cell3"]);
/// ```
///
/// But if you need a bit more control over individual cells, you can explicitly create [`Cell`]s:
/// ```rust
/// # use ratatui::widgets::{Row, Cell};
/// # use ratatui::style::{Style, Color};
/// use ratatui::{prelude::*, widgets::*};
///
/// Row::new(vec![
/// Cell::from("Cell1"),
/// Cell::from("Cell2").style(Style::default().fg(Color::Yellow)),
@ -91,8 +91,9 @@ impl<'a> Styled for Cell<'a> {
///
/// You can also construct a row from any type that can be converted into [`Text`]:
/// ```rust
/// # use std::borrow::Cow;
/// # use ratatui::widgets::Row;
/// use std::borrow::Cow;
/// use ratatui::{prelude::*, widgets::*};
///
/// Row::new(vec![
/// Cow::Borrowed("hello"),
/// Cow::Owned("world".to_uppercase()),
@ -198,10 +199,8 @@ impl HighlightSpacing {
///
/// It is a collection of [`Row`]s, themselves composed of [`Cell`]s:
/// ```rust
/// # use ratatui::widgets::{Block, Borders, Table, Row, Cell};
/// # use ratatui::layout::Constraint;
/// # use ratatui::style::{Style, Color, Modifier};
/// # use ratatui::text::{Text, Line, Span};
/// use ratatui::{prelude::*, widgets::*};
///
/// Table::new(vec![
/// // Row can be created from simple strings.
/// Row::new(vec!["Row11", "Row12", "Row13"]),
@ -276,8 +275,7 @@ impl<'a> Table<'a> {
/// # Examples
///
/// ```rust
/// # use ratatui::prelude::*;
/// # use ratatui::widgets::{Table, Row, Cell};
/// # use ratatui::{prelude::*, widgets::*};
/// let table = Table::new(vec![
/// Row::new(vec![
/// Cell::from("Cell1"),

8
src/widgets/tabs.rs
View file

@ -12,16 +12,14 @@ use crate::{
/// # Examples
///
/// ```
/// # use ratatui::widgets::{Block, Borders, Tabs};
/// # use ratatui::style::{Style, Color};
/// # use ratatui::text::{Line};
/// # use ratatui::symbols::{DOT};
/// use ratatui::{prelude::*, widgets::*};
///
/// let titles = ["Tab1", "Tab2", "Tab3", "Tab4"].iter().cloned().map(Line::from).collect();
/// Tabs::new(titles)
/// .block(Block::default().title("Tabs").borders(Borders::ALL))
/// .style(Style::default().fg(Color::White))
/// .highlight_style(Style::default().fg(Color::Yellow))
/// .divider(DOT);
/// .divider(symbols::DOT);
/// ```
#[derive(Debug, Default, Clone, Eq, PartialEq, Hash)]
pub struct Tabs<'a> {