Struct Display 

pub struct Display { /* private fields */ }

The terminal buffer: a grid of Pixels that you draw into, then print.

Nothing reaches the terminal until you call Display::print (or get the output with Display::render / Display::write_to). Coordinates are (x, y) with (0, 0) at the top left, x growing to the right and y growing down. Drawing outside the display is silently clipped, so nothing here panics on out-of-range coordinates.

use terminal_graphics::{Colour, Display};

let mut display = Display::new(10, 3);
display.set_pixel(1, 1, '#', Colour::Red, Colour::Black);

assert_eq!(display.pixel(1, 1).unwrap().character(), '#');
assert!(display.render().contains('#'));

Implementations

impl Display

pub fn new(width: u32, height: u32) -> Display

Creates a display width columns wide and height rows high, with every pixel set to the default (a black space on a white background).

A size of 0 in either direction gives a display with no pixels, so all drawing into it is clipped.

use terminal_graphics::Display;

let display = Display::new(10, 3);
assert_eq!(display.size(), (10, 3));

Examples found in repository

examples/paint.rs (line 69)

    fn new(width: u32, height: u32) -> Paint {
        let mut paint = Paint {
            display: Display::new(width, height),
            brush: 0,
            last: None,
        };
        paint.clear();
        paint
    }

examples/quickstart.rs (line 9)

fn main() -> std::io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    loop {
        terminal.draw(&display)?;

        // wait up to 50 ms for input; `None` means a frame passed with no input
        match terminal.poll(Duration::from_millis(50))? {
            Some(Event::Key(key)) if key.is_char('q') || key.is_ctrl('c') => return Ok(()),
            Some(Event::Mouse(mouse)) if matches!(mouse.kind, MouseKind::Down(_)) => {
                if let Some((x, y)) = mouse.cell_in(&display) {
                    display.set_pixel(x, y, 'X', Colour::BrightYellow, Colour::Blue);
                }
            }
            _ => {}
        }
    }
}

examples/screensaver.rs (line 179)

fn main() -> io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    // any number will do as a seed; the clock makes each run different
    let seed = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(1, |since| since.subsec_nanos())
        ^ std::process::id();
    let mut saver = Screensaver::new(display.width(), display.height(), seed);

    let mut next_frame = Instant::now() + FRAME;
    loop {
        saver.render(&mut display);
        terminal.draw(&display)?;

        // spend the time until the next frame handling input
        loop {
            let wait = next_frame.saturating_duration_since(Instant::now());
            match terminal.poll(wait)? {
                Some(event) => {
                    if saver.handle(&event) == Action::Quit {
                        return Ok(());
                    }
                }
                None => break,
            }
        }

        saver.step();
        // if we fell behind, do not try to catch up with a burst of frames
        next_frame = (next_frame + FRAME).max(Instant::now());
    }
}

pub fn size(&self) -> (u32, u32)

The display size as (width, height), in cells.

pub fn width(&self) -> u32

The number of columns.

Examples found in repository

examples/paint.rs (line 80)

    fn clear(&mut self) {
        for y in 0..self.canvas_height() {
            for x in 0..self.display.width() as isize {
                self.display
                    .set_pixel(x, y, ' ', Colour::White, Colour::Black);
            }
        }
        self.draw_status();
    }

    /// The last row of the display is the status line, not canvas.
    fn canvas_height(&self) -> isize {
        self.display.height() as isize - 1
    }

    /// One swatch per colour (the chosen one marked `#`), then the controls.
    fn draw_status(&mut self) {
        let y = self.canvas_height();
        for x in 0..self.display.width() as isize {
            self.display
                .set_pixel(x, y, ' ', Colour::White, Colour::Black);
        }
        for (index, colour) in PALETTE.iter().enumerate() {
            let mark = if index == self.brush { '#' } else { ' ' };
            self.display
                .set_pixel(index as isize, y, mark, Colour::Black, *colour);
        }
        let help = "1-8 or scroll: colour   drag: paint   right drag: erase   c: clear   q: quit";
        Text::new(
            PALETTE.len() as isize + 1,
            y,
            help,
            Colour::White,
            Colour::Black,
        )
        .draw(&mut self.display);
    }

    /// Paints (or erases, with black) from where the pointer last was to `(x, y)`.
    fn stroke(&mut self, x: isize, y: isize, colour: Colour) {
        let width = self.display.width() as isize;
        let height = self.canvas_height();

        // Keep the line walk short and free of overflow however wild the
        // coordinates are: one cell outside the canvas is as good as a mile.
        let clamp = |(x, y): (isize, isize)| (x.clamp(-1, width), y.clamp(-1, height));
        let from = self.last.unwrap_or((x, y));
        for (cx, cy) in line(clamp(from), clamp((x, y))) {
            if (0..width).contains(&cx) && (0..height).contains(&cy) {
                self.display.set_pixel(cx, cy, ' ', Colour::White, colour);
            }
        }
        self.last = Some((x, y));
    }

