ratatui/
text.rs

1//! Primitives for styled text.
2//!
3//! A terminal UI is at its root a lot of strings. In order to make it accessible and stylish,
4//! those strings may be associated to a set of styles. `ratatui` has three ways to represent them:
5//! - A single line string where all graphemes have the same style is represented by a [`Span`].
6//! - A single line string where each grapheme may have its own style is represented by [`Line`].
7//! - A multiple line string where each grapheme may have its own style is represented by a
8//!   [`Text`].
9//!
10//! These types form a hierarchy: [`Line`] is a collection of [`Span`] and each line of [`Text`]
11//! is a [`Line`].
12//!
13//! Keep it mind that a lot of widgets will use those types to advertise what kind of string is
14//! supported for their properties. Moreover, `ratatui` provides convenient `From` implementations
15//! so that you can start by using simple `String` or `&str` and then promote them to the previous
16//! primitives when you need additional styling capabilities.
17//!
18//! For example, for the [`crate::widgets::Block`] widget, all the following calls are valid to set
19//! its `title` property (which is a [`Line`] under the hood):
20//!
21//! ```rust
22//! use ratatui::{
23//!     style::{Color, Style},
24//!     text::{Line, Span},
25//!     widgets::Block,
26//! };
27//!
28//! // A simple string with no styling.
29//! // Converted to Line(vec![
30//! //   Span { content: Cow::Borrowed("My title"), style: Style { .. } }
31//! // ])
32//! let block = Block::new().title("My title");
33//!
34//! // A simple string with a unique style.
35//! // Converted to Line(vec![
36//! //   Span { content: Cow::Borrowed("My title"), style: Style { fg: Some(Color::Yellow), .. }
37//! // ])
38//! let block = Block::new().title(Span::styled("My title", Style::default().fg(Color::Yellow)));
39//!
40//! // A string with multiple styles.
41//! // Converted to Line(vec![
42//! //   Span { content: Cow::Borrowed("My"), style: Style { fg: Some(Color::Yellow), .. } },
43//! //   Span { content: Cow::Borrowed(" title"), .. }
44//! // ])
45//! let block = Block::new().title(vec![
46//!     Span::styled("My", Style::default().fg(Color::Yellow)),
47//!     Span::raw(" title"),
48//! ]);
49//! ```
50
51mod grapheme;
52pub use grapheme::StyledGrapheme;
53
54mod line;
55pub use line::{Line, ToLine};
56
57mod masked;
58pub use masked::Masked;
59
60mod span;
61pub use span::{Span, ToSpan};
62
63mod text;
64pub use text::{Text, ToText};
ratatui/text.rs

ratatui/
text.rs
