Struct ratatui::text::Line

pub struct Line<'a> {
    pub spans: Vec<Span<'a>>,
    pub style: Style,
    pub alignment: Option<Alignment>,
}

A line of text, consisting of one or more Spans.

Lines are used wherever text is displayed in the terminal and represent a single line of text. When a Line is rendered, it is rendered as a single line of text, with each Span being rendered in order (left to right).

Constructor Methods

• Line::default creates a line with empty content and the default style.
• Line::raw creates a line with the given content and the default style.
• Line::styled creates a line with the given content and style.

Conversion Methods

• Line::from creates a Line from a String.
• Line::from creates a Line from a &str.
• Line::from creates a Line from a Vec of Spans.
• Line::from creates a Line from single Span.
• String::from converts a line into a String.
• Line::from_iter creates a line from an iterator of items that are convertible to Span.

Setter Methods

These methods are fluent setters. They return a Line with the property set.

• Line::spans sets the content of the line.
• Line::style sets the style of the line.
• Line::alignment sets the alignment of the line.
• Line::left_aligned sets the alignment of the line to Alignment::Left.
• Line::centered sets the alignment of the line to Alignment::Center.
• Line::right_aligned sets the alignment of the line to Alignment::Right.

Iteration Methods

• Line::iter returns an iterator over the spans of this line.
• Line::iter_mut returns a mutable iterator over the spans of this line.
• Line::into_iter returns an iterator over the spans of this line.

Other Methods

• Line::patch_style patches the style of the line, adding modifiers from the given style.
• Line::reset_style resets the style of the line.
• Line::width returns the unicode width of the content held by this line.
• Line::styled_graphemes returns an iterator over the graphemes held by this line.
• Line::push_span adds a span to the line.

Compatibility Notes

Before v0.26.0, Line did not have a style field and instead relied on only the styles that were set on each Span contained in the spans field. The Line::patch_style method was the only way to set the overall style for individual lines. For this reason, this field may not be supported yet by all widgets (outside of the ratatui crate itself).

Examples

Creating Lines

Lines can be created from Spans, Strings, and &strs. They can be styled with a Style.

use ratatui::prelude::*;

let style = Style::new().yellow();
let line = Line::raw("Hello, world!").style(style);
let line = Line::styled("Hello, world!", style);
let line = Line::styled("Hello, world!", (Color::Yellow, Modifier::BOLD));

let line = Line::from("Hello, world!");
let line = Line::from(String::from("Hello, world!"));
let line = Line::from(vec![
    Span::styled("Hello", Style::new().blue()),
    Span::raw(" world!"),
]);

Styling Lines

The line’s Style is used by the rendering widget to determine how to style the line. Each Span in the line will be styled with the Style of the line, and then with its own Style. If the line is longer than the available space, the style is applied to the entire line, and the line is truncated. Line also implements Styled which means you can use the methods of the Stylize trait.

let line = Line::from("Hello world!").style(Style::new().yellow().italic());
let line = Line::from("Hello world!").style(Color::Yellow);
let line = Line::from("Hello world!").style((Color::Yellow, Color::Black));
let line = Line::from("Hello world!").style((Color::Yellow, Modifier::ITALIC));
let line = Line::from("Hello world!").yellow().italic();

Aligning Lines

The line’s Alignment is used by the rendering widget to determine how to align the line within the available space. If the line is longer than the available space, the alignment is ignored and the line is truncated.

let line = Line::from("Hello world!").alignment(Alignment::Right);
let line = Line::from("Hello world!").centered();
let line = Line::from("Hello world!").left_aligned();
let line = Line::from("Hello world!").right_aligned();

Rendering Lines

Line implements the Widget trait, which means it can be rendered to a Buffer.

// in another widget's render method
let line = Line::from("Hello world!").style(Style::new().yellow().italic());
line.render(area, buf);

// in a terminal.draw closure
let line = Line::from("Hello world!").style(Style::new().yellow().italic());
frame.render_widget(line, area);

Rendering Lines with a Paragraph widget

Usually apps will use the Paragraph widget instead of rendering a Line directly as it provides more functionality.

let line = Line::from("Hello world!").yellow().italic();
Paragraph::new(line)
    .wrap(Wrap { trim: true })
    .render(area, buf);

Fields

spans: Vec<Span<'a>>

The spans that make up this line of text.

style: Style

The style of this line of text.

alignment: Option<Alignment>

The alignment of this line of text.

