Module crossterm::event

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::Key(event) => println!("{:?}", event),
            Event::Mouse(event) => println!("{:?}", event),
            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::Key(event) => println!("{:?}", event),
                Event::Mouse(event) => println!("{:?}", event),
                Event::Resize(width, height) => println!("New size {}x{}", width, height),
            }
        } else {
            // Timeout expired and no `Event` is available
        }
    }
    Ok(())
}

Check the examples folder for more of them (event-*).

Structs

DisableMouseCapture	A command that disables mouse event capturing.
EnableMouseCapture	A command that enables mouse event capturing.
EventStream	A stream of Result<Event>.
KeyEvent	Represents a key event.
KeyModifiers	Represents key modifiers (shift, control, alt).
MouseEvent	Represents a mouse event.

Enums

Event	Represents an event.
KeyCode	Represents a key.
MouseButton	Represents a mouse button.
MouseEventKind	A mouse event kind.

Functions

poll	Checks if there is an Event available.
read	Reads a single Event.