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() -> std::io::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, io};

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

fn print_events() -> io::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(())
}

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.