Implementations

impl<'a> Line<'a>

pub fn raw<T>(content: T) -> Self

where T: Into<Cow<'a, str>>,

Create a line with the default style.

content can be any type that is convertible to Cow<str> (e.g. &str, String, Cow<str>, or your own type that implements Into<Cow<str>>).

A Line can specify a Style, which will be applied before the style of each Span in the line.

Any newlines in the content are removed.

Examples

Line::raw("test content");
Line::raw(String::from("test content"));
Line::raw(Cow::from("test content"));

Examples found in repository

examples/tabs.rs (line 156)

fn render_footer(area: Rect, buf: &mut Buffer) {
    Line::raw("◄ ► to change tab | Press q to quit")
        .centered()
        .render(area, buf);
}

examples/flex.rs (line 487)

    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
        if spacer.width > 1 {
            let corners_only = symbols::border::Set {
                top_left: line::NORMAL.top_left,
                top_right: line::NORMAL.top_right,
                bottom_left: line::NORMAL.bottom_left,
                bottom_right: line::NORMAL.bottom_right,
                vertical_left: " ",
                vertical_right: " ",
                horizontal_top: " ",
                horizontal_bottom: " ",
            };
            Block::bordered()
                .border_set(corners_only)
                .border_style(Style::reset().dark_gray())
                .render(spacer, buf);
        } else {
            Paragraph::new(Text::from(vec![
                Line::from(""),
                Line::from("│"),
                Line::from("│"),
                Line::from(""),
            ]))
            .style(Style::reset().dark_gray())
            .render(spacer, buf);
        }
        let width = spacer.width;
        let label = if width > 4 {
            format!("{width} px")
        } else if width > 2 {
            format!("{width}")
        } else {
            String::new()
        };
        let text = Text::from(vec![
            Line::raw(""),
            Line::raw(""),
            Line::styled(label, Style::reset().dark_gray()),
        ]);
        Paragraph::new(text)
            .style(Style::reset().dark_gray())
            .alignment(Alignment::Center)
            .render(spacer, buf);
    }

pub fn styled<T, S>(content: T, style: S) -> Self

where T: Into<Cow<'a, str>>, S: Into<Style>,

Create a line with the given style. Cow<str>, or your own type that implements Into<Cow<str>>).

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Examples

Any newlines in the content are removed.

let style = Style::new().yellow().italic();
Line::styled("My text", style);
Line::styled(String::from("My text"), style);
Line::styled(Cow::from("test content"), style);

Examples found in repository

examples/constraint-explorer.rs (line 558)

    fn label(width: u16) -> impl Widget {
        let long_label = format!("{width} px");
        let short_label = format!("{width}");
        let label = if long_label.len() < width as usize {
            long_label
        } else if short_label.len() < width as usize {
            short_label
        } else {
            String::new()
        };
        Line::styled(label, Self::TEXT_COLOR).centered()
    }

examples/list.rs (line 343)

    fn to_list_item(&self, index: usize) -> ListItem {
        let bg_color = match index % 2 {
            0 => NORMAL_ROW_COLOR,
            _ => ALT_ROW_COLOR,
        };
        let line = match self.status {
            Status::Todo => Line::styled(format!(" ☐ {}", self.todo), TEXT_COLOR),
            Status::Completed => Line::styled(
                format!(" ✓ {}", self.todo),
                (COMPLETED_TEXT_COLOR, bg_color),
            ),
        };

        ListItem::new(line).bg(bg_color)
    }

examples/flex.rs (line 489)

    fn render_spacer(spacer: Rect, buf: &mut Buffer) {
        if spacer.width > 1 {
            let corners_only = symbols::border::Set {
                top_left: line::NORMAL.top_left,
                top_right: line::NORMAL.top_right,
                bottom_left: line::NORMAL.bottom_left,
                bottom_right: line::NORMAL.bottom_right,
                vertical_left: " ",
                vertical_right: " ",
                horizontal_top: " ",
                horizontal_bottom: " ",
            };
            Block::bordered()
                .border_set(corners_only)
                .border_style(Style::reset().dark_gray())
                .render(spacer, buf);
        } else {
            Paragraph::new(Text::from(vec![
                Line::from(""),
                Line::from("│"),
                Line::from("│"),
                Line::from(""),
            ]))
            .style(Style::reset().dark_gray())
            .render(spacer, buf);
        }
        let width = spacer.width;
        let label = if width > 4 {
            format!("{width} px")
        } else if width > 2 {
            format!("{width}")
        } else {
            String::new()
        };
        let text = Text::from(vec![
            Line::raw(""),
            Line::raw(""),
            Line::styled(label, Style::reset().dark_gray()),
        ]);
        Paragraph::new(text)
            .style(Style::reset().dark_gray())
            .alignment(Alignment::Center)
            .render(spacer, buf);
    }

