## 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 `MouseEvent`s, `TouchEvent`s or `PointerEvent`s, 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.
`waitUntil(timestamp)` | `this` | Don't move this finger until the given timestamp is reached.
`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 `Touch`es 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 `Touch`es into `TouchEvent`s, 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 `Touch`es.
`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 `Finger`s, 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

### Events

Use `document.addEventListener('prostheticHandStop', fn)` to do stuff with it.

Event | Data | Description
--- | --- | ---
`prostheticHandStart` | `CustomEvent` | Fired when all movements are complete.
`prostheticHandStop` | `CustomEvent` | Fired when all movements are complete.
`prostheticHandTick` | `CustomEvent` | Fired a movement is about to start, just before the mouse/touch/pointer events are fired.

### 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.
`sync(delay)` | `this` | Synchronizes the finger movements by adding a delay of at least `delay` milliseconds to each finger. After a sync, the movements of the fingers will happen at exactly the same time.
`private_dispatchEvents()` | `this` | Updates all the fingers, fetching their events/touchpoints, and dispatches all `Event`s 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.