Struct ratatui::widgets::canvas::Canvas

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

The Canvas widget may be used to draw more detailed figures using braille patterns (each cell can have a braille character in 8 different positions).

Examples

Canvas::default()
    .block(Block::default().title("Canvas").borders(Borders::ALL))
    .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>) -> Canvas<'a, F>

Examples found in repository

examples/canvas.rs (line 172)

fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
        .split(f.size());
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("World"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&Map {
                color: Color::White,
                resolution: MapResolution::High,
            });
            ctx.print(
                app.x,
                -app.y,
                Span::styled("You are here", Style::default().fg(Color::Yellow)),
            );
        })
        .x_bounds([-180.0, 180.0])
        .y_bounds([-90.0, 90.0]);
    f.render_widget(canvas, chunks[0]);
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("Pong"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&app.ball);
        })
        .x_bounds([10.0, 110.0])
        .y_bounds([10.0, 110.0]);
    f.render_widget(canvas, chunks[1]);
}

pub fn x_bounds(self, bounds: [f64; 2]) -> Canvas<'a, F>

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.

Examples found in repository

examples/canvas.rs (line 185)

fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
        .split(f.size());
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("World"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&Map {
                color: Color::White,
                resolution: MapResolution::High,
            });
            ctx.print(
                app.x,
                -app.y,
                Span::styled("You are here", Style::default().fg(Color::Yellow)),
            );
        })
        .x_bounds([-180.0, 180.0])
        .y_bounds([-90.0, 90.0]);
    f.render_widget(canvas, chunks[0]);
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("Pong"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&app.ball);
        })
        .x_bounds([10.0, 110.0])
        .y_bounds([10.0, 110.0]);
    f.render_widget(canvas, chunks[1]);
}

pub fn y_bounds(self, bounds: [f64; 2]) -> Canvas<'a, F>

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.

Examples found in repository

examples/canvas.rs (line 186)

fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
        .split(f.size());
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("World"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&Map {
                color: Color::White,
                resolution: MapResolution::High,
            });
            ctx.print(
                app.x,
                -app.y,
                Span::styled("You are here", Style::default().fg(Color::Yellow)),
            );
        })
        .x_bounds([-180.0, 180.0])
        .y_bounds([-90.0, 90.0]);
    f.render_widget(canvas, chunks[0]);
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("Pong"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&app.ball);
        })
        .x_bounds([10.0, 110.0])
        .y_bounds([10.0, 110.0]);
    f.render_widget(canvas, chunks[1]);
}

pub fn paint(self, f: F) -> Canvas<'a, F>

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

Examples found in repository

examples/canvas.rs (lines 174-184)

fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
        .split(f.size());
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("World"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&Map {
                color: Color::White,
                resolution: MapResolution::High,
            });
            ctx.print(
                app.x,
                -app.y,
                Span::styled("You are here", Style::default().fg(Color::Yellow)),
            );
        })
        .x_bounds([-180.0, 180.0])
        .y_bounds([-90.0, 90.0]);
    f.render_widget(canvas, chunks[0]);
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("Pong"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&app.ball);
        })
        .x_bounds([10.0, 110.0])
        .y_bounds([10.0, 110.0]);
    f.render_widget(canvas, chunks[1]);
}

pub fn background_color(self, color: Color) -> Canvas<'a, F>

pub fn marker(self, marker: Marker) -> Canvas<'a, F>

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.

Examples

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

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

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

Examples found in repository

examples/canvas.rs (line 173)

fn ui<B: Backend>(f: &mut Frame<B>, app: &App) {
    let chunks = Layout::default()
        .direction(Direction::Horizontal)
        .constraints([Constraint::Percentage(50), Constraint::Percentage(50)].as_ref())
        .split(f.size());
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("World"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&Map {
                color: Color::White,
                resolution: MapResolution::High,
            });
            ctx.print(
                app.x,
                -app.y,
                Span::styled("You are here", Style::default().fg(Color::Yellow)),
            );
        })
        .x_bounds([-180.0, 180.0])
        .y_bounds([-90.0, 90.0]);
    f.render_widget(canvas, chunks[0]);
    let canvas = Canvas::default()
        .block(Block::default().borders(Borders::ALL).title("Pong"))
        .marker(app.marker)
        .paint(|ctx| {
            ctx.draw(&app.ball);
        })
        .x_bounds([10.0, 110.0])
        .y_bounds([10.0, 110.0]);
    f.render_widget(canvas, chunks[1]);
}

Trait Implementations

impl<'a, F> Default for Canvas<'a, F>where F: Fn(&mut Context<'_>),

fn default() -> Canvas<'a, F>

Returns the “default value” for a type.

impl<'a, F> Widget for Canvas<'a, 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.