inputkit 0.1.0

Keyboard and mouse input automation for Windows
Documentation
//! Mouse detection and control.

use crate::{MouseButton, platform};

/// Mouse-wheel movement accumulated since the previous call to
/// [`scroll_delta`]. Values use Windows wheel-delta units: 120 normally
/// represents one wheel notch.
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ScrollDelta {
    /// Positive values move right; negative values move left.
    pub horizontal: i32,
    /// Positive values move up; negative values move down.
    pub vertical: i32,
}

impl ScrollDelta {
    /// Returns whether the wheel moved upward.
    pub const fn is_up(self) -> bool {
        self.vertical > 0
    }

    /// Returns whether the wheel moved downward.
    pub const fn is_down(self) -> bool {
        self.vertical < 0
    }

    /// Returns whether the wheel moved left.
    pub const fn is_left(self) -> bool {
        self.horizontal < 0
    }

    /// Returns whether the wheel moved right.
    pub const fn is_right(self) -> bool {
        self.horizontal > 0
    }
}

/// Returns `true` once when `button` changes from up to down.
pub fn pressed(button: MouseButton) -> bool {
    platform::mouse_pressed(button)
}

/// Returns `true` while `button` is held down.
pub fn down(button: MouseButton) -> bool {
    platform::mouse_down(button)
}

/// Returns `true` once when `button` changes from down to up.
pub fn released(button: MouseButton) -> bool {
    platform::mouse_released(button)
}

/// Returns the cursor position in screen coordinates.
/// Returns `(0, 0)` if Windows cannot read the cursor position.
pub fn position() -> (i32, i32) {
    try_position().unwrap_or((0, 0))
}

/// Returns the cursor position in screen coordinates, or `None` if Windows
/// cannot read it.
pub fn try_position() -> Option<(i32, i32)> {
    platform::cursor_position()
}

/// Returns the cursor's horizontal screen coordinate.
pub fn x() -> i32 {
    position().0
}

/// Returns the cursor's vertical screen coordinate.
pub fn y() -> i32 {
    position().1
}

/// Moves the cursor to the given screen coordinates.
/// Returns whether Windows moved the cursor.
pub fn move_to(x: i32, y: i32) -> bool {
    platform::set_cursor_position(x, y)
}

/// Moves the cursor by a number of screen pixels relative to its current
/// position. Returns whether Windows moved the cursor.
pub fn move_by(x: i32, y: i32) -> bool {
    let Some((current_x, current_y)) = try_position() else {
        return false;
    };
    move_to(current_x.saturating_add(x), current_y.saturating_add(y))
}

/// Presses and releases `button` once.
/// Returns whether Windows accepted both input events.
pub fn click(button: MouseButton) -> bool {
    platform::click_mouse(button, 1)
}

/// Presses and releases `button` twice.
/// Returns whether Windows accepted all four input events.
pub fn double_click(button: MouseButton) -> bool {
    platform::click_mouse(button, 2)
}

/// Presses and releases `button` `count` times.
/// Returns whether Windows accepted every generated event.
pub fn clicks(button: MouseButton, count: usize) -> bool {
    platform::click_mouse(button, count)
}

/// Holds `button` down.
/// Returns whether Windows accepted the input.
pub fn press(button: MouseButton) -> bool {
    platform::send_mouse_button(button, false)
}

/// Releases `button`.
/// Returns whether Windows accepted the input.
pub fn release(button: MouseButton) -> bool {
    platform::send_mouse_button(button, true)
}

/// Scrolls vertically by a number of wheel steps.
/// Positive values scroll up and negative values scroll down. Returns whether
/// Windows accepted the input.
pub fn scroll(steps: i32) -> bool {
    platform::scroll_mouse_vertical(steps)
}

/// Scrolls horizontally by a number of wheel steps.
/// Positive values scroll right and negative values scroll left. Returns
/// whether Windows accepted the input.
pub fn scroll_horizontal(steps: i32) -> bool {
    platform::scroll_mouse_horizontal(steps)
}

/// Returns global wheel movement since the previous call.
///
/// The first call starts a background Windows mouse hook. It returns `None`
/// if Windows could not install that hook. Otherwise, it returns both axes in
/// raw wheel-delta units; 120 normally represents one wheel notch. A zeroed
/// value means no wheel movement occurred since the previous call.
pub fn scroll_delta() -> Option<ScrollDelta> {
    platform::take_scroll_delta().map(|(horizontal, vertical)| ScrollDelta {
        horizontal,
        vertical,
    })
}

#[cfg(test)]
mod tests {
    use super::ScrollDelta;

    #[test]
    fn scroll_direction_helpers_follow_each_axis_sign() {
        let delta = ScrollDelta {
            horizontal: -40,
            vertical: 120,
        };

        assert!(delta.is_up());
        assert!(!delta.is_down());
        assert!(delta.is_left());
        assert!(!delta.is_right());
    }
}