pub fn spans<I>(self, spans: I) -> Self

where I: IntoIterator, I::Item: Into<Span<'a>>,

Sets the spans of this line of text.

spans accepts any iterator that yields items that are convertible to Span (e.g. &str, String, Span, or your own type that implements Into<Span>).

Examples

let line = Line::default().spans(vec!["Hello".blue(), " world!".green()]);
let line = Line::default().spans([1, 2, 3].iter().map(|i| format!("Item {}", i)));

pub fn style<S: Into<Style>>(self, style: S) -> Self

Sets the style of this line of text.

Defaults to Style::default().

Note: This field was added in v0.26.0. Prior to that, the style of a line was determined only by the style of each Span contained in the line. For this reason, this field may not be supported by all widgets (outside of the ratatui crate itself).

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Examples

let mut line = Line::from("foo").style(Style::new().red());

Examples found in repository

examples/demo2/app.rs (line 198)

    fn render_bottom_bar(area: Rect, buf: &mut Buffer) {
        let keys = [
            ("H/←", "Left"),
            ("L/→", "Right"),
            ("K/↑", "Up"),
            ("J/↓", "Down"),
            ("D/Del", "Destroy"),
            ("Q/Esc", "Quit"),
        ];
        let spans = keys
            .iter()
            .flat_map(|(key, desc)| {
                let key = Span::styled(format!(" {key} "), THEME.key_binding.key);
                let desc = Span::styled(format!(" {desc} "), THEME.key_binding.description);
                [key, desc]
            })
            .collect_vec();
        Line::from(spans)
            .centered()
            .style((Color::Indexed(236), Color::Indexed(232)))
            .render(area, buf);
    }

pub fn alignment(self, alignment: Alignment) -> Self

Sets the target alignment for this line of text.

Defaults to: None, meaning the alignment is determined by the rendering widget. Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget.

Examples

let mut line = Line::from("Hi, what's up?");
assert_eq!(None, line.alignment);
assert_eq!(
    Some(Alignment::Right),
    line.alignment(Alignment::Right).alignment
)

pub fn left_aligned(self) -> Self

Left-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Left). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

let line = Line::from("Hi, what's up?").left_aligned();

pub fn centered(self) -> Self

Center-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Center). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

let line = Line::from("Hi, what's up?").centered();

Examples found in repository

examples/tabs.rs (line 157)

fn render_footer(area: Rect, buf: &mut Buffer) {
    Line::raw("◄ ► to change tab | Press q to quit")
        .centered()
        .render(area, buf);
}

examples/demo2/app.rs (line 197)

    fn render_bottom_bar(area: Rect, buf: &mut Buffer) {
        let keys = [
            ("H/←", "Left"),
            ("L/→", "Right"),
            ("K/↑", "Up"),
            ("J/↓", "Down"),
            ("D/Del", "Destroy"),
            ("Q/Esc", "Quit"),
        ];
        let spans = keys
            .iter()
            .flat_map(|(key, desc)| {
                let key = Span::styled(format!(" {key} "), THEME.key_binding.key);
                let desc = Span::styled(format!(" {desc} "), THEME.key_binding.description);
                [key, desc]
            })
            .collect_vec();
        Line::from(spans)
            .centered()
            .style((Color::Indexed(236), Color::Indexed(232)))
            .render(area, buf);
    }

