fb6d4b2f51
* refactor(text): split text::* into separate files * feat(text): expose graphemes on Line - add `Line::styled()` - add `Line::styled_graphemes()` - add `StyledGrapheme::new()` --------- Co-authored-by: Eyesonjune18 <lowellashton@gmail.com>
72 lines
2.5 KiB
Rust
72 lines
2.5 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::widgets::Block;
|
|
//! # use ratatui::text::{Span, Line};
|
|
//! # use ratatui::style::{Color, Style};
|
|
//! // A simple string with no styling.
|
|
//! // Converted to Line(vec![
|
|
//! // Span { content: Cow::Borrowed("My title"), style: Style { .. } }
|
|
//! // ])
|
|
//! let block = Block::default().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::default().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::default().title(vec![
|
|
//! Span::styled("My", Style::default().fg(Color::Yellow)),
|
|
//! Span::raw(" title"),
|
|
//! ]);
|
|
//! ```
|
|
|
|
use crate::style::Style;
|
|
|
|
mod grapheme;
|
|
pub use grapheme::StyledGrapheme;
|
|
|
|
mod line;
|
|
pub use line::Line;
|
|
|
|
mod masked;
|
|
pub use masked::Masked;
|
|
|
|
mod span;
|
|
pub use span::Span;
|
|
|
|
/// We keep this for backward compatibility.
|
|
mod spans;
|
|
#[allow(deprecated)]
|
|
pub use spans::Spans;
|
|
|
|
#[allow(clippy::module_inception)]
|
|
mod text;
|
|
pub use text::Text;
|