Trait InputProvider

pub trait InputProvider: Send + Sync {
    // Required methods
    fn pointer_move(&self, to: Point) -> Result<(), Error>;
    fn pointer_down(&self, button: MouseButton) -> Result<(), Error>;
    fn pointer_up(&self, button: MouseButton) -> Result<(), Error>;
    fn pointer_click(
        &self,
        at: Point,
        button: MouseButton,
        count: u32,
    ) -> Result<(), Error>;
    fn pointer_scroll(&self, at: Point, delta: ScrollDelta) -> Result<(), Error>;
    fn key_down(&self, key: &Key) -> Result<(), Error>;
    fn key_up(&self, key: &Key) -> Result<(), Error>;
    fn type_text(&self, text: &str) -> Result<(), Error>;

    // Provided method
    fn pointer_drag(
        &self,
        from: Point,
        to: Point,
        button: MouseButton,
        duration: Duration,
    ) -> Result<(), Error> { ... }
}

Expand description

Platform backend trait for synthesised user input.

Implementors generate OS-level pointer and keyboard events. Most methods correspond to a single low-level operation; a few (marked “provided”) are synthesised by default but may be overridden when a platform has a higher-fidelity primitive.

This trait is intentionally separate from [crate::Provider]. A backend that only knows how to read the accessibility tree should not implement InputProvider, and vice versa. Crates may implement both for the same platform but the two surfaces never call into each other.

§Errors

Implementations should return:

Error::PermissionDenied when the OS denies the synthesis permission.
Error::Unsupported when the operation has no platform implementation (e.g. pointer warp on a session that disallows it). Do not silently degrade — surface the missing capability per Tenet 1.
Error::Platform for raw OS failures.

Required Methods§

fn pointer_move(&self, to: Point) -> Result<(), Error>

Move the pointer to to without pressing any buttons.

fn pointer_down(&self, button: MouseButton) -> Result<(), Error>

Press button at the current pointer location (no release).

fn pointer_up(&self, button: MouseButton) -> Result<(), Error>

Release button at the current pointer location.

fn pointer_click( &self, at: Point, button: MouseButton, count: u32, ) -> Result<(), Error>

Click button at at, repeated count times. The backend is responsible for honouring the OS double-click interval when count > 1 and for any platform-specific click-state bookkeeping (e.g. kCGMouseEventClickState on macOS).

fn pointer_scroll(&self, at: Point, delta: ScrollDelta) -> Result<(), Error>

Scroll by delta ticks at at.

fn key_down(&self, key: &Key) -> Result<(), Error>

Press key (no release). Use key_up to release.

Modifiers are just keys: hold Key::Shift via key_down(&Key::Shift).

fn key_up(&self, key: &Key) -> Result<(), Error>

Release key.

fn type_text(&self, text: &str) -> Result<(), Error>

Type text as literal user input.

Backends should prefer the OS’s text-input path (with IME support) over synthesising individual key presses where possible.

Provided Methods§

fn pointer_drag( &self, from: Point, to: Point, button: MouseButton, duration: Duration, ) -> Result<(), Error>

Press button at from, interpolate to to over duration, release.

The default synthesis posts pointer_down → a series of pointer_move calls (≈60 Hz cadence) → pointer_up. Backends should override to emit platform-specific drag events where they differ from move events — on macOS, drag-and-drop source apps filter for kCGEventLeftMouseDragged, which is distinct from kCGEventMouseMoved. On Windows and X11 the default synthesis is usually sufficient.