Struct crossterm::TerminalInput

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

Allows you to preform actions with the < option >.

Features:

• features

Check /examples/ in the library for more specific examples.

Remarks

When you want to use '< name >' on 'alternate screen' use the 'crossterm_screen' crate. Allows you to read user input.

Features:

• Read character
• Read line
• Read async
• Read async until
• Wait for key event (terminal pause)

Check /examples/ in the library for more specific examples.

Remarks

When you want to use 'input' on 'alternate screen' use the 'crossterm_screen' crate.

Methods

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.

Remarks

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'.

You should checkout the 'crossterm_screen' crate for more information about this.

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, Error>

Read one line from the user input.

Remark

This function is not work when raw screen is turned on. When you do want to read a line in raw mode please, checkout read_async or read_async_until. Not sure what 'raw mode' is, checkout the 'crossterm_screen' crate.

Example

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, Error>

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),
  }

Important traits for AsyncReader

impl Read for AsyncReader

pub fn read_async(&self) -> AsyncReader

Read the input asynchronously from the user.

Remarks

• This call will not block the current thread. A thread will be fired to read input, on unix systems from TTY and on windows systems with '_getwch' and '_getwche'.
• Requires 'raw screen to be enabled'. Not sure what this is, please checkout the 'crossterm_screen' crate.

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

Important traits for AsyncReader

impl Read for AsyncReader

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.

Remarks

• This call will not block the current thread. A thread will be fired to read input, on unix systems from TTY and on windows systems with '_getwch' and '_getwche'.
• Requires 'raw screen to be enabled'. Not sure what this is, please checkout the 'crossterm_screen' crate.
• Thread is automatically destroyed when the 'delimiter' 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(&self, key_event: KeyEvent)

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

Remark

• Requires 'raw screen to be enabled'. Not sure what this is, please checkout the 'crossterm_screen' crate.

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

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