Expand description
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
A string where all graphemes have the same style.
A string composed of clusters of graphemes, each with their own style.
A grapheme associated to a style.
A string split over multiple lines where each line is composed of several clusters, each with their own style.