pub struct CrosstermBackend { /* private fields */ }Expand description
Production backend backed by crossterm.
Crossterm backend — the production terminal implementation.
Wraps crossterm for terminal I/O behind the Backend trait.
This backend is the production path. It does not run in CI (no TTY), but it must compile and be correct/reasonable.
§Terminal lifecycle (RAII)
CrosstermBackend::new() performs the full terminal setup — raw mode,
alternate screen, mouse capture — at construction; Drop restores the
terminal (best-effort, errors ignored), so a tvision-rs program never hand-rolls
terminal setup.
Two process-global hooks (installed once, on the first construction) keep the user’s terminal usable when the program does not exit normally:
- a panic hook that restores the terminal before delegating to the previous hook — so the panic message prints on the normal screen, and a crashed TUI app leaves the shell sane;
- (unix) a signal thread that restores the terminal on
SIGINT,SIGTERM, orSIGHUPand exits with status128 + signal_number(the shell convention: 130 for SIGINT, 143 for SIGTERM, 129 for SIGHUP). Signals are handled on a dedicated thread — not in an async-signal context — so calling into crossterm is sound. (SIGKILLis uncatchable; akill -9still leaves the terminal dirty — runresetto recover.)
The restore sequence is idempotent, so Drop, the panic hook, and the signal thread may each run it without harm. Both hooks persist for the process lifetime (a later restore on an already-restored terminal is a no-op).
§Clipboard
The clipboard is the ClipboardChain (see backend::clipboard):
- Copy (
set_clipboard): OS-native via arboard (os-clipboardfeature, on by default) → OSC 52 escape sequence queued on the normal output handle (delivered by the nextflush) → internal string buffer. Returnstrueonly on the native rung (trait contract:false= fell back to internal). - Paste (
get_clipboard): OS-native → internal buffer →None. There is no OSC 52 read rung — the capability probes it needs require owning the input parser, which crossterm (not tvision-rs) owns.
SSH story: with no display, arboard init fails and the chain runs
without its native rung — but the OSC 52 emit still reaches the local
terminal’s clipboard on copy, which is exactly what a remote TUI wants.
Paste over SSH falls back to the internal buffer (copies made inside the
app) or the terminal’s own bracketed paste, which arrives as
Event::Paste.
§Color depth
ColorDepth selects which rung of the quantization ladder to use when
mapping our Color enum to crossterm colors.
§Key/event translation
crossterm::event::Event is translated to our Event enum. Only
KeyEventKind::Press and Repeat are translated; Release is ignored.
Construct with CrosstermBackend::new. Construction performs the full
terminal setup (raw mode, alternate screen, mouse capture) and Drop
restores the terminal; see Terminal lifecycle (RAII) above.
§Turbo Vision heritage
Replaces the platform driver behind TScreen / THardwareInfo and the Unix
terminal I/O of unixcon.cpp / termio.cpp with a crossterm-backed
Backend. Terminal setup that the original did in the application
constructor chain is RAII here: construction sets the terminal up, Drop tears
it down.
The production realization of the Backend seam.
tvision-rs extension: each frame is wrapped in synchronized output (DEC private mode 2026), so a terminal that supports it shows the frame whole instead of repainting it part-way. magiblot’s terminal driver does not use the mode.
Implementations§
Source§impl CrosstermBackend
impl CrosstermBackend
Sourcepub fn new() -> Result<Self>
pub fn new() -> Result<Self>
Construct a CrosstermBackend writing to stdout, performing the full
terminal setup: enable raw mode, enter the alternate screen, enable
mouse capture. Also installs the process-global restore hooks (panic
hook + unix signal thread) on first use.
On error the partial setup is rolled back before returning. The terminal is restored when the backend is dropped.
§Note
See the single-instance contract on CrosstermBackend::with_color_depth.
Sourcepub fn with_color_depth(depth: ColorDepth) -> Result<Self>
pub fn with_color_depth(depth: ColorDepth) -> Result<Self>
Construct with an explicit color depth (useful when the caller has
already detected terminal capabilities). Performs the same terminal
setup as CrosstermBackend::new.
§Note
At most one CrosstermBackend should be live per process. A second
instance re-enters the alternate screen (terminal-dependent visual
corruption); the Drop teardown is idempotent and harmless on its
own, but two instances with different lifetimes can leave the
terminal stuck in the alternate screen (the first drop restores the
terminal out from under the still-live instance).
Trait Implementations§
Source§impl Backend for CrosstermBackend
impl Backend for CrosstermBackend
Source§fn set_caret_size(&mut self, size: u8)
fn set_caret_size(&mut self, size: u8)
Map the caret size onto a terminal cursor style, as the terminal platform layer of the original does: the full-cell caret (100) is made “very visible” — here a blinking block — and every other size keeps the terminal’s own caret shape. Sent only when the size changes.
§Turbo Vision heritage
Ports NcursesDisplay::setCaretSize (ncurdisp.cpp:86-97):
curs_set(size == 100 ? 2 : 1), where 1 is the terminal’s normal
caret. ncurses’ “very visible” (terminfo cvvis) varies by terminal;
a block is the portable way to show it. DisplayBuffer::flushScreen
(dispbuff.cpp:220-221) likewise calls setCaretSize only on change.
Source§fn set_clipboard(&mut self, text: &str) -> bool
fn set_clipboard(&mut self, text: &str) -> bool
Run the copy chain (see Clipboard in the CrosstermBackend docs): native → OSC 52 →
internal. The OSC sequence is queued on the normal output handle and
delivered by the next flush (every pump iteration flushes).
Source§fn get_clipboard(&mut self) -> Option<String>
fn get_clipboard(&mut self) -> Option<String>
Run the paste chain: native → internal buffer → None.
Source§fn get_primary(&mut self) -> Option<String>
fn get_primary(&mut self) -> Option<String>
Read the PRIMARY selection — native rung only (see the trait docs).
Source§fn set_primary(&mut self, text: &str) -> bool
fn set_primary(&mut self, text: &str) -> bool
Own the PRIMARY selection — native rung only (see the trait docs).
Source§fn size(&self) -> (u16, u16)
fn size(&self) -> (u16, u16)
(cols, rows). Read moreSource§fn draw(&mut self, content: &[(u16, u16, &Cell)])
fn draw(&mut self, content: &[(u16, u16, &Cell)])
Source§fn set_cursor(&mut self, pos: Option<(u16, u16)>)
fn set_cursor(&mut self, pos: Option<(u16, u16)>)
pos, or hide it when pos is None.Source§fn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>
fn poll_event(&mut self, timeout: Option<Duration>) -> Option<Event>
timeout for the next input event. Read moreSource§impl Drop for CrosstermBackend
impl Drop for CrosstermBackend
Auto Trait Implementations§
impl !RefUnwindSafe for CrosstermBackend
impl !Send for CrosstermBackend
impl !Sync for CrosstermBackend
impl !UnwindSafe for CrosstermBackend
impl Freeze for CrosstermBackend
impl Unpin for CrosstermBackend
impl UnsafeUnpin for CrosstermBackend
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can
then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be
further downcast into Rc<ConcreteType> where ConcreteType implements Trait.§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &Any’s vtable from &Trait’s.§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot
generate &mut Any’s vtable from &mut Trait’s.