Struct CrosstermOptions 

pub struct CrosstermOptions { /* private fields */ }

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

Implementations

impl CrosstermOptions

pub fn new() -> Self

Creates a new set of options with every feature enabled.

pub const fn mouse_capture(self, enabled: bool) -> Self

Sets whether to enable mouse capture (crossterm::event::EnableMouseCapture).

pub const fn kitty_protocol(self, enabled: bool) -> Self

Sets whether to push the kitty keyboard protocol’s enhancement flags (crossterm::event::PushKeyboardEnhancementFlags).

pub const fn focus_change(self, enabled: bool) -> Self

Sets whether to report focus gained/lost as [Event::FocusGained]/[Event::FocusLost] (crossterm::event::EnableFocusChange).

See the crate-level “Focus and lifecycle events” docs for the pause/resume contract this implies (e.g. on Wayland, where a terminal can lose and regain focus independent of any resize).

pub const fn bracketed_paste(self, enabled: bool) -> Self

Sets whether to report bracketed paste as [Event::Paste] (crossterm::event::EnableBracketedPaste).

pub const fn alt_screen(self, enabled: bool) -> Self

Sets whether to enter the alternate screen (crossterm::terminal::EnterAlternateScreen).

Disabling this keeps rendering on the caller’s normal scrollback buffer instead of switching to a dedicated full-screen surface; on exit, Crossterm only leaves the alternate screen (LeaveAlternateScreen) if it entered it, so disabling this doesn’t risk leaving the caller’s real terminal buffer in an unexpected state.

pub const fn raw_mode(self, enabled: bool) -> Self

Sets whether to enable raw mode (crossterm::terminal::enable_raw_mode).

Disabling this leaves the terminal in cooked mode, so the OS/shell keep handling line buffering, echo, and signal-generating keys (Ctrl-C, Ctrl-Z) itself instead of forwarding every keystroke as an [Event::Key]. Restore only disables raw mode if this backend is the one that enabled it.

pub const fn color_support(self, color_support: ColorSupport) -> Self

Overrides the ColorSupport level, skipping this crate’s own $NO_COLOR/$TERM auto-detection (see Crossterm::color_support for the auto-detected default and how it’s chosen). Use this when a caller knows the receiving terminal’s actual color depth (or wants to force it) rather than trusting the environment.

pub fn build(self) -> Result<Crossterm, Error>

Builds the Crossterm backend with these options, rendering to standard output.

Equivalent to Crossterm::with_options; this is the terminal step of the Crossterm::builder().<options>().build() chain started by Crossterm::builder. Use build_with_writer to render to a different sink (a file, a pipe, an in-memory buffer for tests) instead of stdout.

Errors

Returns an std::io::Error if raw mode or terminal commands fail. Also returns an std::io::Error with std::io::ErrorKind::ResourceBusy if another Crossterm instance is already live in this process: see the concurrency contract documented on Crossterm.

pub fn build_with_writer<W: Write>( self, writer: W, ) -> Result<Crossterm<W>, Error>

Builds the Crossterm backend with these options, rendering to writer instead of stdout.

writer only receives the rendered cell content ([Output::draw]/[Output::flush] output, plus the runtime [Output::clear]/[Cursor::set_cursor_visible]/ [Cursor::set_cursor_position] escapes). Terminal-protocol setup/teardown (raw mode, the alternate screen, the initial cursor hide, mouse capture, focus-change reporting, bracketed paste, and the kitty keyboard protocol) always targets the real process stdout regardless of writer, since those are properties of the actual controlling terminal, not of an arbitrary byte sink. Callers rendering to a non-terminal writer (a file, a pipe, an in-memory buffer) should disable the features they don’t want touching the real terminal via CrosstermOptions::raw_mode, CrosstermOptions::alt_screen, CrosstermOptions::mouse_capture, etc.

Errors

Returns an std::io::Error if raw mode or terminal commands fail. Also returns an std::io::Error with std::io::ErrorKind::ResourceBusy if another Crossterm instance is already live in this process: see the concurrency contract documented on Crossterm.

Trait Implementations

impl Clone for CrosstermOptions

fn clone(&self) -> CrosstermOptions

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CrosstermOptions

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for CrosstermOptions

fn default() -> Self

Every feature enabled; matches Crossterm::new’s historical behavior. color_support defaults to None (auto-detect from the environment at build time; see CrosstermOptions::color_support).

impl PartialEq for CrosstermOptions

fn eq(&self, other: &CrosstermOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for CrosstermOptions

impl Eq for CrosstermOptions

impl StructuralPartialEq for CrosstermOptions