Guide API
Skip to main content

Backend

Trait Backend 

Source
pub trait Backend {
    // Required methods
    fn size(&self) -> (u16, u16);
    fn draw(&mut self, content: &[(u16, u16, &Cell)]);
    fn flush(&mut self);
    fn set_cursor(&mut self, pos: Option<(u16, u16)>);
    fn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>;
    fn set_clipboard(&mut self, text: &str) -> bool;
    fn get_clipboard(&mut self) -> Option<String>;

    // Provided methods
    fn set_caret_size(&mut self, _size: u8) { ... }
    fn get_primary(&mut self) -> Option<String> { ... }
    fn set_primary(&mut self, _text: &str) -> bool { ... }
    fn suspend(&mut self) { ... }
    fn resume(&mut self) { ... }
}
Expand description

Platform seam between the framework and the terminal.

The Backend trait — the object-safe terminal seam.

The app holds a Box<dyn Backend>; the view tree never carries a <B> type parameter. This trait must therefore be object-safe — no generic methods.

Two implementations exist:

The trait is object-safe; the app holds Box<dyn Backend>.

§Turbo Vision heritage

Stands in for the platform layer of TScreen / THardwareInfo (hardware.cpp, tscreen.cpp) plus the event source pump. The original selected a platform driver at link time; here the seam is a runtime trait object so the view tree carries no backend type parameter, and tests can swap in an in-memory fake (deviation D11).

Required Methods§

Source

fn size(&self) -> (u16, u16)

Live terminal dimensions in cells, returned as (cols, rows).

Called on each pump cycle to size the root group and therefore the desktop. Because the query is on-demand there is no mutable global to keep in sync: the program resizes the desktop whenever the value changes between cycles.

The production CrosstermBackend asks the terminal at every call; the HeadlessBackend returns the fixed size passed to HeadlessBackend::new.

Custom backend implementors should query the OS terminal size here — the result is used directly for desktop layout, so a stale value will leave the view tree sized incorrectly after a terminal resize.

§Turbo Vision heritage

Replaces the ScreenWidth and ScreenHeight mutable globals (Byte each, set once by InitVideo in drivers.cpp). The Rust port queries on demand instead of caching a stale global, so terminal resizes are picked up automatically on the next pump cycle.

Source

fn draw(&mut self, content: &[(u16, u16, &Cell)])

Apply changed cells to the screen.

Each tuple is (x, y, &cell); the backend writes that cell at position (x, y). Called by Renderer::render with the diff slice produced by Buffer::diff.

Source

fn flush(&mut self)

Flush buffered output to the terminal. No-op for headless.

Source

fn set_cursor(&mut self, pos: Option<(u16, u16)>)

Show the hardware cursor at pos, or hide it when pos is None.

Source

fn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>

Wait up to timeout for the next input event.

  • None timeout → block indefinitely (production) or return immediately (headless — see the determinism note below).
  • Returns None on timeout or when the queue is empty.

Headless never blocks — it pops the next queued event or returns None immediately, ignoring the timeout value. This is the headless determinism contract: test code injects events and drives the loop synchronously without wall-clock waits.

§Turbo Vision heritage

There is deliberately no app-level getEvent override / event-source injection seam (C++ TProgram::getEvent). For periodic work use the timer queue (Event::Timer) or crate::app::Program::set_on_idle; to feed synthetic input in tests, push onto the headless backend’s event queue.

Source

fn set_clipboard(&mut self, text: &str) -> bool

Write text to the system clipboard.

Returns false when the implementation fell back to an internal buffer (no native clipboard took the text). The caller can treat a false return as “clipboard unavailable but the string is stored internally and can be retrieved via get_clipboard”. Native first, internal only on failure. The production impl runs the full fallback chain (native → OSC 52 emit → internal — see backend::clipboard); headless is a plain internal string by design (the test fake).

Source

fn get_clipboard(&mut self) -> Option<String>

Read the clipboard: native clipboard first, else the internal buffer, else None.

Provided Methods§

Source

fn set_caret_size(&mut self, _size: u8)

Set the shape of the visible caret. size is the percentage of the character cell the caret fills, 1..=100: CARET_NORMAL (the normal caret) or CARET_INSERT (the whole cell). Called by Renderer::render each frame in which the caret is shown, after set_cursor; hiding the caret is set_cursor(None). The default does nothing, for backends that cannot change the caret shape.

The CrosstermBackend shows CARET_INSERT as a blinking block and keeps the terminal’s own caret shape for every other size (as the original’s ncurses display does), and restores the terminal’s shape on exit and suspend.

§Turbo Vision heritage

Ports THardwareInfo::setCaretSize (hardware.cpp). A size of 0 (caret hidden) is carried by set_cursor(None) instead.

Source

fn get_primary(&mut self) -> Option<String>

Read the X11/Wayland PRIMARY selection — what a middle-click pastes.

PRIMARY is a display-server concept, so this has one rung: the native clipboard. There is no internal-buffer fallback and no OSC 52 — with no display (the SSH shape) the honest answer is None, and a middle-click paste is simply inert. Serving the in-app buffer instead would paste stale text the user never selected.

§Turbo Vision heritage

tvision-rs extension: no Turbo Vision counterpart. magiblot’s TClipboard reads only the CLIPBOARD selection.

Defaulted to None so an existing implementor keeps compiling and silently gets the inert behaviour.

Source

fn set_primary(&mut self, _text: &str) -> bool

Take ownership of the PRIMARY selection and serve text from it, so another X client can middle-click-paste what the user selected here.

Returns false when there is no PRIMARY selection to own (no display, or a platform without one). Same single-rung rule as get_primary: the internal buffer is never written, because it backs CLIPBOARD and must not be shadowed by a selection the user merely swept with the mouse.

§Turbo Vision heritage

tvision-rs extension: no Turbo Vision counterpart.

Source

fn suspend(&mut self)

Suspend the terminal: leave alt-screen and restore normal terminal mode.

Called by the event loop immediately before the process is suspended (e.g. SIGTSTP on Unix, or the DOS-shell command on any platform). A correct implementation tears down raw mode and the alternate screen so the shell that takes over sees a clean terminal.

The production CrosstermBackend executes crossterm’s LeaveAlternateScreen + DisableMouseCapture + disable_raw_mode sequence. The HeadlessBackend is a no-op by design (no real terminal to tear down).

Custom backend implementors must pair this with resume: every suspend call will be followed by exactly one resume call when the process is brought back to the foreground.

§Turbo Vision heritage

Stands in for TApplication::suspend (tapplica.cpp), which called TSystemError::suspend, TEventQueue::suspend, and TScreen::suspend in sequence. The Rust port collapses all three subsystem calls into this single trait method on the Backend.

Source

fn resume(&mut self)

Resume the terminal: re-enter alt-screen, raw mode, and mouse capture.

Called by the event loop immediately after the process returns to the foreground following a suspend. A correct implementation restores the full terminal state so the next draw cycle re-paints the TUI correctly.

The production CrosstermBackend executes crossterm’s enable_raw_mode + EnterAlternateScreen + EnableMouseCapture sequence, followed by a full redraw. The HeadlessBackend is a no-op.

§Turbo Vision heritage

Stands in for TApplication::resume (tapplica.cpp), which called TScreen::resume, TEventQueue::resume, and TSystemError::resume in sequence.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§