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 Iterator for AsyncReader type Item = InputEvent;

pub fn read_async(&self) -> AsyncReader

Read the input asynchronously, which means that input events are gathered on the background and will be queued for you to read.

If you want a blocking, or less resource consuming read to happen use read_sync(), this will leave a way all the thread and queueing and will be a blocking read.

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

Remarks

• Readings won't be blocking calls. A thread will be fired to read input, on unix systems from TTY and on windows WinApi ReadConsoleW will be used.
• Input events read from the user will be queued on a MPSC-channel.
• The reading thread will be cleaned up when it drops.
• Requires 'raw screen to be enabled'. Not sure what this is? Please checkout the 'crossterm_screen' crate.

Examples

Please checkout the example folder in the repository.

Important traits for AsyncReader

impl Iterator for AsyncReader type Item = InputEvent;

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

Read the input asynchronously until a certain character is hit, which means that input events are gathered on the background and will be queued for you to read.

If you want a blocking, or less resource consuming read to happen use read_sync(), this will leave a way all the thread and queueing and will be a blocking read.

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

Remarks

• Readings won't be blocking calls. A thread will be fired to read input, on unix systems from TTY and on windows WinApi ReadConsoleW will be used.
• Input events read from the user will be queued on a MPSC-channel.
• The reading thread will be cleaned up when it drops.
• Requires 'raw screen to be enabled'. Not sure what this is? Please checkout the 'crossterm_screen' crate.

Examples

Please checkout the example folder in the repository.

Important traits for SyncReader

impl Iterator for SyncReader type Item = InputEvent;

pub fn read_sync(&self) -> SyncReader

Read the input synchronously from the user, which means that reading call wil be blocking ones. It also uses less resources than the AsyncReader because background thread and queues are left away.

In case you don't want the reading to block your program you could consider read_async.

Remark

• Readings will be blocking calls.

Examples

Please checkout the example folder in the repository.

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

Enable mouse events to be captured.

When enabling mouse input you will be able to capture, mouse movements, pressed buttons and locations.

Remark

• Mouse events will be send over the reader created with read_async, read_async_until, read_sync.

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

Disable mouse events to be captured.

When disabling mouse input you won't be able to capture, mouse movements, pressed buttons and locations anymore.