Struct tui::buffer::Buffer

pub struct Buffer {
    pub area: Rect,
    pub content: Vec<Cell>,
}

A buffer that maps to the desired content of the terminal after the draw call

No widget in the library interacts directly with the terminal. Instead each of them is required to draw their state to an intermediate buffer. It is basically a grid where each cell contains a grapheme, a foreground color and a background color. This grid will then be used to output the appropriate escape sequences and characters to draw the UI as the user has defined it.

Examples:

use tui::buffer::{Buffer, Cell};
use tui::layout::Rect;
use tui::style::{Color, Style, Modifier};

let mut buf = Buffer::empty(Rect{x: 0, y: 0, width: 10, height: 5});
buf.get_mut(0, 2).set_symbol("x");
assert_eq!(buf.get(0, 2).symbol, "x");
buf.set_string(3, 0, "string", Style::default().fg(Color::Red).bg(Color::White));
assert_eq!(buf.get(5, 0), &Cell{
    symbol: String::from("r"),
    fg: Color::Red,
    bg: Color::White,
    modifier: Modifier::empty()
});
buf.get_mut(5, 0).set_char('x');
assert_eq!(buf.get(5, 0).symbol, "x");

Fields

area: Rect

The area represented by this buffer

content: Vec<Cell>

The content of the buffer. The length of this Vec should always be equal to area.width * area.height

Implementations

impl Buffer

pub fn empty(area: Rect) -> Buffer

Returns a Buffer with all cells set to the default one

pub fn filled(area: Rect, cell: &Cell) -> Buffer

Returns a Buffer with all cells initialized with the attributes of the given Cell

pub fn with_lines<S>(lines: Vec<S>) -> Buffer where
    S: AsRef<str>, 

Returns a Buffer containing the given lines

pub fn content(&self) -> &[Cell]

Returns the content of the buffer as a slice

pub fn area(&self) -> &Rect

Returns the area covered by this buffer

pub fn get(&self, x: u16, y: u16) -> &Cell

Returns a reference to Cell at the given coordinates

pub fn get_mut(&mut self, x: u16, y: u16) -> &mut Cell

Returns a mutable reference to Cell at the given coordinates

pub fn index_of(&self, x: u16, y: u16) -> usize

Returns the index in the Vec for the given global (x, y) coordinates.

Global coordinates are offset by the Buffer's area offset (x/y).

Examples

let rect = Rect::new(200, 100, 10, 10);
let buffer = Buffer::empty(rect);
// Global coordinates to the top corner of this buffer's area
assert_eq!(buffer.index_of(200, 100), 0);

Panics

Panics when given an coordinate that is outside of this Buffer's area.

let rect = Rect::new(200, 100, 10, 10);
let buffer = Buffer::empty(rect);
// Top coordinate is outside of the buffer in global coordinate space, as the Buffer's area
// starts at (200, 100).
buffer.index_of(0, 0); // Panics

pub fn pos_of(&self, i: usize) -> (u16, u16)

Returns the (global) coordinates of a cell given its index

Global coordinates are offset by the Buffer's area offset (x/y).

Examples

let rect = Rect::new(200, 100, 10, 10);
let buffer = Buffer::empty(rect);
assert_eq!(buffer.pos_of(0), (200, 100));
assert_eq!(buffer.pos_of(14), (204, 101));

Panics

Panics when given an index that is outside the Buffer's content.

let rect = Rect::new(0, 0, 10, 10); // 100 cells in total
let buffer = Buffer::empty(rect);
// Index 100 is the 101th cell, which lies outside of the area of this Buffer.
buffer.pos_of(100); // Panics

pub fn set_string<S>(&mut self, x: u16, y: u16, string: S, style: Style) where
    S: AsRef<str>, 

Print a string, starting at the position (x, y)

pub fn set_stringn<S>(
    &mut self,
    x: u16,
    y: u16,
    string: S,
    width: usize,
    style: Style
) -> (u16, u16) where
    S: AsRef<str>, 

Print at most the first n characters of a string if enough space is available until the end of the line

pub fn set_spans<'a>(
    &mut self,
    x: u16,
    y: u16,
    spans: &Spans<'a>,
    width: u16
) -> (u16, u16)

pub fn set_span<'a>(
    &mut self,
    x: u16,
    y: u16,
    span: &Span<'a>,
    width: u16
) -> (u16, u16)

pub fn set_background(&mut self, area: Rect, color: Color)

👎 Deprecated since 0.10.0:

You should use styling capabilities of Buffer::set_style

pub fn set_style(&mut self, area: Rect, style: Style)

pub fn resize(&mut self, area: Rect)

Resize the buffer so that the mapped area matches the given area and that the buffer length is equal to area.width * area.height

pub fn reset(&mut self)

Reset all cells in the buffer

pub fn merge(&mut self, other: &Buffer)

Merge an other buffer into this one

pub fn diff<'a>(&self, other: &'a Buffer) -> Vec<(u16, u16, &'a Cell)>

Builds a minimal sequence of coordinates and Cells necessary to update the UI from self to other.

We're assuming that buffers are well-formed, that is no double-width cell is followed by a non-blank cell.

Multi-width characters handling:

(Index:) `01`
Prev:    `コ`
Next:    `aa`
Updates: `0: a, 1: a'

(Index:) `01`
Prev:    `a `
Next:    `コ`
Updates: `0: コ` (double width symbol at index 0 - skip index 1)

(Index:) `012`
Prev:    `aaa`
Next:    `aコ`
Updates: `0: a, 1: コ` (double width symbol at index 1 - skip index 2)

Trait Implementations

impl Clone for Buffer

pub fn clone(&self) -> Buffer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Buffer

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

Formats the value using the given formatter.

impl Default for Buffer

pub fn default() -> Buffer

Returns the "default value" for a type.

impl PartialEq<Buffer> for Buffer

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

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

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

This method tests for !=.

impl StructuralPartialEq for Buffer