examples/constraint-explorer.rs (line 318)

    fn swap_legend() -> impl Widget {
        #[allow(unstable_name_collisions)]
        Paragraph::new(
            Line::from(
                [
                    ConstraintName::Min,
                    ConstraintName::Max,
                    ConstraintName::Length,
                    ConstraintName::Percentage,
                    ConstraintName::Ratio,
                    ConstraintName::Fill,
                ]
                .iter()
                .enumerate()
                .map(|(i, name)| {
                    format!("  {i}: {name}  ", i = i + 1)
                        .fg(SLATE.c200)
                        .bg(name.color())
                })
                .intersperse(Span::from(" "))
                .collect_vec(),
            )
            .centered(),
        )
        .wrap(Wrap { trim: false })
    }

    /// A bar like `<----- 80 px (gap: 2 px) ----->`
    ///
    /// Only shows the gap when spacing is not zero
    fn axis(&self, width: u16) -> impl Widget {
        let label = if self.spacing != 0 {
            format!("{} px (gap: {} px)", width, self.spacing)
        } else {
            format!("{width} px")
        };
        let bar_width = width.saturating_sub(2) as usize; // we want to `<` and `>` at the ends
        let width_bar = format!("<{label:-^bar_width$}>");
        Paragraph::new(width_bar).fg(Self::AXIS_COLOR).centered()
    }

    fn render_layout_blocks(&self, area: Rect, buf: &mut Buffer) {
        let [user_constraints, area] = Layout::vertical([Length(3), Fill(1)])
            .spacing(1)
            .areas(area);

        self.render_user_constraints_legend(user_constraints, buf);

        let [start, center, end, space_around, space_between] =
            Layout::vertical([Length(7); 5]).areas(area);

        self.render_layout_block(Flex::Start, start, buf);
        self.render_layout_block(Flex::Center, center, buf);
        self.render_layout_block(Flex::End, end, buf);
        self.render_layout_block(Flex::SpaceAround, space_around, buf);
        self.render_layout_block(Flex::SpaceBetween, space_between, buf);
    }

    fn render_user_constraints_legend(&self, area: Rect, buf: &mut Buffer) {
        let blocks = Layout::horizontal(
            self.constraints
                .iter()
                .map(|_| Constraint::Fill(1))
                .collect_vec(),
        )
        .split(area);

        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
            let selected = self.selected_index == i;
            ConstraintBlock::new(*constraint, selected, true).render(*area, buf);
        }
    }

    fn render_layout_block(&self, flex: Flex, area: Rect, buf: &mut Buffer) {
        let [label_area, axis_area, blocks_area] =
            Layout::vertical([Length(1), Max(1), Length(4)]).areas(area);

        if label_area.height > 0 {
            format!("Flex::{flex:?}").bold().render(label_area, buf);
        }

        self.axis(area.width).render(axis_area, buf);

        let (blocks, spacers) = Layout::horizontal(&self.constraints)
            .flex(flex)
            .spacing(self.spacing)
            .split_with_spacers(blocks_area);

        for (i, (area, constraint)) in blocks.iter().zip(self.constraints.iter()).enumerate() {
            let selected = self.selected_index == i;
            ConstraintBlock::new(*constraint, selected, false).render(*area, buf);
        }

        for area in spacers.iter() {
            SpacerBlock.render(*area, buf);
        }
    }
}

impl Widget for ConstraintBlock {
    fn render(self, area: Rect, buf: &mut Buffer) {
        match area.height {
            1 => self.render_1px(area, buf),
            2 => self.render_2px(area, buf),
            _ => self.render_4px(area, buf),
        }
    }
}

impl ConstraintBlock {
    const TEXT_COLOR: Color = SLATE.c200;

    const fn new(constraint: Constraint, selected: bool, legend: bool) -> Self {
        Self {
            constraint,
            legend,
            selected,
        }
    }

    fn label(&self, width: u16) -> String {
        let long_width = format!("{width} px");
        let short_width = format!("{width}");
        // border takes up 2 columns
        let available_space = width.saturating_sub(2) as usize;
        let width_label = if long_width.len() < available_space {
            long_width
        } else if short_width.len() < available_space {
            short_width
        } else {
            String::new()
        };
        format!("{}\n{}", self.constraint, width_label)
    }

    fn render_1px(&self, area: Rect, buf: &mut Buffer) {
        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
        let main_color = ConstraintName::from(self.constraint).color();
        let selected_color = if self.selected {
            lighter_color
        } else {
            main_color
        };
        Block::default()
            .fg(Self::TEXT_COLOR)
            .bg(selected_color)
            .render(area, buf);
    }

    fn render_2px(&self, area: Rect, buf: &mut Buffer) {
        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
        let main_color = ConstraintName::from(self.constraint).color();
        let selected_color = if self.selected {
            lighter_color
        } else {
            main_color
        };
        Block::bordered()
            .border_set(symbols::border::QUADRANT_OUTSIDE)
            .border_style(Style::reset().fg(selected_color).reversed())
            .render(area, buf);
    }

