1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
//! Provides unified access to input devices across platforms.
//!
//! # Keyboard Inputs
//!
//! To check whether the current platform provides keyboard input, call:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Returns true if a keyboard is attached
//! input::has_keyboard_attached();
//! ```
//!
//! Nothing bad will happen if you call the keyboard functions even if `has_keyboard_
//! attached` returns false. To check the current state of specific keys:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Checks if a key is currently held down.
//! input::is_key_down(Key::A);
//!
//! // Checks if a key has been pressed down during the last frame.
//! input::is_key_press(Key::A);
//!
//! // Checks if a key has been released during the last frame.
//! input::is_key_repeat(Key::A);
//! ```
//!
//! A list of all key codes can be found in the `Key` enumeration. Notes
//! that the key code used here, are virtual keycode of physical keys, they don't
//! necessarily represent what's actually printed on the key cap.
//!
//! It's useful to get converted character input instead of raw key codes, to capture
//! entered text in last frame, you can call:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Gets captured text during the last frame.
//! input::text();
//! ```
//!
//! # Mouse Inputs
//!
//! Similar to keyboard device, to find out whether the host platform provides mouse
//! input, call `has_mouse_attached`.
//!
//! To check the state of the mouse buttons, use the following functions:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Checks if a mouse button is held down.
//! input::is_mouse_down(MouseButton::Left);
//!
//! // Checks if a mouse button has been pressed during last frame.
//! input::is_mouse_press(MouseButton::Left);
//!
//! // Checks if a mouse button has been released during last frame.
//! input::is_mouse_release(MouseButton::Left);
//! ```
//!
//! A list of all mouse buttons can be found in the `Key` enumeration. To get
//! the current mouse position and the last frame's mouse movement in pixels:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Gets the mouse position relative to the top-left hand corner of the window.
//! input::mouse_position();
//!
//! // Gets mouse movement in pixels since last frame.
//! input::mouse_movement();
//! ```
//!
//! To get mouse wheel information:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Gets the scroll movement of mouse in pixels, usually provided by mouse wheel.
//! input::mouse_scroll();
//! ```
//!
//! Mouse positions and movement are reported in pixel coordinates which makes it
//! difficult to derive useful movement information out of it. It might changes in
//! the future versions (dividing by the framebuffer resolution is a simple but very
//! fuzzy workaround).
//!
//! We also recognize some simple input patterns, like:
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Checks if a mouse button has been clicked during last frame.
//! input::mouse_position();
//!
//! // Checks if a mouse button has been double clicked during last frame.
//! input::is_mouse_double_click(MouseButton::Left);
//! ```
//!
//! Notes we also have APIs with `_in_points` suffix to works in logical points.
//!
//! # `TouchPad` Inputs
//!
//! The touch input functions provides access to basic touch- and multi-touch-input,
//! and is currently only implemented on mobile platforms and not for notebook
//! touchpads. You can get the touch informations by the finger index, which is
//! ordered by the first touch time.
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Checks if the `n`th finger is touched during last frame.
//! input::is_finger_touched(0);
//!
//! // Gets the position of the `n`th touched finger.
//! input::finger_position(0);
//! ```
//!
//! The touch support also addresses a few platform-agnostic gesture recognizers
//! based on low-level touch inputs.
//!
//! ```rust
//! use crayon::prelude::*;
//! application::oneshot().unwrap();
//!
//! // Gets the tap gesture.
//! match input::finger_tap() {
//! // A tap geture is detected during last frame.
//! GestureTap::Action { position } => { },
//! GestureTap::None => { },
//! }
//!
//! // Gets the double tap gesture.
//! match input::finger_double_tap() {
//! // A double tap geture is detected during last frame.
//! GestureTap::Action { position } => { },
//! GestureTap::None => { },
//! }
//!
//! // Gets the panning gesture.
//! match input::finger_pan() {
//! GesturePan::Start { start_position } => { },
//! GesturePan::Move { start_position, position, movement } => { },
//! GesturePan::End { start_position, position } => { },
//! GesturePan::None => { },
//! }
//! ```
//!
//! Notes we also have APIs with `_in_points` suffix to works in logical points.
//!
//! # Others Inputs
//!
//! Somethings that nice to have, but not implemented right now:
//!
//! 1. Device sensor inputs;
//! 2. Game pad inputs;
//! 3. More touch gesture like `Pinching`.
pub mod events;
pub mod keyboard;
pub mod mouse;
pub mod touchpad;
pub mod prelude {
pub use super::events::InputEvent;
pub use super::keyboard::{Key, KeyboardParams};
pub use super::mouse::{MouseButton, MouseParams};
pub use super::touchpad::{GesturePan, GestureTap, TouchPadParams};
pub use super::InputParams;
}
mod system;
/// Maximum touches that would be tracked at sametime.
pub const MAX_TOUCHES: usize = 4;
use crate::math::prelude::Vector2;
use self::ins::{ctx, CTX};
use self::keyboard::{Key, KeyboardParams};
use self::mouse::{MouseButton, MouseParams};
use self::system::InputSystem;
use self::touchpad::{GesturePan, GestureTap, TouchPadParams};
/// The setup parameters of all supported input devices.
#[derive(Debug, Clone, Copy, Default)]
pub struct InputParams {
pub touch_emulation: bool,
pub keyboard: KeyboardParams,
pub mouse: MouseParams,
pub touchpad: TouchPadParams,
}
/// Setup the resource system.
pub(crate) unsafe fn setup(params: InputParams) {
debug_assert!(CTX.is_null(), "duplicated setup of resource system.");
let ctx = InputSystem::new(params);
CTX = Box::into_raw(Box::new(ctx));
}
/// Discard the resource system.
pub(crate) unsafe fn discard() {
if CTX.is_null() {
return;
}
drop(Box::from_raw(CTX as *mut InputSystem));
CTX = std::ptr::null();
}
/// Checks if the resource system is enabled.
#[inline]
pub fn valid() -> bool {
unsafe { !CTX.is_null() }
}
/// Reset input to initial states.
#[inline]
pub fn reset() {
ctx().reset();
}
/// Returns true if a keyboard is attached
#[inline]
pub fn has_keyboard_attached() -> bool {
ctx().has_keyboard_attached()
}
/// Checks if a key is currently held down.
#[inline]
pub fn is_key_down(key: Key) -> bool {
ctx().is_key_down(key)
}
/// Checks if a key has been pressed down during the last frame.
#[inline]
pub fn is_key_press(key: Key) -> bool {
ctx().is_key_press(key)
}
/// Checks if a key has been released during the last frame.
#[inline]
pub fn is_key_release(key: Key) -> bool {
ctx().is_key_release(key)
}
/// Checks if a key has been repeated during the last frame.
#[inline]
pub fn is_key_repeat(key: Key) -> bool {
ctx().is_key_repeat(key)
}
/// Gets captured text during the last frame.
#[inline]
pub fn text() -> String {
ctx().text()
}
/// Returns true if a mouse is attached
#[inline]
pub fn has_mouse_attached() -> bool {
ctx().has_mouse_attached()
}
/// Checks if a mouse buttoAn is held down.
#[inline]
pub fn is_mouse_down(button: MouseButton) -> bool {
ctx().is_mouse_down(button)
}
/// Checks if a mouse button has been pressed during last frame.
#[inline]
pub fn is_mouse_press(button: MouseButton) -> bool {
ctx().is_mouse_press(button)
}
/// Checks if a mouse button has been released during last frame.
#[inline]
pub fn is_mouse_release(button: MouseButton) -> bool {
ctx().is_mouse_release(button)
}
/// Checks if a mouse button has been clicked during last frame.
#[inline]
pub fn is_mouse_click(button: MouseButton) -> bool {
ctx().is_mouse_click(button)
}
/// Checks if a mouse button has been double clicked during last frame.
#[inline]
pub fn is_mouse_double_click(button: MouseButton) -> bool {
ctx().is_mouse_double_click(button)
}
/// Gets the mouse position relative to the lower-left hand corner of the window.
#[inline]
pub fn mouse_position() -> Vector2<f32> {
ctx().mouse_position()
}
/// Gets mouse movement since last frame.
#[inline]
pub fn mouse_movement() -> Vector2<f32> {
ctx().mouse_movement()
}
/// Gets the scroll movement of mouse, usually provided by mouse wheel.
#[inline]
pub fn mouse_scroll() -> Vector2<f32> {
ctx().mouse_scroll()
}
/// Returns true if a touchpad is attached
#[inline]
pub fn has_touchpad_attached() -> bool {
ctx().has_touchpad_attached()
}
/// Checks if the `n`th finger is touched during last frame.
#[inline]
pub fn is_finger_touched(n: usize) -> bool {
ctx().is_finger_touched(n)
}
/// Gets the position of the `n`th touched finger.
#[inline]
pub fn finger_position(n: usize) -> Option<Vector2<f32>> {
ctx().finger_position(n)
}
/// Gets the tap gesture.
#[inline]
pub fn finger_tap() -> GestureTap {
ctx().finger_tap()
}
/// Gets the double tap gesture.
#[inline]
pub fn finger_double_tap() -> GestureTap {
ctx().finger_double_tap()
}
/// Gets the panning gesture.
#[inline]
pub fn finger_pan() -> GesturePan {
ctx().finger_pan()
}
mod ins {
use super::system::InputSystem;
pub static mut CTX: *const InputSystem = std::ptr::null();
#[inline]
pub fn ctx() -> &'static InputSystem {
unsafe {
debug_assert!(
!CTX.is_null(),
"input system has not been initialized properly."
);
&*CTX
}
}
}