# 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.
```rust,no_run
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:
```powershell
cargo add inputkit
```
Or add it directly to `Cargo.toml`:
```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:
| `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:
```rust,no_run
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:
```rust,no_run
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:
```rust,no_run
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:
```rust,no_run
use inputkit::{keyboard, Key};
if keyboard::down(Key::Shift) {
println!("Either Shift key is held");
}
```
Use a side-specific variant when the distinction matters:
```rust,no_run
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`:
| `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:
```rust,no_run
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:
```rust,no_run
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:
```rust,no_run
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.
```rust,no_run
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
```rust,no_run
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
| `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::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:
```text
examples/
├── detect_keyboard.rs
├── detect_mouse.rs
├── move_mouse.rs
└── keyboard_control.rs
```
Run one with Cargo on Windows:
```powershell
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.