Skip to main content

Crate inputkit

Crate inputkit 

Source
Expand description

§inputkit

inputkit provides simple keyboard and mouse detection and control for Windows. Its public API uses ordinary Rust functions and enums; all Win32 types and unsafe code stay inside the crate.

use inputkit::{keyboard, mouse, Key, MouseButton};

fn main() {
    if keyboard::pressed(Key::A) {
        println!("A pressed");
    }

    if keyboard::down(Key::Shift) {
        println!("Shift is being held");
    }

    if keyboard::released(Key::Escape) {
        println!("Escape released");
    }

if mouse::pressed(MouseButton::Left) {
    println!("Left click");
}

if let Some(wheel) = mouse::scroll_delta() {
    if wheel.is_up() {
        println!("Wheel moved up");
    }
}

    let (x, y) = mouse::position();
    println!("{x}, {y}");
}

§Requirements

  • Windows
  • Stable Rust with the 2024 edition

Linux and macOS are not supported yet. Building the crate on another operating system produces a clear compile-time error.

§Installation

Add the published crate to your application:

cargo add inputkit

Or add it directly to Cargo.toml:

[dependencies]
inputkit = "0.1"

During local development, you can instead point Cargo at this folder with inputkit = { path = "../inputkit" }.

The windows dependency and its feature selection are implementation details; applications using inputkit do not need to call Win32 APIs themselves.

§Detecting keyboard input

The three detection functions describe different parts of a key’s state:

FunctionReturns true
keyboard::pressed(key)Once when the key changes from up to down
keyboard::down(key)Every time it is called while the key is held
keyboard::released(key)Once when the key changes from down to up

Poll transition functions repeatedly so they can observe both sides of a transition:

use std::{thread, time::Duration};
use inputkit::{keyboard, Key};

loop {
    if keyboard::pressed(Key::A) {
        println!("A was pressed");
    }

    if keyboard::down(Key::Shift) {
        println!("Shift is held");
    }

    if keyboard::released(Key::A) {
        println!("A was released");
    }

    if keyboard::pressed(Key::Escape) {
        break;
    }

    thread::sleep(Duration::from_millis(10));
}

pressed and released keep independent state for every key. Repeated calls while a key remains held do not continuously report a new press. Because this is a polling API, a complete press-and-release cycle that happens between two polls cannot be observed.

The state is system-wide: the application does not need keyboard focus to detect a key.

§Controlling the keyboard

Use press to hold a key, release to let it go, and tap to perform both actions:

use inputkit::{keyboard, Key};

// Type an uppercase H by holding the left Shift key while tapping H.
let shift_pressed = keyboard::press(Key::LeftShift);
let h_tapped = keyboard::tap(Key::H);
let shift_released = keyboard::release(Key::LeftShift);

let i_tapped = keyboard::tap(Key::I);
let enter_tapped = keyboard::tap(Key::Enter);

if !(shift_pressed && h_tapped && shift_released && i_tapped && enter_tapped) {
    eprintln!("Windows did not accept every keyboard event");
}

Always pair a successful press with release. A key remains logically held until it is released.

Keyboard control functions return true when Windows accepts every requested input event. Ignoring the return value is allowed for small scripts:

use inputkit::{keyboard, Key};

keyboard::tap(Key::Space);

§Supported keys

The Key enum contains:

  • Letters: A through Z
  • Number-row keys: Num0 through Num9
  • Function keys: F1 through F24
  • Whitespace and editing: Space, Enter, Tab, Backspace, Insert, Delete
  • Modifiers: Shift, Control, Alt, plus separate left and right variants
  • Windows keys: LeftWindows, RightWindows, Menu
  • Navigation: Home, End, PageUp, PageDown, and the four arrow keys
  • Locks and system keys: CapsLock, NumLock, ScrollLock, PrintScreen, Pause, Escape
  • Numeric keypad: Numpad0 through Numpad9 and its arithmetic keys
  • Punctuation: brackets, quote, comma, period, slash, and the other common keys
  • Audio and media: volume, playback, and track controls
  • Browser controls: back, forward, refresh, stop, search, favorites, and home
  • Application controls: mail, media player, application launch keys, and sleep

Num0 through Num9 refer to the number row, not the numeric keypad. Numpad0 through Numpad9 refer specifically to the numeric keypad.

§Left and right modifiers

Use the generic modifier when either side should count:

use inputkit::{keyboard, Key};

if keyboard::down(Key::Shift) {
    println!("Either Shift key is held");
}

Use a side-specific variant when the distinction matters:

use inputkit::{keyboard, Key};

if keyboard::down(Key::LeftShift) {
    println!("Left Shift is held");
}

if keyboard::down(Key::RightShift) {
    println!("Right Shift is held");
}

The same pattern is available for Control and Alt:

Either sideLeft sideRight side
ShiftLeftShiftRightShift
ControlLeftControlRightControl
AltLeftAltRightAlt

The Windows keys use LeftWindows and RightWindows; they do not have a generic combined variant.

§Typing text

Use type_text when you want characters rather than physical key presses. It supports Unicode, including characters that are not present on the active keyboard layout:

use inputkit::keyboard;

