rustom 0.1.0

A library for building rich, stateful terminal user interfaces and dashboards.
Documentation
//! `Terminal` owns a `Backend` plus two buffers (the currently displayed
//! frame and the one being built), and diffs them on every `draw` call so
//! only cells that actually changed get written to the real terminal.

use std::io;

use crate::backend::Backend;
use crate::buffer::Buffer;
use crate::layout::Rect;
use crate::widgets::{StatefulWidget, Widget};

/// A handle passed into the draw closure, used to render widgets into the
/// buffer for the frame currently being built.
pub struct Frame<'a> {
    buffer: &'a mut Buffer,
    area: Rect,
    cursor_position: &'a mut Option<(u16, u16)>,
}

impl<'a> Frame<'a> {
    /// The full area available to draw into this frame.
    pub fn area(&self) -> Rect {
        self.area
    }

    pub fn render_widget<W: Widget>(&mut self, widget: W, area: Rect) {
        widget.render(area, self.buffer);
    }

    pub fn render_stateful_widget<W: StatefulWidget>(
        &mut self,
        widget: W,
        area: Rect,
        state: &mut W::State,
    ) {
        widget.render(area, self.buffer, state);
    }

    /// Requests that the terminal cursor be moved to `(x, y)` and shown
    /// after this frame is flushed. Call this from within the draw closure
    /// when a widget such as a text input wants a visible cursor.
    pub fn set_cursor_position(&mut self, x: u16, y: u16) {
        *self.cursor_position = Some((x, y));
    }
}

/// Owns the backend and the double buffer, and drives the diff based
/// rendering loop.
pub struct Terminal<B: Backend> {
    backend: B,
    buffers: [Buffer; 2],
    current: usize,
    cursor_position: Option<(u16, u16)>,
}

impl<B: Backend> Terminal<B> {
    pub fn new(backend: B) -> io::Result<Terminal<B>> {
        let size = backend.size()?;
        Ok(Terminal {
            backend,
            buffers: [Buffer::empty(size), Buffer::empty(size)],
            current: 0,
            cursor_position: None,
        })
    }

    pub fn backend(&self) -> &B {
        &self.backend
    }

    pub fn backend_mut(&mut self) -> &mut B {
        &mut self.backend
    }

    pub fn size(&self) -> io::Result<Rect> {
        self.backend.size()
    }

    /// Resizes both internal buffers to match the current terminal size,
    /// forcing a full repaint on the next `draw`.
    pub fn autoresize(&mut self) -> io::Result<()> {
        let size = self.backend.size()?;
        if size != self.buffers[self.current].area {
            self.buffers[0].resize(size);
            self.buffers[1].resize(size);
        }
        Ok(())
    }

    /// Runs `f` against a fresh `Frame`, diffs the resulting buffer against
    /// the last one drawn, writes only the changed cells to the backend,
    /// and flushes.
    pub fn draw<F>(&mut self, f: F) -> io::Result<()>
    where
        F: FnOnce(&mut Frame),
    {
        self.autoresize()?;

        let area = self.buffers[self.current].area;
        self.buffers[self.current].reset();

        {
            let mut frame = Frame {
                buffer: &mut self.buffers[self.current],
                area,
                cursor_position: &mut self.cursor_position,
            };
            f(&mut frame);
        }

        let previous = 1 - self.current;
        let updates = self.buffers[previous].diff(&self.buffers[self.current]);
        self.backend.draw(updates.into_iter())?;

        match self.cursor_position {
            Some((x, y)) => {
                self.backend.set_cursor_position(x, y)?;
                self.backend.show_cursor()?;
            }
            None => self.backend.hide_cursor()?,
        }

        self.backend.flush()?;
        self.current = previous;
        Ok(())
    }

    pub fn clear(&mut self) -> io::Result<()> {
        self.backend.clear()?;
        self.buffers[0].reset();
        self.buffers[1].reset();
        Ok(())
    }

    pub fn hide_cursor(&mut self) -> io::Result<()> {
        self.backend.hide_cursor()
    }

    pub fn show_cursor(&mut self) -> io::Result<()> {
        self.backend.show_cursor()
    }
}