Struct crossterm::TerminalInput

pub struct TerminalInput<'stdout> { /* private fields */ }

Struct that stores a platform-specific implementation for input related actions.

Check /examples/input the examples folder on github for more info.

extern crate crossterm;
use self::crossterm::Screen;
use self::crossterm::input;

let input = input();
let result = input.read_line();
let pressed_char = input.read_char();

!! Take note when using input with raw mode you should use the Screen type. !!

let screen = Screen::new(true);
let input = crossterm::input::from_screen(&screen);

When you want to use ‘input’ related actions on ‘alternate screen’ use the Screen type instead, and pass it to the terminal::from_screen() function. By doing that terminal actions will be performed on the alternate screen.

Implementations

impl<'stdout> TerminalInput<'stdout>

pub fn new() -> TerminalInput<'stdout>

Create a new instance of TerminalInput whereon input related actions could be preformed.

pub fn from_output(
    stdout: &'stdout Arc<TerminalOutput>
) -> TerminalInput<'stdout>

Create a new instance of TerminalInput whereon input related actions could be preformed.

Note

Use this function when you want your terminal to operate with a specific output. This could be useful when you have a screen which is in ‘alternate mode’. And you want your actions from the TerminalInput, created by this function, to operate on the ‘alternate screen’.

Example

let screen = Screen::default();
if let Ok(alternate) = screen.enable_alternate_modes(false) {
   let terminal = TerminalInput::from_output(&alternate.screen.stdout);
}

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

Read one line from the user input.

Note that this function only works when rawscreen is not turned on. When you do want to read a line in raw mode please checkout read_async or read_async_until.

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

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

Read one character from the user input

let input = input();

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

pub fn read_async(&self) -> AsyncReader

Read the input asynchronously from the user.

This call will not block the current thread. Under the hood a thread is fired which will read input on unix systems from TTY and on windows systems with ‘_getwch’ and ‘_getwche’

// we need to enable raw mode otherwise the characters will be outputted by default before we are able to read them.
let screen = Screen::new(true);
let input = crossterm::input::from_screen(&screen);

let mut stdin = input.read_async().bytes();

for i in 0..100 {

    // Get the next character typed. This is None if nothing is pressed. And Some(Ok(u8 value of character))
    let a = stdin.next();

    println!("pressed key: {:?}", a);

    if let Some(Ok(b'x')) = a {
        println!("The key: `x` was pressed and program is terminated.");
        break;
    }
    // simulate some timeout so that we can see the character on the screen.
    thread::sleep(time::Duration::from_millis(50));
}

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

Read the input asynchronously until a certain character is hit.

This is the same as read_async() but stops reading when a certain character is hit.

// we need to enable raw mode otherwise the characters will be outputted by default before we are able to read them.
let screen = Screen::new(true);

// create an instance of `Crossterm` which will preform the actions on the raw screen.
let crossterm = Crossterm::from_screen(&screen);
let input = crossterm.input();
let terminal = crossterm.terminal();
let mut cursor = crossterm.cursor();

let mut stdin = input.read_until_async(b'\r').bytes();

for i in 0..100 {
    terminal.clear(ClearType::All);
    cursor.goto(1, 1);
    let a = stdin.next();

    println!("pressed key: {:?}", a);

    if let Some(Ok(b'\r')) = a {
        println!("The enter key is hit and program is not listening to input anymore.");
        break;
    }

    if let Some(Ok(b'x')) = a {
         println!("The key: x was pressed and program is terminated.");
        break;
    }

    thread::sleep(time::Duration::from_millis(100));
}

pub fn wait_until(key_event: KeyEvent)

This will prevent the current thread from continuing until the passed KeyEvent has happened.

This function will put the terminal into raw mode so that any key presses will not be shown at the screen.

use crossterm::input::{TerminalInput, KeyEvent};

fn main() {
    println!("Press 'x' to quit...");
    TerminalInput::wait_until(KeyEvent::OnKeyPress(b'x'));
}