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 ;
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:
[]
= "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:
| Function | Returns 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 ;
use ;
loop
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 ;
// Type an uppercase H by holding the left Shift key while tapping H.
let shift_pressed = press;
let h_tapped = tap;
let shift_released = release;
let i_tapped = tap;
let enter_tapped = tap;
if !
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 ;
tap;
Supported keys
The Key enum contains:
- Letters:
AthroughZ - Number-row keys:
Num0throughNum9 - Function keys:
F1throughF24 - 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:
Numpad0throughNumpad9and 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 ;
if down
Use a side-specific variant when the distinction matters:
use ;
if down
if down
The same pattern is available for Control and Alt:
| Either side | Left side | Right side |
|---|---|---|
Shift |
LeftShift |
RightShift |
Control |
LeftControl |
RightControl |
Alt |
LeftAlt |
RightAlt |
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 keyboard;
if !type_text
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 ;
if pressed
if down
if 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 mouse;
if scroll_delta.is_none
loop
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 mouse;
let = position;
println!;
if let Some = try_position
println!;
println!;
if !move_to
move_by;
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 ;
click;
double_click;
clicks;
press;
release;
scroll; // Three steps up.
scroll; // Three steps down.
scroll_horizontal; // Two steps right.
scroll_horizontal; // 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
| Keyboard | Purpose |
|---|---|
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 |
| Mouse | Purpose |
|---|---|
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.