StInput
State-based input for modern browsers.
Install
NPM
npm install stinput
Bower
bower install stinput
Other
Just fetch stinput.js
from this repo and include in your web page.
Supported Browsers
StInput don't require any external libs and should work on all modern browsers, but note that it uses JavaScript classes and therefor requires ECMAScript 2015 or newer to run.
Usage Example
To use StInput
you need to create an StInput instance, update it at the end of every frame, and query it.
For example:
// create the input managerinput = ; // our main loop { // left mouse button is down if input console; // left mouse button was released this update call if input console; // left mouse button was released this update call if input console; // keyboard button up arrow was released if input console; // mouse moved if inputmouseMoving console; // update input input;} // start main loop;
When you finish using StInput call input.dispose()
to unregister all its event handlers.
Full API
Create / Destroy
Creating New StInput:
// 'element' is the DOM element you want to register events on. // if not defined, will use 'window'.var input = element;
Destroying StInput:
input;
Update
For StInput to work properly, you must update it every frame of your main loop, at the end of your update function.
To do so, call endFrame()
:
input;
Mouse Buttons
Checking if mouse button is down:
// returns if different mouse buttons are held downinputinputinput // Or: // returns if different mouse buttons are held downinputinputinput
Checking if a mouse button was released this update call:
// returns if different mouse buttons were released this update callinputinputinput // Or: // returns if different mouse buttons were released this update callinputinputinput
Checking if mouse button was pressed this update call:
// returns if different mouse buttons were released this update callinputinputinput // Or: // returns if different mouse buttons were released this update callinputinputinput
Mouse Position & Movement
Get mouse current position:
// returns Point with x,y representing mouse current positioninputmousePosition
Checking if mouse is currently moving:
// returns true if mouse is currently movinginputmouseMoving
Get a point {x,y} representing the mouse position delta since last update call:
// returns Point with x,y representing mouse movementinputmouseDelta
Mouse Wheel
Get mouse wheel delta in this update call:
// get mouse wheel deltainputmouseWheel // get just the mouse wheel change sign:inputmouseWheelDirection
Keyboard
Checking if keyboard key is down:
// returns if 'a' key is downinput // Or: // returns if 'a' key is downinput
Checking if keyboard key was released this update call:
// returns if 'a' key was released this update callinput // Or: // returns if 'a' key was released this update callinput
Checking if keyboard key was pressed this update call:
// returns if 'a' key was released this update callinput // Or: // returns if 'a' key was released this update callinput
Check if any keyboard key is currently down:
// returns if any keyboard key is held downinputanyKeyDown
Check special keys states:
// returns if alt, ctrl, or shift are currently held down// note: in some browsers pressing 'alt' will make the window lose focus, so its not recommended to useinputaltDowninputctrlDowninputshiftDown
Supported Keys
All supported mouse buttons are:
StinputMouseButtonss = left: 0 middle: 1 right: 2
All supported keyboard keys are:
StinputKeyboardKeys = backspace: 8 tab: 9 enter: 13 shift: 16 ctrl: 17 alt: 18 break: 19 caps_lock: 20 escape: 27 page_up: 33 page_down: 34 end: 35 home: 36 left_arrow: 37 up_arrow: 38 right_arrow: 39 down_arrow: 40 insert: 45 delete: 46 space: 32 n0: 48 n1: 49 n2: 50 n3: 51 n4: 52 n5: 53 n6: 54 n7: 55 n8: 56 n9: 57 a: 65 b: 66 c: 67 d: 68 e: 69 f: 70 g: 71 h: 72 i: 73 j: 74 k: 75 l: 76 m: 77 n: 78 o: 79 p: 80 q: 81 r: 82 s: 83 t: 84 u: 85 v: 86 w: 87 x: 88 y: 89 z: 90 left_window_key: 91 right_window_key: 92 select_key: 93 numpad_0: 96 numpad_1: 97 numpad_2: 98 numpad_3: 99 numpad_4: 100 numpad_5: 101 numpad_6: 102 numpad_7: 103 numpad_8: 104 numpad_9: 105 multiply: 106 add: 107 subtract: 109 decimal_point: 110 divide: 111 f1: 112 f2: 113 f3: 114 f4: 115 f5: 116 f6: 117 f7: 118 f8: 119 f9: 120 f10: 121 f11: 122 f12: 123 numlock: 144 scroll_lock: 145 semicolon: 186 equal_sign: 187 comma: 188 dash: 189 period: 190 forward_slash: 191 grave_accent: 192 open_bracket: 219 back_slash: 220 close_braket: 221 single_quote: 222
Miscs
Some extra properties you can set to StInput instance:
input.preventDefaults
If true, will prevent defaults on all events it register to (defaults to false).
input.enableMouseDeltaWhileMouseWheelDown
If true, will disable the default mouse-wheel-down action to allow getting mouse delta while users hold down the mouse wheel (defaults to true).
input.disableContextMenu
If true, will disable the right-click context menu (defaults to true).
input.resetOnFocusLoss
If true, will reset all internal states when element / window loses focus (defaults to true). This property is described later in details.
Handling Focus Loss
By default, whenever the browser window loses its focus, StInput will reset all its internal state.
This behavior is important to prevent keys from getting "stuck" in down state due to browsers limitations (for example, if you hold down a key, make the window lose focus, and then release the key outside - you won't get the keyup event and the key will remain stuck).
However, if you wish to override this behavior, set resetOnFocusLoss
to false:
// will not reset state on focus loss.inputresetOnFocusLoss = false;
License
StInput is distributed under the permissive MIT license and may be used for any purpose, commercial included.