    fn render_4px(&self, area: Rect, buf: &mut Buffer) {
        let lighter_color = ConstraintName::from(self.constraint).lighter_color();
        let main_color = ConstraintName::from(self.constraint).color();
        let selected_color = if self.selected {
            lighter_color
        } else {
            main_color
        };
        let color = if self.legend {
            selected_color
        } else {
            main_color
        };
        let label = self.label(area.width);
        let block = Block::bordered()
            .border_set(symbols::border::QUADRANT_OUTSIDE)
            .border_style(Style::reset().fg(color).reversed())
            .fg(Self::TEXT_COLOR)
            .bg(color);
        Paragraph::new(label)
            .centered()
            .fg(Self::TEXT_COLOR)
            .bg(color)
            .block(block)
            .render(area, buf);

        if !self.legend {
            let border_color = if self.selected {
                lighter_color
            } else {
                main_color
            };
            if let Some(last_row) = area.rows().last() {
                buf.set_style(last_row, border_color);
            }
        }
    }
}

impl Widget for SpacerBlock {
    fn render(self, area: Rect, buf: &mut Buffer) {
        match area.height {
            1 => (),
            2 => Self::render_2px(area, buf),
            3 => Self::render_3px(area, buf),
            _ => Self::render_4px(area, buf),
        }
    }
}

impl SpacerBlock {
    const TEXT_COLOR: Color = SLATE.c500;
    const BORDER_COLOR: Color = SLATE.c600;

    /// A block with a corner borders
    fn block() -> impl Widget {
        let corners_only = symbols::border::Set {
            top_left: line::NORMAL.top_left,
            top_right: line::NORMAL.top_right,
            bottom_left: line::NORMAL.bottom_left,
            bottom_right: line::NORMAL.bottom_right,
            vertical_left: " ",
            vertical_right: " ",
            horizontal_top: " ",
            horizontal_bottom: " ",
        };
        Block::bordered()
            .border_set(corners_only)
            .border_style(Self::BORDER_COLOR)
    }

    /// A vertical line used if there is not enough space to render the block
    fn line() -> impl Widget {
        Paragraph::new(Text::from(vec![
            Line::from(""),
            Line::from("│"),
            Line::from("│"),
            Line::from(""),
        ]))
        .style(Self::BORDER_COLOR)
    }

    /// A label that says "Spacer" if there is enough space
    fn spacer_label(width: u16) -> impl Widget {
        let label = if width >= 6 { "Spacer" } else { "" };
        label.fg(Self::TEXT_COLOR).into_centered_line()
    }

    /// A label that says "8 px" if there is enough space
    fn label(width: u16) -> impl Widget {
        let long_label = format!("{width} px");
        let short_label = format!("{width}");
        let label = if long_label.len() < width as usize {
            long_label
        } else if short_label.len() < width as usize {
            short_label
        } else {
            String::new()
        };
        Line::styled(label, Self::TEXT_COLOR).centered()
    }

examples/barchart.rs (line 207)

fn create_groups<'a>(app: &'a App, combine_values_and_labels: bool) -> Vec<BarGroup<'a>> {
    app.months
        .iter()
        .enumerate()
        .map(|(i, &month)| {
            let bars: Vec<Bar> = app
                .companies
                .iter()
                .map(|c| {
                    let mut bar = Bar::default()
                        .value(c.revenue[i])
                        .style(c.bar_style)
                        .value_style(
                            Style::default()
                                .bg(c.bar_style.fg.unwrap())
                                .fg(Color::Black),
                        );

                    if combine_values_and_labels {
                        bar = bar.text_value(format!(
                            "{} ({:.1} M)",
                            c.label,
                            (c.revenue[i] as f64) / 1000.
                        ));
                    } else {
                        bar = bar
                            .text_value(format!("{:.1}", (c.revenue[i] as f64) / 1000.))
                            .label(c.label.into());
                    }
                    bar
                })
                .collect();
            BarGroup::default()
                .label(Line::from(month).centered())
                .bars(&bars)
        })
        .collect()
}

examples/layout.rs (line 83)

