Struct Cell

pub struct Cell {
    pub fg: Color,
    pub bg: Color,
    pub underline_color: Color,
    pub modifier: Modifier,
    pub skip: bool,
    /* private fields */
}

A buffer cell

Fields

fg: Color

The foreground color of the cell.

bg: Color

The background color of the cell.

underline_color: Color

Available on crate feature underline-color only.

The underline color of the cell.

modifier: Modifier

The modifier of the cell.

skip: bool

Whether the cell should be skipped when copying (diffing) the buffer to the screen.

Implementations

impl Cell

pub const EMPTY: Self

An empty Cell

pub const fn new(symbol: &'static str) -> Self

Creates a new Cell with the given symbol.

This works at compile time and puts the symbol onto the stack. Fails to build when the symbol doesnt fit onto the stack and requires to be placed on the heap. Use Self::default().set_symbol() in that case. See CompactString::const_new for more details on this.

pub fn symbol(&self) -> &str

Gets the symbol of the cell.

Examples found in repository

examples/demo2/destroy.rs (line 105)

fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
    if sub_frame == 0 {
        return;
    }

    let logo = indoc::indoc! {"
        ██████      ████    ██████    ████    ██████  ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██████    ████████    ██    ████████    ██    ██    ██  ██
        ██  ██    ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██      ████    ██
    "};
    let logo_text = Text::styled(logo, Color::Rgb(255, 255, 255));
    let area = centered_rect(area, logo_text.width() as u16, logo_text.height() as u16);

    let mask_buf = &mut Buffer::empty(area);
    logo_text.render(area, mask_buf);

    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);

    for row in area.rows() {
        for col in row.columns() {
            let cell = &mut buf[(col.x, col.y)];
            let mask_cell = &mut mask_buf[(col.x, col.y)];
            cell.set_symbol(mask_cell.symbol());

            // blend the mask cell color with the cell color
            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));

            let color = blend(mask_color, cell_color, percentage);
            cell.set_style(Style::new().fg(color));
        }
    }
}

pub fn set_symbol(&mut self, symbol: &str) -> &mut Self

Sets the symbol of the cell.

Examples found in repository

examples/widget_impl.rs (line 255)

fn fill<S: Into<Style>>(area: Rect, buf: &mut Buffer, symbol: &str, style: S) {
    let style = style.into();
    for y in area.top()..area.bottom() {
        for x in area.left()..area.right() {
            buf[(x, y)].set_symbol(symbol).set_style(style);
        }
    }
}

examples/hyperlink.rs (line 98)

    fn render(self, area: Rect, buffer: &mut Buffer) {
        (&self.text).render(area, buffer);

        // this is a hacky workaround for https://github.com/ratatui/ratatui/issues/902, a bug
        // in the terminal code that incorrectly calculates the width of ANSI escape sequences. It
        // works by rendering the hyperlink as a series of 2-character chunks, which is the
        // calculated width of the hyperlink text.
        for (i, two_chars) in self
            .text
            .to_string()
            .chars()
            .chunks(2)
            .into_iter()
            .enumerate()
        {
            let text = two_chars.collect::<String>();
            let hyperlink = format!("\x1B]8;;{}\x07{}\x1B]8;;\x07", self.url, text);
            buffer[(area.x + i as u16 * 2, area.y)].set_symbol(hyperlink.as_str());
        }
    }

examples/demo2/destroy.rs (line 105)

fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
    if sub_frame == 0 {
        return;
    }

    let logo = indoc::indoc! {"
        ██████      ████    ██████    ████    ██████  ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██████    ████████    ██    ████████    ██    ██    ██  ██
        ██  ██    ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██      ████    ██
    "};
    let logo_text = Text::styled(logo, Color::Rgb(255, 255, 255));
    let area = centered_rect(area, logo_text.width() as u16, logo_text.height() as u16);

    let mask_buf = &mut Buffer::empty(area);
    logo_text.render(area, mask_buf);

    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);

    for row in area.rows() {
        for col in row.columns() {
            let cell = &mut buf[(col.x, col.y)];
            let mask_cell = &mut mask_buf[(col.x, col.y)];
            cell.set_symbol(mask_cell.symbol());

            // blend the mask cell color with the cell color
            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));

            let color = blend(mask_color, cell_color, percentage);
            cell.set_style(Style::new().fg(color));
        }
    }
}

