Guide API
Skip to main content

CrosstermBackend

Struct CrosstermBackend 

Source
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, or SIGHUP and exits with status 128 + 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. (SIGKILL is uncatchable; a kill -9 still leaves the terminal dirty — run reset to 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-clipboard feature, on by default) → OSC 52 escape sequence queued on the normal output handle (delivered by the next flush) → internal string buffer. Returns true only 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

Source

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.

Source

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

Source§

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

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>

Run the paste chain: native → internal buffer → None.

Source§

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

Own the PRIMARY selection — native rung only (see the trait docs).

Source§

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

Live terminal dimensions in cells, returned as (cols, rows). Read more
Source§

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

Apply changed cells to the screen. Read more
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. Read more
Source§

fn suspend(&mut self)

Suspend the terminal: leave alt-screen and restore normal terminal mode. Read more
Source§

fn resume(&mut self)

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

impl Drop for CrosstermBackend

Source§

fn drop(&mut self)

Restore the terminal (best-effort; errors during drop are ignored).

Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert 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>

Convert 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)

Convert &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)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.