# retroglyph-crossterm - Complete API Documentation > Crossterm terminal backend for retroglyph **Version:** 0.0.0 **Authors:** Matan Lurey **License:** MIT **Repository:** https://github.com/crates-lurey-io/retroglyph **Keywords:** roguelike, terminal, grid, gamedev Generated: 2026-08-05 20:21:10 UTC Created by: [cargo-llms-txt](https://github.com/masinc/cargo-llms-txt) ## Table of Contents ### src/lib.rs - impl InstanceGuard - impl Drop for InstanceGuard - pub struct CrosstermOptions - impl CrosstermOptions - impl Default for CrosstermOptions - pub struct Crossterm - impl Crossterm - impl Crossterm - impl Drop for Crossterm - impl Crossterm - pub struct SuspendGuard - impl SuspendGuard - impl Drop for SuspendGuard - impl Output for Crossterm - impl Input for Crossterm - impl Crossterm - impl Cursor for Crossterm - pub fn from_crossterm_event - impl tests::CrosstermObserver - impl Output for tests::CrosstermObserver - impl Cursor for tests::CrosstermObserver - impl retroglyph_core::testing::conformance::Observable for tests::CrosstermObserver --- ## README.md ### retroglyph-crossterm Crossterm terminal backend for retroglyph Part of the [retroglyph](https://github.com/crates-lurey-io/retroglyph) workspace. --- ## src/lib.rs ### impl InstanceGuard ```rust impl InstanceGuard { } ``` ### impl Drop for InstanceGuard ```rust impl Drop for InstanceGuard { } ``` ### CrosstermOptions ```rust #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct CrosstermOptions { } ``` Options controlling which optional terminal protocol features [`Crossterm::with_options`] enables. All features default to `true`; mouse capture, the kitty keyboard protocol, entering the alternate screen, and raw mode all match the unconditional behavior of [`Crossterm::new`] prior to this type's introduction. Use [`CrosstermOptions::mouse_capture`], [`CrosstermOptions::kitty_protocol`], [`CrosstermOptions::focus_change`], [`CrosstermOptions::bracketed_paste`], [`CrosstermOptions::alt_screen`], or [`CrosstermOptions::raw_mode`] to disable a feature entirely, e.g. when running on a terminal (or through a pipe/CI harness/`tmux`/SSH session) where the feature is unwanted. This is also the type returned by [`Crossterm::builder`], the preferred entry point for constructing one of these: `Crossterm::builder()` reads better at a call site than `CrosstermOptions::new()` but the two are otherwise identical (`builder()` just calls `Self::new()`). This crate does not attempt to auto-detect terminal capabilities (no `TERM` parsing, no `supports_keyboard_enhancement()` query): those queries can block for seconds on terminals that never respond. `CrosstermOptions` is the opt-out mechanism instead: callers who know their environment don't support a feature can disable it explicitly. ``` use retroglyph_crossterm::Crossterm; let options = Crossterm::builder().mouse_capture(false).kitty_protocol(false); ``` ### impl CrosstermOptions ```rust impl CrosstermOptions { pub fn new() -> Self; pub fn mouse_capture(self, enabled: bool) -> Self; pub fn kitty_protocol(self, enabled: bool) -> Self; pub fn focus_change(self, enabled: bool) -> Self; pub fn bracketed_paste(self, enabled: bool) -> Self; pub fn alt_screen(self, enabled: bool) -> Self; pub fn raw_mode(self, enabled: bool) -> Self; pub fn color_support(self, color_support: retroglyph_terminal::ColorSupport) -> Self; pub fn build(self) -> Result; pub fn build_with_writer(self, writer: W) -> Result, std::io::Error>; } ``` ### impl Default for CrosstermOptions ```rust impl Default for CrosstermOptions { } ``` ### Crossterm ```rust pub struct Crossterm { } ``` A terminal rendering backend powered by `crossterm`. Generic over the content writer `W`: the sink that receives rendered cell output ([`Output::draw`]/[`Output::flush`], plus the runtime cursor/clear escapes). Defaults to `BufWriter`, matching this type's historical behavior; use [`Crossterm::with_writer`]/[`CrosstermOptions::build_with_writer`] to render to a file, a pipe, or an in-memory buffer instead (e.g. for tests that want to inspect the emitted ANSI bytes without a real TTY). See [`CrosstermOptions::build_with_writer`] for exactly which operations go through `W` versus the real terminal. #### Concurrency: only one live instance per process Raw mode, the alternate screen, and the other terminal-protocol state this backend negotiates are process-wide OS resources (there's exactly one controlling terminal, one raw-mode flag, one alternate-screen buffer), not something a `Crossterm` instance owns exclusively the way a `File` owns a file descriptor. Because of that, at most one `Crossterm` (of any `W`) may be live at a time in a process: constructing a second one while a first is still alive ([`new`], [`with_options`], [`with_writer`], and every [`CrosstermOptions::build`]/ [`CrosstermOptions::build_with_writer`] call) returns an `std::io::Error` with [`std::io::ErrorKind::ResourceBusy`] instead of proceeding: this is a documented error, not undefined behavior, and nothing is torn down or corrupted by the attempt. Sequential construct-drop-construct is fully supported: once the live instance is dropped, a new one can be constructed immediately. [`new`]: Crossterm::new [`with_options`]: Crossterm::with_options [`with_writer`]: Crossterm::with_writer ### impl Crossterm ```rust impl Crossterm { pub fn new() -> Result; pub fn builder() -> CrosstermOptions; pub fn with_options(options: CrosstermOptions) -> Result; pub fn run(app: A) -> Result<(), std::io::Error> where A: retroglyph_core::app::App; pub fn run_with(app: A, options: retroglyph_core::app::RunOptions) -> Result<(), std::io::Error> where A: retroglyph_core::app::App; } ``` ### impl Crossterm ```rust impl Crossterm { pub fn with_writer(writer: W) -> Result; pub fn writer(&self) -> &W; pub fn plain_mode(&self) -> bool; pub fn color_support(&self) -> retroglyph_terminal::ColorSupport; pub fn writer_mut(&mut self) -> &mut W; } ``` ### impl Drop for Crossterm ```rust impl Drop for Crossterm { } ``` ### impl Crossterm ```rust impl Crossterm { pub fn suspend(&mut self) -> std::io::Result>; } ``` ### SuspendGuard ```rust pub struct SuspendGuard<'a, W> { } ``` RAII guard returned by [`Crossterm::suspend`]; see that method's docs for the full contract. Borrows the suspended [`Crossterm`] mutably for its whole lifetime, so no other method on it can be called (accidentally drawing, polling, or moving the cursor) while the real terminal is handed back to the OS/shell. ### impl SuspendGuard ```rust impl SuspendGuard { pub fn resume(self) -> std::io::Result<()>; } ``` ### impl Drop for SuspendGuard ```rust impl Drop for SuspendGuard { } ``` ### impl Output for Crossterm ```rust impl Output for Crossterm { } ``` ### impl Input for Crossterm ```rust impl Input for Crossterm { } ``` ### impl Crossterm ```rust impl Crossterm { pub fn set_title(&mut self, title: &str) -> std::io::Result<()>; pub fn ring_bell(&mut self) -> std::io::Result<()>; } ``` ### impl Cursor for Crossterm ```rust impl Cursor for Crossterm { } ``` ### from_crossterm_event ```rust pub fn from_crossterm_event(event: crossterm::event::Event) -> Option ``` ### impl CrosstermObserver ```rust impl CrosstermObserver { } ``` ### impl Output for CrosstermObserver ```rust impl Output for CrosstermObserver { } ``` ### impl Cursor for CrosstermObserver ```rust impl Cursor for CrosstermObserver { } ``` ### impl retroglyph_core::testing::conformance::Observable for CrosstermObserver ```rust impl retroglyph_core::testing::conformance::Observable for CrosstermObserver { } ```