chialab-gestures v1.1.0

Gestures

A library for custom gestures.

Special thanks

This work is inspired by the Polymer.Gestures implementation.

Install

$ npm i chialab-gestures --save

$ bower i chialab-gestures --save

Bind gestures

There are two ways to bind a gesture to a HTMLElement:

• bind directly to the node:

Gestures.addEventListener(node, 'tap', callback);

• bind a wrapper (or the whole document) and use native Node.addEventListener

Gestures.bindGesture(document.body, 'tap');
node.addEventListener('tap', callback);

Builtin gestures

• down and up

  • down is an alias for mousedown and touchstart both.
  • up is an alias for mouseup and touchend both.

• tap

  • tap is fired on click using the left mouse button or after a touchstart/touchend combination in touch environments.

    Params

  • Gestures.tapSensibility: during the gesture, user could slightly move the cursor or the finger. Set up the max number of pixel to ignore before gesture failure (@default 25).

• track

  • track is fired when the user move the cursor after a mousedown or during a touchmove. It is very useful for drag & drop implementation.

    Params

  • Gestures.minTrackDistance: the required number of pixel to reach with the tracking before event triggering (@default 5).

    Extra event info

  • dx: the distance (in pixel) over the x axis.

  • dy: the distance (in pixel) over the y axis.
  • ddx: the distance (in pixel) over the x axis from the last track trigger.
  • ddy: the distance (in pixel) over the y axis from the last track trigger.

• hold

  • an hold event is fired after a long press with the left mouse button or on the touch screen.

    Params

  • Gestures.holdTimeout: the press duration in ms (@default 350).

    Extra event info

  • timeout: the press duration in ms.

Register a new gesture

Use the Gestures.register method:

Gestures.register({
    name: 'myCustomGesture',
    deps: ['mousedown', 'touchstart', ...],
    flow: {
        start: ['mousedown', 'touchstart'],
        end: ['mouseup', 'touchend'],
    },
    emits: ['myCustomEvent'],
    reset: function() {
        // callback triggered at the end or the failure of the gesture
    },
    mousedown: function(e) {
        // on mousedown
    },
    touchstart: function(e) {
        // on touchstart
    },
    fire: function(myCustomEventName, targetNode, sourceEvent) {
        // fire my custom event
        Gestures.fire(targetNode, myCustomEventName, {
            ... // custom extra event details
            sourceEvent: sourceEvent,
            prevent: function(e) {
                return Gestures.prevent(e);
            }
        });
    }
});

Dev