366c2a0e6d
`Block::bordered()` is shorter than `Block::new().borders(Borders::ALL)`, requires one less import (`Borders`) and in case `Block::default()` was used before can even be `const`.
62 lines
2.3 KiB
Rust
62 lines
2.3 KiB
Rust
//! Primitives for styled text.
|
|
//!
|
|
//! A terminal UI is at its root a lot of strings. In order to make it accessible and stylish,
|
|
//! those strings may be associated to a set of styles. `ratatui` has three ways to represent them:
|
|
//! - A single line string where all graphemes have the same style is represented by a [`Span`].
|
|
//! - A single line string where each grapheme may have its own style is represented by [`Line`].
|
|
//! - A multiple line string where each grapheme may have its own style is represented by a
|
|
//! [`Text`].
|
|
//!
|
|
//! These types form a hierarchy: [`Line`] is a collection of [`Span`] and each line of [`Text`]
|
|
//! is a [`Line`].
|
|
//!
|
|
//! Keep it mind that a lot of widgets will use those types to advertise what kind of string is
|
|
//! supported for their properties. Moreover, `ratatui` provides convenient `From` implementations
|
|
//! so that you can start by using simple `String` or `&str` and then promote them to the previous
|
|
//! primitives when you need additional styling capabilities.
|
|
//!
|
|
//! For example, for the [`crate::widgets::Block`] widget, all the following calls are valid to set
|
|
//! its `title` property (which is a [`Line`] under the hood):
|
|
//!
|
|
//! ```rust
|
|
//! use ratatui::{prelude::*, widgets::*};
|
|
//!
|
|
//! // A simple string with no styling.
|
|
//! // Converted to Line(vec![
|
|
//! // Span { content: Cow::Borrowed("My title"), style: Style { .. } }
|
|
//! // ])
|
|
//! let block = Block::new().title("My title");
|
|
//!
|
|
//! // A simple string with a unique style.
|
|
//! // Converted to Line(vec![
|
|
//! // Span { content: Cow::Borrowed("My title"), style: Style { fg: Some(Color::Yellow), .. }
|
|
//! // ])
|
|
//! let block = Block::new().title(Span::styled("My title", Style::default().fg(Color::Yellow)));
|
|
//!
|
|
//! // A string with multiple styles.
|
|
//! // Converted to Line(vec![
|
|
//! // Span { content: Cow::Borrowed("My"), style: Style { fg: Some(Color::Yellow), .. } },
|
|
//! // Span { content: Cow::Borrowed(" title"), .. }
|
|
//! // ])
|
|
//! let block = Block::new().title(vec![
|
|
//! Span::styled("My", Style::default().fg(Color::Yellow)),
|
|
//! Span::raw(" title"),
|
|
//! ]);
|
|
//! ```
|
|
|
|
mod grapheme;
|
|
pub use grapheme::StyledGrapheme;
|
|
|
|
mod line;
|
|
pub use line::Line;
|
|
|
|
mod masked;
|
|
pub use masked::Masked;
|
|
|
|
mod span;
|
|
pub use span::Span;
|
|
|
|
#[allow(clippy::module_inception)]
|
|
mod text;
|
|
pub use text::Text;
|