Home Reference Source Test

ZingTouch

A modern JavaScript touch gesture library. Allows developers to configure pre-existing gestures and even create their own using ZingTouch's life cycle.

Code Climate Documentation

Table of Contents

Overview

ZingTouch is built to make implementing gestures for the browser as easy or complex as you need it to be. ZingTouch comes with 6 main gestures :

These gestures can be customized including the number of inputs it accepts, or how sensitive the gesture is to be recognized.

ZingTouch is also has lifecycle events that you can hook into to create new Gestures or to act upon certain touch events. We know supporting touch events across multiple browsers can be a pain; ZingTouch makes it easy by defining 3 hooks to pass callbacks to :

Getting Started

Include the library

ES6 / CommonJS

var ZingTouch = require('ZingTouch');

or

Include the file

<script src='./path/to/zingtouch.js'></script>

Create a Region

var zt = new ZingTouch.Region(document.body);

Bind an element to a gesture

var myElement = document.getElementById('my-div');

zt.bind(myElement, 'tap', function(e){
    //Actions here
}, false);

Usage

Table of Contents

Constructs

Gestures

Methods

Constructs

Region

new Region(element, [capture], [preventDefault])

Regions specify an area to listen for all window events. ZingTouch needs to listen to all window events in order to determine if a gesture is recognized. Note that you can reuse regions for multiple elements and gesture bindings. They simply specify an area where to listen for gestures.

Suppose you had an element that you wanted to track gestures on. We set the region on that element along with binding it to a gesture.

var touchArea = document.getElementById('toucharea');
var myRegion = new ZingTouch.Region(touchArea);

myRegion.bind(touchArea, 'swipe', function(e){
    console.log(e.detail);
});

The shaded area in blue shows the area where ZingTouch will now listen for events such as touchstart, touchmove, touchend, etc.

Region

But humans aren't perfect. Suppose the element #toucharea were to listen for the Swipe gesture. The tracking of the window events will stop when the user reaches the edges of #toucharea. But what if the user didn't finish until say 10-50px outside the element? Regions are here to help.

Suppose you set the Region to the parent of the #toucharea element instead.

var parentTouchArea = document.getElementById('parent-toucharea')
var touchArea = document.getElementById('toucharea')
var myRegion = new ZingTouch.Region(parentTouchArea);

myRegion.bind(touchArea, 'swipe', function(e){
    console.log(e.detail);
});

Parent Region

ZingTouch now tracks the swipe gesture inside the #toucharea element AND the #parent-toucharea. This allows some forgiveness when the user tries to swipe on the #toucharea, but lifts their finger somewhere in the #parent-toucharea.

Note: The swipe gesture can only be initiated on the area it is bound to. This means the user has to being touching the #toucharea element first, but can move out and end within #parent-toucharea and including #toucharea.

Multiple Regions

Regions only are aware of themselves and their contents, not across regions. This allows for control at a larger scale so you can group similar gestures together. While you can throw a Region on top of the document.body, we suggest splitting up your application into regions for better performance -- the less bindings a single region has to iterate through to detect a gesture, the better.

Multiple Regions

Gestures

Gesture classes can be instatiated to generate modified versions.

Tap

Tap Gesture

A tap is detected when the user touches the screen and releases in quick succession.

Options

Example

new ZingTouch.Tap({
    maxDelay: 200,
    numInputs: 2,
    tolerance: 125
})

Emits


Swipe

Swipe Gesture

A swipe is detected when the user touches the screen and moves in a relatively increasing velocity, leaving the screen at some point before it drops below a certain velocity.

Options

Example

new ZingTouch.Swipe({
    numInputs: 2,
    maxRestTime: 100,
    escapeVelocity: 0.25
});

Emits

An array of data objects containing:

Each index represents an input that participated in the event.


Pinch

Pinch Gesture

A pinch is detected when the user has two inputs on the screen and moves one or both closer towards the other input.

Example

new ZingTouch.Pinch()

Emits


Expand

Expand Gesture

An expand is detected when the user has two inputs on the screen and moves one or both away from the other input.

Example

new ZingTouch.Expand()

Emits


Pan

Pan Gesture

A pan is detected when the user touches the screen and moves about the area.

Options

Example

new ZingTouch.Pan({
    numInputs: 2
})

Emits

An array of data objects containing:

Each index represents an input that participated in the event.