pub fn set_char(&mut self, ch: char) -> &mut Self

Sets the symbol of the cell to a single character.

Examples found in repository

examples/demo2/colors.rs (line 22)

    fn render(self, area: Rect, buf: &mut Buffer) {
        for (yi, y) in (area.top()..area.bottom()).enumerate() {
            let value = f32::from(area.height) - yi as f32;
            let value_fg = value / f32::from(area.height);
            let value_bg = (value - 0.5) / f32::from(area.height);
            for (xi, x) in (area.left()..area.right()).enumerate() {
                let hue = xi as f32 * 360.0 / f32::from(area.width);
                let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
                let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
                buf[(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
    }

examples/colors_rgb.rs (line 218)

    fn render(self, area: Rect, buf: &mut Buffer) {
        self.setup_colors(area);
        let colors = &self.colors;
        for (xi, x) in (area.left()..area.right()).enumerate() {
            // animate the colors by shifting the x index by the frame number
            let xi = (xi + self.frame_count) % (area.width as usize);
            for (yi, y) in (area.top()..area.bottom()).enumerate() {
                // render a half block character for each row of pixels with the foreground color
                // set to the color of the pixel and the background color set to the color of the
                // pixel below it
                let fg = colors[yi * 2][xi];
                let bg = colors[yi * 2 + 1][xi];
                buf[Position::new(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
        self.frame_count += 1;
    }

examples/demo2/tabs/about.rs (line 124)

pub fn render_logo(selected_row: usize, area: Rect, buf: &mut Buffer) {
    let eye_color = if selected_row % 2 == 0 {
        THEME.logo.rat_eye
    } else {
        THEME.logo.rat_eye_alt
    };
    let area = area.inner(Margin {
        vertical: 0,
        horizontal: 2,
    });
    for (y, (line1, line2)) in RATATUI_LOGO.iter().tuples().enumerate() {
        for (x, (ch1, ch2)) in line1.chars().zip(line2.chars()).enumerate() {
            let x = area.left() + x as u16;
            let y = area.top() + y as u16;
            let cell = &mut buf[(x, y)];
            let rat_color = THEME.logo.rat;
            let term_color = THEME.logo.term;
            match (ch1, ch2) {
                ('█', '█') => {
                    cell.set_char('█');
                    cell.fg = rat_color;
                    cell.bg = rat_color;
                }
                ('█', ' ') => {
                    cell.set_char('▀');
                    cell.fg = rat_color;
                }
                (' ', '█') => {
                    cell.set_char('▄');
                    cell.fg = rat_color;
                }
                ('█', 'x') => {
                    cell.set_char('▀');
                    cell.fg = rat_color;
                    cell.bg = term_color;
                }
                ('x', '█') => {
                    cell.set_char('▄');
                    cell.fg = rat_color;
                    cell.bg = term_color;
                }
                ('x', 'x') => {
                    cell.set_char(' ');
                    cell.fg = term_color;
                    cell.bg = term_color;
                }
                ('█', 'e') => {
                    cell.set_char('▀');
                    cell.fg = rat_color;
                    cell.bg = eye_color;
                }
                ('e', '█') => {
                    cell.set_char('▄');
                    cell.fg = rat_color;
                    cell.bg = eye_color;
                }
                (_, _) => {}
            };
        }
    }
}

pub fn set_fg(&mut self, color: Color) -> &mut Self

Sets the foreground color of the cell.

Examples found in repository

examples/demo2/colors.rs (line 22)

    fn render(self, area: Rect, buf: &mut Buffer) {
        for (yi, y) in (area.top()..area.bottom()).enumerate() {
            let value = f32::from(area.height) - yi as f32;
            let value_fg = value / f32::from(area.height);
            let value_bg = (value - 0.5) / f32::from(area.height);
            for (xi, x) in (area.left()..area.right()).enumerate() {
                let hue = xi as f32 * 360.0 / f32::from(area.width);
                let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
                let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
                buf[(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
    }

examples/colors_rgb.rs (line 218)

    fn render(self, area: Rect, buf: &mut Buffer) {
        self.setup_colors(area);
        let colors = &self.colors;
        for (xi, x) in (area.left()..area.right()).enumerate() {
            // animate the colors by shifting the x index by the frame number
            let xi = (xi + self.frame_count) % (area.width as usize);
            for (yi, y) in (area.top()..area.bottom()).enumerate() {
                // render a half block character for each row of pixels with the foreground color
                // set to the color of the pixel and the background color set to the color of the
                // pixel below it
                let fg = colors[yi * 2][xi];
                let bg = colors[yi * 2 + 1][xi];
                buf[Position::new(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
        self.frame_count += 1;
    }

pub fn set_bg(&mut self, color: Color) -> &mut Self

Sets the background color of the cell.

Examples found in repository

examples/demo2/colors.rs (line 22)

    fn render(self, area: Rect, buf: &mut Buffer) {
        for (yi, y) in (area.top()..area.bottom()).enumerate() {
            let value = f32::from(area.height) - yi as f32;
            let value_fg = value / f32::from(area.height);
            let value_bg = (value - 0.5) / f32::from(area.height);
            for (xi, x) in (area.left()..area.right()).enumerate() {
                let hue = xi as f32 * 360.0 / f32::from(area.width);
                let fg = color_from_oklab(hue, Okhsv::max_saturation(), value_fg);
                let bg = color_from_oklab(hue, Okhsv::max_saturation(), value_bg);
                buf[(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
    }

examples/colors_rgb.rs (line 218)

    fn render(self, area: Rect, buf: &mut Buffer) {
        self.setup_colors(area);
        let colors = &self.colors;
        for (xi, x) in (area.left()..area.right()).enumerate() {
            // animate the colors by shifting the x index by the frame number
            let xi = (xi + self.frame_count) % (area.width as usize);
            for (yi, y) in (area.top()..area.bottom()).enumerate() {
                // render a half block character for each row of pixels with the foreground color
                // set to the color of the pixel and the background color set to the color of the
                // pixel below it
                let fg = colors[yi * 2][xi];
                let bg = colors[yi * 2 + 1][xi];
                buf[Position::new(x, y)].set_char('▀').set_fg(fg).set_bg(bg);
            }
        }
        self.frame_count += 1;
    }

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

Sets the style of the cell.

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

Examples found in repository

examples/widget_impl.rs (line 255)

fn fill<S: Into<Style>>(area: Rect, buf: &mut Buffer, symbol: &str, style: S) {
    let style = style.into();
    for y in area.top()..area.bottom() {
        for x in area.left()..area.right() {
            buf[(x, y)].set_symbol(symbol).set_style(style);
        }
    }
}

examples/demo2/destroy.rs (line 112)

fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
    if sub_frame == 0 {
        return;
    }

    let logo = indoc::indoc! {"
        ██████      ████    ██████    ████    ██████  ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██████    ████████    ██    ████████    ██    ██    ██  ██
        ██  ██    ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██      ████    ██
    "};
    let logo_text = Text::styled(logo, Color::Rgb(255, 255, 255));
    let area = centered_rect(area, logo_text.width() as u16, logo_text.height() as u16);

    let mask_buf = &mut Buffer::empty(area);
    logo_text.render(area, mask_buf);

    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);

    for row in area.rows() {
        for col in row.columns() {
            let cell = &mut buf[(col.x, col.y)];
            let mask_cell = &mut mask_buf[(col.x, col.y)];
            cell.set_symbol(mask_cell.symbol());

            // blend the mask cell color with the cell color
            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));

            let color = blend(mask_color, cell_color, percentage);
            cell.set_style(Style::new().fg(color));
        }
    }
}

pub const fn style(&self) -> Style

Returns the style of the cell.

Examples found in repository

examples/demo2/destroy.rs (line 108)

fn text(frame_count: usize, area: Rect, buf: &mut Buffer) {
    let sub_frame = frame_count.saturating_sub(TEXT_DELAY);
    if sub_frame == 0 {
        return;
    }

    let logo = indoc::indoc! {"
        ██████      ████    ██████    ████    ██████  ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██████    ████████    ██    ████████    ██    ██    ██  ██
        ██  ██    ██    ██    ██    ██    ██    ██    ██    ██  ██
        ██    ██  ██    ██    ██    ██    ██    ██      ████    ██
    "};
    let logo_text = Text::styled(logo, Color::Rgb(255, 255, 255));
    let area = centered_rect(area, logo_text.width() as u16, logo_text.height() as u16);

    let mask_buf = &mut Buffer::empty(area);
    logo_text.render(area, mask_buf);

    let percentage = (sub_frame as f64 / 480.0).clamp(0.0, 1.0);

    for row in area.rows() {
        for col in row.columns() {
            let cell = &mut buf[(col.x, col.y)];
            let mask_cell = &mut mask_buf[(col.x, col.y)];
            cell.set_symbol(mask_cell.symbol());

            // blend the mask cell color with the cell color
            let cell_color = cell.style().bg.unwrap_or(Color::Rgb(0, 0, 0));
            let mask_color = mask_cell.style().fg.unwrap_or(Color::Rgb(255, 0, 0));

            let color = blend(mask_color, cell_color, percentage);
            cell.set_style(Style::new().fg(color));
        }
    }
}

pub fn set_skip(&mut self, skip: bool) -> &mut Self

Sets the cell to be skipped when copying (diffing) the buffer to the screen.

This is helpful when it is necessary to prevent the buffer from overwriting a cell that is covered by an image from some terminal graphics protocol (Sixel / iTerm / Kitty …).

pub fn reset(&mut self)

Resets the cell to the empty state.

Examples found in repository

examples/demo2/destroy.rs (line 66)

fn drip(frame_count: usize, area: Rect, buf: &mut Buffer) {
    // a seeded rng as we have to move the same random pixels each frame
    let mut rng = rand_chacha::ChaCha8Rng::seed_from_u64(10);
    let ramp_frames = 450;
    let fractional_speed = frame_count as f64 / f64::from(ramp_frames);
    let variable_speed = DRIP_SPEED as f64 * fractional_speed * fractional_speed * fractional_speed;
    let pixel_count = (frame_count as f64 * variable_speed).floor() as usize;
    for _ in 0..pixel_count {
        let src_x = rng.gen_range(0..area.width);
        let src_y = rng.gen_range(1..area.height - 2);
        let src = buf[(src_x, src_y)].clone();
        // 1% of the time, move a blank or pixel (10:1) to the top line of the screen
        if rng.gen_ratio(1, 100) {
            let dest_x = rng
                .gen_range(src_x.saturating_sub(5)..src_x.saturating_add(5))
                .clamp(area.left(), area.right() - 1);
            let dest_y = area.top() + 1;

            let dest = &mut buf[(dest_x, dest_y)];
            // copy the cell to the new location about 1/10 of the time blank out the cell the rest
            // of the time. This has the effect of gradually removing the pixels from the screen.
            if rng.gen_ratio(1, 10) {
                *dest = src;
            } else {
                dest.reset();
            }
        } else {
            // move the pixel down one row
            let dest_x = src_x;
            let dest_y = src_y.saturating_add(1).min(area.bottom() - 2);
            // copy the cell to the new location
            buf[(dest_x, dest_y)] = src;
        }
    }
}

Trait Implementations

impl Clone for Cell

fn clone(&self) -> Cell

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Cell

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

Formats the value using the given formatter.

impl Default for Cell

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Cell

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl From<char> for Cell

fn from(ch: char) -> Self

Converts to this type from the input type.

impl Hash for Cell

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 PartialEq for Cell

fn eq(&self, other: &Cell) -> bool

Tests for self and other values to be equal, and is used by ==.

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

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

impl Serialize for Cell

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Cell

impl StructuralPartialEq for Cell