examples/screensaver.rs (line 186)

fn main() -> io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    // any number will do as a seed; the clock makes each run different
    let seed = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(1, |since| since.subsec_nanos())
        ^ std::process::id();
    let mut saver = Screensaver::new(display.width(), display.height(), seed);

    let mut next_frame = Instant::now() + FRAME;
    loop {
        saver.render(&mut display);
        terminal.draw(&display)?;

        // spend the time until the next frame handling input
        loop {
            let wait = next_frame.saturating_duration_since(Instant::now());
            match terminal.poll(wait)? {
                Some(event) => {
                    if saver.handle(&event) == Action::Quit {
                        return Ok(());
                    }
                }
                None => break,
            }
        }

        saver.step();
        // if we fell behind, do not try to catch up with a burst of frames
        next_frame = (next_frame + FRAME).max(Instant::now());
    }
}

pub fn height(&self) -> u32

The number of rows.

Examples found in repository

examples/paint.rs (line 90)

    fn canvas_height(&self) -> isize {
        self.display.height() as isize - 1
    }

examples/screensaver.rs (line 186)

fn main() -> io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    // any number will do as a seed; the clock makes each run different
    let seed = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_or(1, |since| since.subsec_nanos())
        ^ std::process::id();
    let mut saver = Screensaver::new(display.width(), display.height(), seed);

    let mut next_frame = Instant::now() + FRAME;
    loop {
        saver.render(&mut display);
        terminal.draw(&display)?;

        // spend the time until the next frame handling input
        loop {
            let wait = next_frame.saturating_duration_since(Instant::now());
            match terminal.poll(wait)? {
                Some(event) => {
                    if saver.handle(&event) == Action::Quit {
                        return Ok(());
                    }
                }
                None => break,
            }
        }

        saver.step();
        // if we fell behind, do not try to catch up with a burst of frames
        next_frame = (next_frame + FRAME).max(Instant::now());
    }
}

pub fn set_pixel( &mut self, x: isize, y: isize, character: char, colour: Colour, background: Colour, )

Sets the character and both colours of the pixel at (x, y). Coordinates outside the display are ignored.

use terminal_graphics::{Colour, Display};

let mut display = Display::new(4, 2);
display.set_pixel(3, 1, 'x', Colour::Green, Colour::Blue);

// (4, 0) is outside a 4 by 2 display, so this has no effect
display.set_pixel(4, 0, 'y', Colour::Red, Colour::Red);
assert!(!display.render().contains('y'));

Examples found in repository

examples/paint.rs (line 82)

    fn clear(&mut self) {
        for y in 0..self.canvas_height() {
            for x in 0..self.display.width() as isize {
                self.display
                    .set_pixel(x, y, ' ', Colour::White, Colour::Black);
            }
        }
        self.draw_status();
    }

    /// The last row of the display is the status line, not canvas.
    fn canvas_height(&self) -> isize {
        self.display.height() as isize - 1
    }

    /// One swatch per colour (the chosen one marked `#`), then the controls.
    fn draw_status(&mut self) {
        let y = self.canvas_height();
        for x in 0..self.display.width() as isize {
            self.display
                .set_pixel(x, y, ' ', Colour::White, Colour::Black);
        }
        for (index, colour) in PALETTE.iter().enumerate() {
            let mark = if index == self.brush { '#' } else { ' ' };
            self.display
                .set_pixel(index as isize, y, mark, Colour::Black, *colour);
        }
        let help = "1-8 or scroll: colour   drag: paint   right drag: erase   c: clear   q: quit";
        Text::new(
            PALETTE.len() as isize + 1,
            y,
            help,
            Colour::White,
            Colour::Black,
        )
        .draw(&mut self.display);
    }

    /// Paints (or erases, with black) from where the pointer last was to `(x, y)`.
    fn stroke(&mut self, x: isize, y: isize, colour: Colour) {
        let width = self.display.width() as isize;
        let height = self.canvas_height();

        // Keep the line walk short and free of overflow however wild the
        // coordinates are: one cell outside the canvas is as good as a mile.
        let clamp = |(x, y): (isize, isize)| (x.clamp(-1, width), y.clamp(-1, height));
        let from = self.last.unwrap_or((x, y));
        for (cx, cy) in line(clamp(from), clamp((x, y))) {
            if (0..width).contains(&cx) && (0..height).contains(&cy) {
                self.display.set_pixel(cx, cy, ' ', Colour::White, colour);
            }
        }
        self.last = Some((x, y));
    }