fn ui(frame: &mut Frame) {
    let vertical = Layout::vertical([
        Length(4),  // text
        Length(50), // examples
        Min(0),     // fills remaining space
    ]);
    let [text_area, examples_area, _] = vertical.areas(frame.size());

    // title
    frame.render_widget(
        Paragraph::new(vec![
            Line::from("Horizontal Layout Example. Press q to quit".dark_gray()).centered(),
            Line::from("Each line has 2 constraints, plus Min(0) to fill the remaining space."),
            Line::from("E.g. the second line of the Len/Min box is [Length(2), Min(2), Min(0)]"),
            Line::from("Note: constraint labels that don't fit are truncated"),
        ]),
        text_area,
    );

    let example_rows = Layout::vertical([
        Length(9),
        Length(9),
        Length(9),
        Length(9),
        Length(9),
        Min(0), // fills remaining space
    ])
    .split(examples_area);
    let example_areas = example_rows
        .iter()
        .flat_map(|area| {
            Layout::horizontal([
                Length(14),
                Length(14),
                Length(14),
                Length(14),
                Length(14),
                Min(0), // fills remaining space
            ])
            .split(*area)
            .iter()
            .copied()
            .take(5) // ignore Min(0)
            .collect_vec()
        })
        .collect_vec();

    // the examples are a cartesian product of the following constraints
    // e.g. Len/Len, Len/Min, Len/Max, Len/Perc, Len/Ratio, Min/Len, Min/Min, ...
    let examples = [
        (
            "Len",
            vec![
                Length(0),
                Length(2),
                Length(3),
                Length(6),
                Length(10),
                Length(15),
            ],
        ),
        (
            "Min",
            vec![Min(0), Min(2), Min(3), Min(6), Min(10), Min(15)],
        ),
        (
            "Max",
            vec![Max(0), Max(2), Max(3), Max(6), Max(10), Max(15)],
        ),
        (
            "Perc",
            vec![
                Percentage(0),
                Percentage(25),
                Percentage(50),
                Percentage(75),
                Percentage(100),
                Percentage(150),
            ],
        ),
        (
            "Ratio",
            vec![
                Ratio(0, 4),
                Ratio(1, 4),
                Ratio(2, 4),
                Ratio(3, 4),
                Ratio(4, 4),
                Ratio(6, 4),
            ],
        ),
    ];

    for (i, (a, b)) in examples
        .iter()
        .cartesian_product(examples.iter())
        .enumerate()
    {
        let (name_a, examples_a) = a;
        let (name_b, examples_b) = b;
        let constraints = examples_a
            .iter()
            .copied()
            .zip(examples_b.iter().copied())
            .collect_vec();
        render_example_combination(
            frame,
            example_areas[i],
            &format!("{name_a}/{name_b}"),
            constraints,
        );
    }
}

pub fn right_aligned(self) -> Self

Right-aligns this line of text.

Convenience shortcut for Line::alignment(Alignment::Right). Setting the alignment of a Line generally overrides the alignment of its parent Text or Widget, with the default alignment being inherited from the parent.

Examples

let line = Line::from("Hi, what's up?").right_aligned();

pub fn width(&self) -> usize

Returns the width of the underlying string.

Examples

let line = Line::from(vec!["Hello".blue(), " world!".green()]);
assert_eq!(12, line.width());

Examples found in repository

examples/custom_widget.rs (line 119)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let (background, text, shadow, highlight) = self.colors();
        buf.set_style(area, Style::new().bg(background).fg(text));

        // render top line if there's enough space
        if area.height > 2 {
            buf.set_string(
                area.x,
                area.y,
                "▔".repeat(area.width as usize),
                Style::new().fg(highlight).bg(background),
            );
        }
        // render bottom line if there's enough space
        if area.height > 1 {
            buf.set_string(
                area.x,
                area.y + area.height - 1,
                "▁".repeat(area.width as usize),
                Style::new().fg(shadow).bg(background),
            );
        }
        // render label centered
        buf.set_line(
            area.x + (area.width.saturating_sub(self.label.width() as u16)) / 2,
            area.y + (area.height.saturating_sub(1)) / 2,
            &self.label,
            area.width,
        );
    }