Rotate

Rotate Gesture

A Rotate is detected when the use has two inputs moving about a circle on the edges of a diameter.

Example

new ZingTouch.Rotate()

Emits


Gesture

A generic gesture. By default, this gesture does not emit but is useful for hooking into ZingTouch's life cycle. See ZingTouch Life Cycle for more information.

Example

new ZingTouch.Gesture()

Methods

Region.bind(element, gesture, handler, [capture])

Binds a single element to a gesture, executing the handler when the gesture is emitted.

Parameters

Example #1

var myRegion = new ZingTouch.Region(document.body);
var myElement = document.getElementById('some-div');

myRegion.bind(myElement, 'tap', function(e) {
    console.log('Tap gesture emitted: ' + e.detail.interval);
});

Example #2

var myElement = document.getElementById('some-div');
var myTapGesture = new ZingTouch.Tap({ maxDelay : 100 });
var myRegion = new ZingTouch.Region(document.body);

myRegion.bind(myElement, myTapGesture, function(e) {
    console.log('Custom Tap gesture emitted: ' + e.detail.interval);
}, false);

Notes

  1. Instance Gestures that are passed to bind will be stored and maintained in memory, therefore it is reccomended to reuse gestures object where possible, or to use the Region.register syntax -- they essentially do the same thing. Either works fine, but try to avoid using the following pattern where an instance variable is created at every bind :
//Poor performance
var delay = 100;
for (var i = 0; i < 100; i++){
    myRegion.bind(myElement, new ZingTouch.Tap({maxDelay : delay}),function(e){...});
}
//Better performance
var delay = 100;
var customTap = new ZingTouch.Tap({maxDelay : delay});
for (var i = 0; i < 100; i++){
    myRegion.bind(myElement, customTap, function(e){...});
}

Region.bind(element)

Passing a qualified DOM element to the bind function will return an object that can be chainable with the 6 main gestures, or any other gestures that you may have registered with Region.register

Parameters

Returns

Example

var myElement = document.getElementById('mydiv');
var myRegion = new ZingTouch.Region(myElement);
var chainableObject = myRegion.bind(myElement);

chainableObject
    .tap(function(e){
        console.log(e.detail);
    })
    .swipe(function(e){
        console.log(e.detail);
    }, true)

Region.bindOnce()

Identical to both method signatures of bind, but is "bound once" meaning the event will only be captured once before it is destroyed.

See Region.bind


Region.unbind(element, [gesture])

Unbinds an element from a specific gesture, or all gestures if none is specified.

Parameters

Returns

Examples

Unbind from a specific gesture

var myElement = document.getElementById('mydiv');
myRegion.unbind(myElement, 'tap');

Unbind from all gestures

var myElement = document.getElementById('mydiv');
myRegion.unbind(myElement);

Unbind from a gesture instance.

var myElement = document.getElementById('mydiv');
var myRegion = new ZingTouch.Region(document.body);
var myTapGesture = new ZingTouch.Tap({ maxDelay : 100 });

myRegion.bind(myElement, myTapGesture, function(e) {});

myRegion.unbind(myElement, myTapGesture);

Region.register(key, gesture)

Register a gesture of the Gesture class to each Region. Allows the newly registered Gesture to be accessible in the bind/unbind syntax including the chainable object of bind.

Parameters

Returns

Examples

var myTapGesture = new ZingTouch.Tap({ maxDelay : 60 });

var myRegion = new ZingTouch.Region(document.body);
myRegion.register('shortTap', myTapGesture);

And the usages :

myRegion.bind(myElement, 'shortTap', function(e){});
myRegion.bind(myElement).shortTap(function(e){});

Region.unregister(key)

Unregisters a gesture that was previously registered. Unregistering a gesture will automatically unbind any elements that were bound to this gesture.

Parameters

Returns

Example

myRegion.unregister('shortTap');

ZingTouch Life Cycle

Utilizing ZingTouch's life cycle (start, move, end) allows you to create new gestures and to interface with the mobile event cycle in a much finer detail. It will allow you to hook into events and to apply external functions during events. Imagine the Pan gesture allowing in-between events to be triggered:

The syntax for utilizing the life cycle is still to be determined, but will be released in the near future.


Contributing

Build dependencies

Comments and Documentation

Testing

npm scripts


License

MIT License

© 2016 ZingChart, Inc.