if !keyboard::type_text("Hello, नमस्ते, Привет! 👋") {
    eprintln!("Windows did not accept all text events");
}

The focused application receives the text. Some software, especially games that read raw keyboard scan codes, may accept press, release, and tap but ignore Unicode text events.

§Detecting mouse input

Mouse buttons use the same transition semantics as keyboard keys:

use inputkit::{mouse, MouseButton};

if mouse::pressed(MouseButton::Left) {
    println!("Left button pressed");
}

if mouse::down(MouseButton::Right) {
    println!("Right button held");
}

if mouse::released(MouseButton::Middle) {
    println!("Middle button released");
}

Supported buttons are Left, Right, Middle, X1, and X2. The X buttons are the additional side buttons found on many mice.

§Detecting wheel movement

scroll_delta detects vertical and horizontal wheel movement system-wide. Its first call starts the listener; call it once before entering a polling loop so no later movement is missed:

use inputkit::mouse;

if mouse::scroll_delta().is_none() {
    eprintln!("Windows could not start wheel detection");
    return;
}

loop {
    let Some(delta) = mouse::scroll_delta() else {
        break;
    };

    if delta.is_up() {
        println!("up");
    } else if delta.is_down() {
        println!("down");
    }

    if delta.is_left() {
        println!("left");
    } else if delta.is_right() {
        println!("right");
    }
}

Each call consumes the movement accumulated since the preceding call. The values are Windows wheel-delta units: a traditional wheel notch is normally 120, while high-resolution devices may report smaller values. Generated wheel input is visible to this global listener too.

§Reading and moving the cursor

Coordinates are Windows screen coordinates. The origin (0, 0) is normally the top-left corner of the primary display. Secondary displays can have negative coordinates depending on their arrangement.

use inputkit::mouse;

let (x, y) = mouse::position();
println!("Cursor: {x}, {y}");

if let Some((x, y)) = mouse::try_position() {
    println!("Cursor lookup succeeded: {x}, {y}");
}

println!("Only x: {}", mouse::x());
println!("Only y: {}", mouse::y());

if !mouse::move_to(500, 300) {
    eprintln!("The cursor could not be moved");
}

mouse::move_by(20, -10);

position returns (0, 0) if Windows cannot read the cursor position. try_position distinguishes that failure from a real (0, 0) position. move_to and move_by return whether Windows accepted the requested position.

§Clicking and scrolling

use inputkit::{mouse, MouseButton};

mouse::click(MouseButton::Left);
mouse::double_click(MouseButton::Left);
mouse::clicks(MouseButton::Left, 3);

mouse::press(MouseButton::Right);
mouse::release(MouseButton::Right);

mouse::scroll(3);  // Three steps up.
mouse::scroll(-3); // Three steps down.
mouse::scroll_horizontal(2);  // Two steps right.
mouse::scroll_horizontal(-2); // Two steps left.

As with keyboard control, pair every mouse press with a release. Mouse control functions return true when Windows accepts every generated event.

§API overview

KeyboardPurpose
keyboard::pressed(Key)Detect a new press
keyboard::down(Key)Check whether a key is held
keyboard::released(Key)Detect a new release
keyboard::press(Key)Hold a key down
keyboard::release(Key)Release a key
keyboard::tap(Key)Press and release a key
keyboard::type_text(&str)Type arbitrary Unicode text
MousePurpose
mouse::pressed(MouseButton)Detect a new button press
mouse::down(MouseButton)Check whether a button is held
mouse::released(MouseButton)Detect a new button release
mouse::position()Read (x, y) screen coordinates
mouse::try_position()Read coordinates with explicit failure handling
mouse::x() / mouse::y()Read one cursor coordinate
mouse::move_to(x, y)Move the cursor
mouse::move_by(x, y)Move relative to the current cursor position
mouse::click(MouseButton)Click once
mouse::double_click(MouseButton)Click twice
mouse::clicks(MouseButton, count)Click any number of times
mouse::press(MouseButton)Hold a button down
mouse::release(MouseButton)Release a button
mouse::scroll(steps)Scroll vertically
mouse::scroll_horizontal(steps)Scroll horizontally
mouse::scroll_delta()Consume detected vertical/horizontal scrolling

§Examples

The repository contains four runnable examples:

examples/
├── detect_keyboard.rs
├── detect_mouse.rs
├── move_mouse.rs
└── keyboard_control.rs

Run one with Cargo on Windows:

cargo run --example detect_keyboard
cargo run --example detect_mouse
cargo run --example mouse_control
cargo run --example keyboard_control

The control examples generate real input. Focus the window that should receive the keyboard events before running keyboard_control.

§Windows behavior

Key and button detection reads the global asynchronous state exposed by Windows. Wheel detection uses a global low-level mouse hook on a background thread and starts on the first call to mouse::scroll_delta. Generated input is sent through the normal Windows input stream, so it goes to the application that would ordinarily receive keyboard or mouse input.

Windows can reject generated input across security boundaries, such as when a normal application tries to control a higher-privilege application. In that case a control function returns false. The crate does not bypass Windows security or application-level input restrictions.

Modules§

keyboard
Keyboard detection and control.
mouse
Mouse detection and control.

Enums§

Key
MouseButton
A mouse button.