pub fn styled_graphemes<S: Into<Style>>( &'a self, base_style: S ) -> impl Iterator<Item = StyledGrapheme<'a>>

Returns an iterator over the graphemes held by this line.

base_style is the Style that will be patched with each grapheme Style to get the resulting Style.

base_style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

Examples

use std::iter::Iterator;

use ratatui::{prelude::*, text::StyledGrapheme};

let line = Line::styled("Text", Style::default().fg(Color::Yellow));
let style = Style::default().fg(Color::Green).bg(Color::Black);
assert_eq!(
    line.styled_graphemes(style)
        .collect::<Vec<StyledGrapheme>>(),
    vec![
        StyledGrapheme::new("T", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("e", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("x", Style::default().fg(Color::Yellow).bg(Color::Black)),
        StyledGrapheme::new("t", Style::default().fg(Color::Yellow).bg(Color::Black)),
    ]
);

Examples found in repository

examples/demo2/big_text.rs (line 141)

    fn render(self, area: Rect, buf: &mut Buffer) {
        let layout = layout(area, self.pixel_size);
        for (line, line_layout) in self.lines.iter().zip(layout) {
            for (g, cell) in line.styled_graphemes(self.style).zip(line_layout) {
                render_symbol(&g, cell, buf, self.pixel_size);
            }
        }
    }

pub fn patch_style<S: Into<Style>>(self, style: S) -> Self

Patches the style of this Line, adding modifiers from the given style.

This is useful for when you want to apply a style to a line that already has some styling. In contrast to Line::style, this method will not overwrite the existing style, but instead will add the given style’s modifiers to this Line’s style.

style accepts any type that is convertible to Style (e.g. Style, Color, or your own type that implements Into<Style>).

This is a fluent setter method which must be chained or used as it consumes self

Examples

let line = Line::styled("My text", Modifier::ITALIC);

let styled_line = Line::styled("My text", (Color::Yellow, Modifier::ITALIC));

assert_eq!(styled_line, line.patch_style(Color::Yellow));

pub fn reset_style(self) -> Self

Resets the style of this Line.

Equivalent to calling patch_style(Style::reset()).

This is a fluent setter method which must be chained or used as it consumes self

Examples

let line = Line::styled("My text", style);

assert_eq!(Style::reset(), line.reset_style().style);

pub fn iter(&self) -> Iter<'_, Span<'a>>

Returns an iterator over the spans of this line.

pub fn iter_mut(&mut self) -> IterMut<'_, Span<'a>>

Returns a mutable iterator over the spans of this line.

pub fn push_span<T: Into<Span<'a>>>(&mut self, span: T)

Adds a span to the line.

span can be any type that is convertible into a Span. For example, you can pass a &str, a String, or a Span.

Examples

let mut line = Line::from("Hello, ");
line.push_span(Span::raw("world!"));
line.push_span(" How are you?");

Trait Implementations

impl<'a> Clone for Line<'a>

fn clone(&self) -> Line<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Line<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> Default for Line<'a>

fn default() -> Line<'a>

Returns the “default value” for a type.

impl Display for Line<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&'a str> for Line<'a>

fn from(s: &'a str) -> Self

Converts to this type from the input type.

impl<'a> From<Line<'a>> for String

fn from(line: Line<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Line<'a>> for Text<'a>

fn from(line: Line<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<Span<'a>> for Line<'a>

fn from(span: Span<'a>) -> Self

Converts to this type from the input type.

impl<'a> From<String> for Line<'a>

fn from(s: String) -> Self

Converts to this type from the input type.

impl<'a> From<Vec<Span<'a>>> for Line<'a>

fn from(spans: Vec<Span<'a>>) -> Self

Converts to this type from the input type.

impl<'a, T> FromIterator<T> for Line<'a>

where T: Into<Span<'a>>,

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<'a> Hash for Line<'a>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a> IntoIterator for &'a Line<'a>

type Item = &'a Span<'a>

The type of the elements being iterated over.

type IntoIter = Iter<'a, Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for &'a mut Line<'a>

type Item = &'a mut Span<'a>

The type of the elements being iterated over.

type IntoIter = IterMut<'a, Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> IntoIterator for Line<'a>

type Item = Span<'a>

The type of the elements being iterated over.

type IntoIter = IntoIter<Span<'a>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a> PartialEq for Line<'a>

fn eq(&self, other: &Line<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> Styled for Line<'a>

type Item = Line<'a>

fn style(&self) -> Style

Returns the style of the object.

fn set_style<S: Into<Style>>(self, style: S) -> Self::Item

Sets the style of the object.

impl Widget for Line<'_>

fn render(self, area: Rect, buf: &mut Buffer)

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl WidgetRef for Line<'_>

fn render_ref(&self, area: Rect, buf: &mut Buffer)

Available on crate feature unstable-widget-ref only.

Draws the current state of the widget in the given buffer. That is the only method required to implement a custom widget.

impl<'a> Eq for Line<'a>

impl<'a> StructuralPartialEq for Line<'a>