Struct Canvas

pub struct Canvas<'a, F>
where
    F: Fn(&mut Context<'_>),
{ /* private fields */ }

The Canvas widget provides a means to draw shapes (Lines, Rectangles, Circles, etc.) on a grid.

By default the grid is made of Braille patterns but you may change the marker to use a different set of symbols. If your terminal or font does not support this unicode block, you will see unicode replacement characters (�) instead of braille dots. The Braille patterns provide a more fine grained result (2x4 dots) but you might want to use a simple dot, block, or bar instead by calling the marker method if your target environment does not support those symbols,

See Unicode Braille Patterns for more info.

The HalfBlock marker is useful when you want to draw shapes with a higher resolution than a CharGrid but lower than a BrailleGrid. This grid type supports a foreground and background color for each terminal cell. This allows for more flexibility than the BrailleGrid which only supports a single foreground color for each 2x4 dots cell.

The Canvas widget is used by calling the Canvas::paint method and passing a closure that will be used to draw on the canvas. The closure will be passed a Context object that can be used to draw shapes on the canvas.

The Context object provides a Context::draw method that can be used to draw shapes on the canvas. The Context::layer method can be used to save the current state of the canvas and start a new layer. This is useful if you want to draw multiple shapes on the canvas in specific order. The Context object also provides a Context::print method that can be used to print text on the canvas. Note that the text is always printed on top of the canvas and is not affected by the layers.

Examples

use ratatui::{
    style::Color,
    widgets::{
        canvas::{Canvas, Line, Map, MapResolution, Rectangle},
        Block,
    },
};

Canvas::default()
    .block(Block::bordered().title("Canvas"))
    .x_bounds([-180.0, 180.0])
    .y_bounds([-90.0, 90.0])
    .paint(|ctx| {
        ctx.draw(&Map {
            resolution: MapResolution::High,
            color: Color::White,
        });
        ctx.layer();
        ctx.draw(&Line {
            x1: 0.0,
            y1: 10.0,
            x2: 10.0,
            y2: 10.0,
            color: Color::White,
        });
        ctx.draw(&Rectangle {
            x: 10.0,
            y: 20.0,
            width: 10.0,
            height: 10.0,
            color: Color::Red,
        });
    });

Implementations

impl<'a, F> Canvas<'a, F>

where F: Fn(&mut Context<'_>),

pub fn block(self, block: Block<'a>) -> Self

Wraps the canvas with a custom Block widget.

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

pub const fn x_bounds(self, bounds: [f64; 2]) -> Self

Define the viewport of the canvas.

If you were to “zoom” to a certain part of the world you may want to choose different bounds.

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

pub const fn y_bounds(self, bounds: [f64; 2]) -> Self

Define the viewport of the canvas.

If you were to “zoom” to a certain part of the world you may want to choose different bounds.

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

pub fn paint(self, f: F) -> Self

Store the closure that will be used to draw to the Canvas

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

pub const fn background_color(self, color: Color) -> Self

Change the background Color of the entire canvas

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

pub const fn marker(self, marker: Marker) -> Self

Change the type of points used to draw the shapes.

By default the Braille patterns are used as they provide a more fine grained result, but you might want to use the simple Dot or Block instead if the targeted terminal does not support those symbols.

The HalfBlock marker is useful when you want to draw shapes with a higher resolution than with a grid of characters (e.g. with Block or Dot) but lower than with Braille. This grid type supports a foreground and background color for each terminal cell. This allows for more flexibility than the BrailleGrid which only supports a single foreground color for each 2x4 dots cell.

Examples

use ratatui::{symbols, widgets::canvas::Canvas};

Canvas::default()
    .marker(symbols::Marker::Braille)
    .paint(|ctx| {});

Canvas::default()
    .marker(symbols::Marker::HalfBlock)
    .paint(|ctx| {});

Canvas::default()
    .marker(symbols::Marker::Dot)
    .paint(|ctx| {});

Canvas::default()
    .marker(symbols::Marker::Block)
    .paint(|ctx| {});

Trait Implementations

impl<'a, F> Clone for Canvas<'a, F>

where F: Fn(&mut Context<'_>) + Clone,

fn clone(&self) -> Canvas<'a, F>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, F> Debug for Canvas<'a, F>

where F: Fn(&mut Context<'_>) + Debug,

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

Formats the value using the given formatter.

impl<'a, F> Default for Canvas<'a, F>

where F: Fn(&mut Context<'_>),

fn default() -> Self

Returns the “default value” for a type.

impl<'a, F> PartialEq for Canvas<'a, F>

where F: Fn(&mut Context<'_>) + PartialEq,

fn eq(&self, other: &Canvas<'a, F>) -> 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<F> Widget for Canvas<'_, F>

where F: Fn(&mut Context<'_>),

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<F> WidgetRef for Canvas<'_, F>

where F: Fn(&mut Context<'_>),

fn render_ref(&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<'a, F> StructuralPartialEq for Canvas<'a, F>

where F: Fn(&mut Context<'_>),