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:
CrosstermBackend— production, wraps crossterm.HeadlessBackend— tests, in-memory buffer.
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§
Sourcefn size(&self) -> (u16, u16)
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.
Sourcefn draw(&mut self, content: &[(u16, u16, &Cell)])
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.
Sourcefn set_cursor(&mut self, pos: Option<(u16, u16)>)
fn set_cursor(&mut self, pos: Option<(u16, u16)>)
Show the hardware cursor at pos, or hide it when pos is None.
Sourcefn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>
fn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>
Wait up to timeout for the next input event.
Nonetimeout → block indefinitely (production) or return immediately (headless — see the determinism note below).- Returns
Noneon 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.
Sourcefn set_clipboard(&mut self, text: &str) -> bool
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).
Sourcefn get_clipboard(&mut self) -> Option<String>
fn get_clipboard(&mut self) -> Option<String>
Read the clipboard: native clipboard first, else the internal buffer,
else None.
Provided Methods§
Sourcefn set_caret_size(&mut self, _size: u8)
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.
Sourcefn get_primary(&mut self) -> Option<String>
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.
Sourcefn set_primary(&mut self, _text: &str) -> bool
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.
Sourcefn suspend(&mut self)
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.
Sourcefn resume(&mut self)
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".