examples/screensaver.rs (line 155)

    fn render(&self, display: &mut Display) {
        for y in 0..self.height {
            for x in 0..self.width {
                let (colour, frames_left) = self.trail[(y * self.width + x) as usize];
                let block = match frames_left {
                    0 => ' ',
                    n if n == TRAIL_LENGTH => '█',
                    n if n * 3 >= TRAIL_LENGTH * 2 => '▓',
                    n if n * 3 >= TRAIL_LENGTH => '▒',
                    _ => '░',
                };
                display.set_pixel(x, y, block, colour, Colour::Black);
            }
        }
    }

examples/quickstart.rs (line 19)

fn main() -> std::io::Result<()> {
    let mut terminal = Terminal::start()?;

    // `draw` needs a display at most one row shorter than the window
    let (width, height) = terminal.size();
    let mut display = Display::new(width, height.saturating_sub(1));

    loop {
        terminal.draw(&display)?;

        // wait up to 50 ms for input; `None` means a frame passed with no input
        match terminal.poll(Duration::from_millis(50))? {
            Some(Event::Key(key)) if key.is_char('q') || key.is_ctrl('c') => return Ok(()),
            Some(Event::Mouse(mouse)) if matches!(mouse.kind, MouseKind::Down(_)) => {
                if let Some((x, y)) = mouse.cell_in(&display) {
                    display.set_pixel(x, y, 'X', Colour::BrightYellow, Colour::Blue);
                }
            }
            _ => {}
        }
    }
}

pub fn pixel(&self, x: isize, y: isize) -> Option<&Pixel>

The pixel at (x, y), or None if that position is outside the display. Use it to read what has been drawn.

use terminal_graphics::{Colour, Display};

let mut display = Display::new(3, 1);
display.set_pixel(2, 0, '#', Colour::Red, Colour::Black);

assert_eq!(display.pixel(2, 0).unwrap().character(), '#');
assert!(display.pixel(3, 0).is_none());

pub fn pixel_mut(&mut self, x: isize, y: isize) -> Option<&mut Pixel>

A mutable reference to the pixel at (x, y), or None if that position is outside the display. Use it to change just one property of a pixel, such as its background.

use terminal_graphics::{Colour, Display};

let mut display = Display::new(3, 3);
if let Some(pixel) = display.pixel_mut(2, 2) {
    pixel.set_character('@');
    pixel.set_colour(Colour::Yellow);
}

assert!(display.pixel_mut(3, 0).is_none());

pub fn clear(&mut self)

Resets every pixel to the default (a black space on a white background). The size of the display does not change.

pub fn render(&self) -> String

Renders the display to a string of ANSI escape codes, without printing it.

The string starts by moving the cursor up by the display’s height, so printing it again overwrites the previous frame in place. A display with no rows renders to an empty string.

Use this for tests, or to send the output somewhere other than stdout.

use terminal_graphics::{Colour, Display};

let mut display = Display::new(2, 1);
display.set_pixel(0, 0, 'A', Colour::Red, Colour::Black);

let output = display.render();
assert!(output.starts_with("\x1b[1F"));
assert!(output.contains('A'));

pub fn write_to<W>(&self, writer: &mut W) -> Result<(), Error>

where W: Write,

Writes the rendered display, as produced by Display::render, to any writer: a file, a Vec<u8>, a socket, and so on. Does not flush.

use terminal_graphics::Display;

let display = Display::new(3, 1);
let mut bytes: Vec<u8> = Vec::new();
display.write_to(&mut bytes).unwrap();
assert_eq!(bytes, display.render().into_bytes());

pub fn print(&self) -> Result<(), Error>

Prints the display to stdout and flushes it. Printing the same display again redraws it in place.

Returns the error if stdout cannot be written to, for example a closed pipe. Call Display::reserve_space once before the first frame.

pub fn reserve_space(&self) -> Result<(), Error>

Prints one blank line per display row, making room for the display.

Each frame starts by moving the cursor up over the previous one, so there must be at least height lines above the cursor to draw on. Call this once before the first Display::print; without it the first frame overwrites whatever is above the cursor. Do not call it between frames.

use terminal_graphics::Display;

let display = Display::new(40, 10);
display.reserve_space()?;
display.print()?;

Trait Implementations

impl Clone for Display

fn clone(&self) -> Display

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Display

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

Formats the value using the given formatter.

impl Eq for Display

impl PartialEq for Display

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for Display