Module event

Available on crate features dep_crossterm and std only.

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 and Focus Events

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

Examples

Blocking read:

#![cfg(feature = "bracketed-paste")]
use crossterm::{
    event::{
        read, DisableBracketedPaste, DisableFocusChange, DisableMouseCapture, EnableBracketedPaste,
        EnableFocusChange, EnableMouseCapture, Event,
    },
    execute,
};

fn print_events() -> std::io::Result<()> {
    execute!(
         std::io::stdout(),
         EnableBracketedPaste,
         EnableFocusChange,
         EnableMouseCapture
    )?;
    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),
        }
    }
    execute!(
        std::io::stdout(),
        DisableBracketedPaste,
        DisableFocusChange,
        DisableMouseCapture
    )?;
    Ok(())
}

Non-blocking read:

#![cfg(feature = "bracketed-paste")]
use std::{time::Duration, io};

use crossterm::{
    event::{
        poll, read, DisableBracketedPaste, DisableFocusChange, DisableMouseCapture,
        EnableBracketedPaste, EnableFocusChange, EnableMouseCapture, Event,
    },
    execute,
};

fn print_events() -> io::Result<()> {
    execute!(
         std::io::stdout(),
         EnableBracketedPaste,
         EnableFocusChange,
         EnableMouseCapture
    )?;
    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
        }
    }
    execute!(
        std::io::stdout(),
        DisableBracketedPaste,
        DisableFocusChange,
        DisableMouseCapture
    )?;
    Ok(())
}

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

Structs

DisableBracketedPaste

A command that disables bracketed paste mode.

DisableFocusChange

A command that disables focus event emission.

DisableMouseCapture

A command that disables mouse event capturing.

EnableBracketedPaste

A command that enables bracketed paste mode.

EnableFocusChange

A command that enables focus event emission.

EnableMouseCapture

A command that enables mouse event capturing.

KeyEvent

Represents a key event.

KeyEventState

Represents extra state about the key event.

KeyModifiers

Represents key modifiers (shift, control, alt, etc.).

KeyboardEnhancementFlags

Represents special flags that tell compatible terminals to add extra information to keyboard events.

MouseEvent

Represents a mouse event.

PopKeyboardEnhancementFlags

A command that disables extra kinds of keyboard events.

PushKeyboardEnhancementFlags

A command that enables the kitty keyboard protocol, which adds extra information to keyboard events and removes ambiguity for modifier keys.

Enums

Event

Represents an event.

KeyCode

Represents a key.

KeyEventKind

Represents a keyboard event kind.

MediaKeyCode

Represents a media key (as part of KeyCode::Media).

ModifierKeyCode

Represents a modifier key (as part of KeyCode::Modifier).

MouseButton

Represents a mouse button.

MouseEventKind

A mouse event kind.

Functions

poll

Checks if there is an Event available.

read

Reads a single Event.