API.md

Classes

Taps

Tap

Taps

Properties:

Name	Type	Description
dragDistance	number	Distance in pixels for tap to move from start position to enter drag state, default: 20 pixels.
dragDelay	number	Time in milliseconds for tap to enter drag state if held for that long, default: 200 milliseconds.

new Taps([element]) (constructor)
.start : Iterable.<Tap>
.up : Iterable.<Tap>
.click : Iterable.<Tap>
.dragstart : Iterable.<Tap>
.drag : Iterable.<Tap>
.dragend : Iterable.<Tap>
.update()

new Taps([element])

Taps provide source agnostic sync access to input. Either it comes from mouse and/or touch, it is the same API. It assumes multiple instances of taps making your code multi-touch by design. Providing sync access instead of event based, for best usage in real-time applications. Class itself is an iterator for easy access to taps.

Param	Type	Description
[element]	object	Element to which mouse and touch events to be attached, by default window.

Example

// create taps interface
const taps = new Taps();

function update() {
    requestAnimationFrame(update);

    // update taps on each frame
    taps.update();

    // access all taps
    for(const tap of taps) {
        // iterate through all taps
    }
}
requestAnimationFrame(update);

.start : Iterable.<Tap>

Iterator of taps that just've been created. Tap can be only once in start state during its life.

Example

for(const tap of taps.start) {
    // same as touchstart or mousedown
}

.up : Iterable.<Tap>

Iterator of taps that been released. Tap can be only once in up state during its life and will be removed after.

Example

for(const tap of taps.up) {
    // same as touchend, touchcancel or mouseup
}

.click : Iterable.<Tap>

Iterator of taps that are consider clicks. Tap can be only once in click state, and will be removed after.

Example

for(const tap of taps.click) {
    // same as click, happens on mouseup or touchend
    // if tap been short lived and/or didn't move too far from initial position
}

.dragstart : Iterable.<Tap>

Iterator of taps that started a drag. Tap can be only once in dragstart state. It is guaranteed to trigger dragend instead of click as a last state.

Example

for(const tap of taps.dragstart) {
    // held touch/mousedown for long enough or moved far enough from initial tap position
}

.drag : Iterable.<Tap>

Iterator of taps that are in drag state. This state will persist from and during dragstart and until/during dragend states.

Example

for(const tap of taps.drag) {
    // tap is dragging
}

.dragend : Iterable.<Tap>

Iterator of taps that ended a drag. Tap can be only once in dragend state, and will be removed after.

Example

for(const tap of taps.dragend) {
    // drag is finished
}

.update()

Update taps states, should be executed in the beginning of an application every update loop.

Example

function update() {
    requestAnimationFrame(update);

    // update taps on each frame
    taps.update();

    // access all taps
}
requestAnimationFrame(update);

Tap

Properties:

Name	Type	Description
start	boolean	True when tap been just created, equivalent to mousedown and touchstart.
up	boolean	True when tap is ended, equivalent to mouseup, touchend, touchcancel. It can be in that state only once, and will be removed after.
click	boolean	True when tap is considered a click. It can be in that state only once, and will be removed after.
dragstart	boolean	True when tap is started dragging, which happens when either: tap duration is long enough and/or it is moved away from initial position enough. It will be in that state once, and guarantees to have dragend state instead of click state.
drag	boolean	True when tap is dragging. It will be in that state from dragstart till the end of a tap.
dragend	boolean	True when tap is ended dragging. It will be in that state only if previously was in dragstart, and tap will be removed after.
timestamp	boolean	Milliseconds timestamp of when tap has started.
mouse	boolean	True when tap originated from mouse input.
button	null | number	If originated from mouse, a button number, otherwise null.
x	number	X current coordinate of a tap, where 0 - is left.
y	number	Y current coordinate of a tap, where 0 - is top.
sx	number	X coordinate of where tap started.
sy	number	Y coordinate of where tap started.
dx	number	X distance of a tap traveled since previous update.
dy	number	Y distance of a tap traveled since previous update.

new Tap()

Tap is instintiated by Taps, and provides information about the input, its state and coordinates. It is source agnostic, and behaves identical between mouse and touch.

Example

// clicking

for(const tap of taps.click) {
    // pick an object based on tap coordinates
    const object = pickObject(tap.x, tap.y);
    if (! object) continue;

    object.interact();
}

Example

// dragging

// grab an object for dragstart taps
for(const tap of taps.dragstart) {
    // pick an object based on tap start coordinates
    const object = pickObject(tap.sx, tap.sy);
    // remember that object against a tap
    tap.object = object;
}

// move an objects for drag taps
for(const tap of taps.drag) {
    // ensure we have an object
    if (! tap.object) continue;

    // set position of a dragged object to tap coordinates
    tap.object.setPosition(tap.x, tap.y);
}

// throw an object for dragend taps
for(const tap of taps.dragend) {
    // ensure we have an object
    if (! tap.object) continue;

    // dt - delta time, to correct for a variable FPS
    tap.object.setLinearVelocity(tap.dx * dt, tap.dy * dt);
}