Struct crossterm_input::TerminalInput

pub struct TerminalInput { /* fields omitted */ }

A terminal input.

Examples

// You can replace the following line with `use crossterm::...;`
// if you're using the `crossterm` crate with the `input` feature enabled.
use crossterm_input::{Result, TerminalInput, RawScreen};

fn main() -> Result<()> {
    let input = TerminalInput::new();
    // Read a single character
    let char = input.read_char()?;
    // Read a single line
    let line = input.read_line()?;

    // Make sure to enable raw screen when reading input events
    let screen = RawScreen::into_raw_mode();

    // Create async reader
    let mut async_stdin = input.read_async();

    // Create sync reader
    let mut sync_stdin = input.read_sync();

    // Enable mouse input events
    input.enable_mouse_mode()?;
    // Disable mouse input events
    input.disable_mouse_mode()
}

Methods

impl TerminalInput

pub fn new() -> TerminalInput

Creates a new TerminalInput.

pub fn read_line(&self) -> Result<String>

Reads one line from the user input and strips the new line character(s).

This function does not work when the raw mode is enabled (see the crossterm_screen crate documentation to learn more). You should use the read_async, read_until_async or read_sync method if the raw mode is enabled.

Examples

let input = crossterm_input::input();
match input.read_line() {
    Ok(s) => println!("string typed: {}", s),
    Err(e) => println!("error: {}", e),
}

pub fn read_char(&self) -> Result<char>

Reads one character from the user input.

Examples

let input = crossterm_input::input();
match input.read_char() {
    Ok(c) => println!("character pressed: {}", c),
    Err(e) => println!("error: {}", e),
}

Important traits for AsyncReader

impl Iterator for AsyncReader type Item = InputEvent;

pub fn read_async(&self) -> AsyncReader

Creates a new AsyncReader allowing to read the input asynchronously (not blocking).

If you want a blocking, or less resource consuming read, see the read_sync method.

Notes

• It requires enabled raw mode (see the crossterm_screen crate documentation to learn more).
• A thread is spawned to read the input.
• The reading thread is cleaned up when you drop the AsyncReader.

Examples

use std::{thread, time::Duration};
use crossterm_input::input;

let mut async_stdin = input().read_async();

loop {
    if let Some(key_event) = async_stdin.next() {
        /* Check which event occurred here */
    }

    thread::sleep(Duration::from_millis(50));
}

Important traits for AsyncReader

impl Iterator for AsyncReader type Item = InputEvent;

pub fn read_until_async(&self, delimiter: u8) -> AsyncReader

Creates a new AsyncReader allowing to read the input asynchronously (not blocking) until the given delimiter.

It behaves in the same way as the read_async method, but it stops reading when the delimiter is hit.

Notes

• It requires enabled raw mode (see the crossterm_screen crate documentation to learn more).
• A thread is spawned to read the input.
• The reading thread is cleaned up when you drop the AsyncReader.

Examples

use std::{thread, time::Duration};

let mut async_stdin = crossterm_input::input().read_until_async(b'x');

loop {
    if let Some(key_event) = async_stdin.next() {
        /* Check which event occurred here */
    }

    thread::sleep(Duration::from_millis(50));
}

Important traits for SyncReader

impl Iterator for SyncReader type Item = InputEvent;

pub fn read_sync(&self) -> SyncReader

Creates a new SyncReader allowing to read the input synchronously (blocking).

It's less resource hungry when compared to the read_async method, because it doesn't spawn any reading threads.

Examples

use std::{thread, time::Duration};

let mut sync_stdin = crossterm_input::input().read_sync();

loop {
    if let Some(key_event) = sync_stdin.next() {
        /* Check which event occurred here */
    }
}

pub fn enable_mouse_mode(&self) -> Result<()>

Enables mouse events.

Mouse events will be produced by the AsyncReader/SyncReader.

pub fn disable_mouse_mode(&self) -> Result<()>

Disables mouse events.

Mouse events wont be produced by the AsyncReader/SyncReader.