Leafdoc generated API reference

Finger

Represents a finger, capable of performing single touch/pointer/mouse synthetic events.

Usage example

var h = new Hand();
var fatFinger = h.growFinger('pointer', { pointerType: 'touch', pressure: 0.9 });
var lightFinger = h.growFinger('pointer', { pointerType: 'touch', pressure: 0.1 });
fatFinger.wait(500).moveTo(200, 250, 0).down().moveBy(100, 150, 2000).up();

Creation

Instantiation Description
new Finger(<String> eventMode, <Finger state> options?) Instantiates a new Finger. eventMode must be mouse, touch or pointer for MouseEvents, TouchEvents or PointerEvents, respectively.

Options

Finger state

The internal state of a Finger has options which will be reflected as properties of the events fired afterwards. Some of these state options apply only to a specific event mode.
Option Type Default Description
x Number The number of pixels from the left boundary the finger is at.
y Number The number of pixels from the top boundary the finger is at.
down Boolean Whether the finger is down (clicking/touching/pressing) or not. This is referred to as "active" in some of the events specifications.
pressure Number 0.5 The value for Touch.force or PointerEvent.pressure, between 0.0 and 1.0
tiltX Number 0 The value for PointerEvent.tiltX
tiltY Number 0 The value for PointerEvent.tiltX
width Number 25 The value for Touch.radiusX or PointerEvent.width
radiusY Number 25 The value for Touch.radiusY or PointerEvent.height
pointerType String 'pen' The value for PointerEvent.pointerType

Methods

Finger state

Method Returns Description
isIdle() Boolean Returns true when the finger has no more pending movements/waits/wiggles/etc.
down(<Number> delay?) this Puts the finger down, optionally after a delay.
up(<{}> options?) this Lifts the finger up, after an optional delay.
wait(delay) this Don't move this finger for delay milliseconds.
update(<{}> options?) this Updates some of the finger options, like pressure or touch angle, without disturbing its movement, after an optional delay.
reset(<{}> options?) this Clears all the queued movements for this finger and immediately lifts it up
moveTo(<Number> x, <Number> y, <Number> delay, <{}> options?) this Queues moving this finger to an absolute position at (x, y); the movement will last for delay milliseconds.
moveBy(<Number> x, <Number> y, <Number> delay, <{}> options?) this Queues a move of this finger to an position relative to its last position plus(x, y); the movement will last for delay milliseconds.
getNextMoveEndTime() Number|undefined
getEvents(<Number> timestamp?, <Boolean> justOne) [] Updates the private properties of the finger (x, y, timestamp) by running the next movement(s) as far as indicated by the timestamp (or as fas as to performance.now()), then checks if the state has changed and means an event should be fired. If justOne is set to truthy, then this will run just one movements. Otherwise, it will run as many movements as needed until timestamp is reached. Returns an array of objects of the form {type: 'foo', event: MouseEvent(...), finger: Finger} or {type: 'foo', touch: Touch(...), finger: Finger}, with all the active Touches or all triggered mouse/pointer events triggered by executing moves until timestamp. If the finger doesn't matter when getEvents() is called, then an empty array is return instead. This happens for mice not moving, and fingers not touching (fingers touching but not moving, and mice not pressing but moving do matter). A Hand is reponsible for getting events (using loops, timings, or whatever), requesting the right timestamps if needed, merging Touches into TouchEvents, and firing the events via dispatchEvent().
private_asTouch() Touch Returns an instance of Touch representing the current state of the finger Note this is not an event - a TouchEvent must be created later, with several Touches.
private_asPointerEvent() PointerEvent Returns an instance of PointerEvent representing the current state of the finger
private_asMouseEvent(<String> evType) PointerEvent Returns an instance of PointerEvent representing the current state of the finger

Hand

Represents a set of Fingers, capable of performing synthetic touch gestures

Usage example

var h = new Hand({ timing: '20ms' });

Creation

Instantiation Description
new Hand(<Hand options> options?) Instantiates a new Hand with the given options.

Options

Option Type Default Description
timing Timing '20ms' Defines how often new events will be fired, in one of the possible timing modes

Methods

Method Returns Description
growFinger(eventMode, options) Finger Creates a new Finger with the same parameters as the Finger constructor, and adds it to the hand.
fingerIsBusy() this Used by this hand's fingers to signal that there are movements to be performed by at least one finger.
fingerIsIdle() this Used by this hand's fingers to signal that one finger has finished doing all the queued movements.
private_dispatchEvents() this Updates all the fingers, fetching their events/touchpoints, and dispatches all Events triggered by the update. This is meant to be called on an internal timer.

Timing

Option Type Default Description
ms Preceded by a number (e.g. '20ms'), this mode triggers an event dispatch every that many milliseconds.
frame This mode dispatches an event every animation frame.
minimal This mode triggers an event dispatch per finger change, and ensures that every move can trigger its own event (no two movements will be rolled into one event if they are very close).
instant Like the minimal mode, but ignores timings completely and dispatches all events instantaneously. This might cause misbehaviour in graphical browsers.
fastframe This mode ignores timings completely like the instant mode, and dispatches a new event every so many frames.