Module tui::text

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. tui 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 Spans.
• A multiple line string where each grapheme may have its own style is represented by a Text.

These types form a hierarchy: Spans is a collection of Span and each line of Text is a Spans.

Keep it mind that a lot of widgets will use those types to advertise what kind of string is supported for their properties. Moreover, tui 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 Spans under the hood):

// A simple string with no styling.
// Converted to Spans(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 Spans(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 Spans(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"),
]);

Structs

Span	A string where all graphemes have the same style.
Spans	A string composed of clusters of graphemes, each with their own style.
StyledGrapheme	A grapheme associated to a style.
Text	A string split over multiple lines where each line is composed of several clusters, each with their own style.