Module crossterm::event

Expand description

A module to read events.

Event

The event module provides the functionality to read keyboard, mouse and terminal resize events.

The read function returns an Event immediately (if available) or blocks until an Event is available.
The poll function allows you to check if there is or isn’t an Event available within the given period of time. In other words - if subsequent call to the read function will block or not.

It’s not allowed to call these functions from different threads or combine them with the EventStream. You’re allowed to either:

use the read & poll functions on any, but same, thread
or the EventStream.

Make sure to enable raw mode in order for keyboard events to work properly

Mouse Events

Mouse events are not enabled by default. You have to enable them with the EnableMouseCapture command. See Command API for more information.

Examples

Blocking read:

use crossterm::event::{read, Event};

fn print_events() -> crossterm::Result<()> {
    loop {
        // `read()` blocks until an `Event` is available
        match read()? {
            Event::FocusGained => println!("FocusGained"),
            Event::FocusLost => println!("FocusLost"),
            Event::Key(event) => println!("{:?}", event),
            Event::Mouse(event) => println!("{:?}", event),
            #[cfg(feature = "bracketed-paste")]
            Event::Paste(data) => println!("{:?}", data),
            Event::Resize(width, height) => println!("New size {}x{}", width, height),
        }
    }
    Ok(())
}

Non-blocking read:

use std::time::Duration;

use crossterm::event::{poll, read, Event};

fn print_events() -> crossterm::Result<()> {
    loop {
        // `poll()` waits for an `Event` for a given time period
        if poll(Duration::from_millis(500))? {
            // It's guaranteed that the `read()` won't block when the `poll()`
            // function returns `true`
            match read()? {
                Event::FocusGained => println!("FocusGained"),
                Event::FocusLost => println!("FocusLost"),
                Event::Key(event) => println!("{:?}", event),
                Event::Mouse(event) => println!("{:?}", event),
                #[cfg(feature = "bracketed-paste")]
                Event::Paste(data) => println!("Pasted {:?}", data),
                Event::Resize(width, height) => println!("New size {}x{}", width, height),
            }
        } else {
            // Timeout expired and no `Event` is available
        }
    }
    Ok(())
}