UI Input State

A library for stateful tracking of current input state.

Frame-oriented input state built on ui-events.

This crate provides simple state containers to make input handling easier in immediate-mode or frame-based UIs. Instead of reacting to each event individually, you feed pointer and keyboard events into the state, query the current and per-frame information during your update, and then call [InputState::clear_frame] at the end of the frame.

What it provides:

[PrimaryPointerState]: current pointer state, coalesced and predicted motion, per-frame button transitions, and helpers for motion in physical/logical units.
[KeyboardState]: current modifiers, keys down, and per-frame key transitions.
[InputState]: a convenience container bundling both states and a per-frame clear.

Typical lifecycle per frame:

Receive backend events and convert them to ui-events types.
Update PrimaryPointerState and KeyboardState with the events.
Read state during your UI update (e.g. check just pressed, motion, etc.).
Call [InputState::clear_frame] before the next frame.

Example (sketch):

use ui_input_state::{InputState, PrimaryPointerState, KeyboardState};
use ui_events::pointer::PointerEvent;
use ui_events::keyboard::KeyboardEvent;

let mut input = InputState::default();

// 1-2) In your event loop, feed events into state
fn on_pointer_event(input: &mut InputState, e: PointerEvent) {
    input.primary_pointer.process_pointer_event(e);
}
fn on_keyboard_event(input: &mut InputState, e: KeyboardEvent) {
    input.keyboard.process_keyboard_event(e);
}

// 3) During your update pass, read state
fn update(input: &InputState) {
    if input.primary_pointer.is_primary_just_pressed() {
        // Begin a drag, for example
    }
    if input.keyboard.key_str_just_pressed("z") && input.keyboard.modifiers.ctrl() {
        // Ctrl+Z
    }
}

// 4) At the end of the frame, clear per-frame transitions
fn end_frame(input: &mut InputState) { input.clear_frame(); }

Coordinates and units

Pointer positions are stored in physical pixels with a Y-down axis, as in ui-events. Use [PrimaryPointerState::current_logical_position] and [PrimaryPointerState::logical_motion] to work in logical units.

Features

std (enabled by default): Use the Rust standard library.
libm: Enable ui-events/libm transitively for no_std environments.

Minimum supported Rust Version (MSRV)

This version of UI Input State has been verified to compile with Rust 1.85 and later.

Future versions of UI Input State might increase the Rust version requirement. It will not be treated as a breaking change and as such can even happen with small patch releases.

As time has passed, some of UI Input State's dependencies could have released versions with a higher Rust requirement. If you encounter a compilation issue due to a dependency and don't want to upgrade your Rust toolchain, then you could downgrade the dependency.

# Use the problematic dependency's name and version
cargo update -p package_name --precise 0.1.1

Community

Discussion of UI Input State development happens in the Linebender Zulip, specifically the #general channel. All public content can be read without logging in.

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Contributions are welcome by pull request. The Rust code of conduct applies. Please feel free to add your name to the AUTHORS file in any substantive pull request.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

ui-input-state 0.3.0