Module 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. zui_widgets 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, zui_widgets 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.