westures-core


Westures is a robust n-pointer multitouch gesture detection library for
JavaScript. This means that each gesture is be capable of working seamlessly as
input points are added and removed, with no limit on the number of input points,
and with each input point contributing to the gesture. It is also capable of
working across a wide range of devices.

This module contains the core functionality of the Westures gesture library for
JavaScript. It is intended for use as a lighter-weight module to use if you do
not want to use the base gestures included with the standard westures module.

Visit this page for an example of the system in action: Westures Example.

Westures aims to achieve its goals without using any dependencies, yet maintain
usability across the main modern browsers. Transpilation may be necessary for
this last point to be achieved, as the library is written using many of the
newer features of the JavaScript language. A transpiled bundle is provided, but
the browser target list is arbitrary and likely includes some bloat. In most
cases you will be better off performing bundling, transpilation, and
minification yourself.

Westures is a fork of ZingTouch.

Quick Example

``javascript
// Import the module.
const wes = require('westures-core');

// Declare a region. The default is the window object, but other elements like
// the document body work too.
const region = new wes.Region();

// Define a Gesture subclass
class Follow extends wes.Gesture {
move(state) {
return state.centroid; // Reports the {x, y} of the average input position
}
}

// Locate an element to attach the gesture to.
const element = document.querySelector('#follow');

// Instantiate a Gesture for an element within the region.
const follow = new Follow(element, (data) => {
// data.x ...
// data.y ...
});

// Add the gesture to the region.
region.addGesture(follow);
`

Table of Contents

- Features
- Overview
- Basic Usage
- Implementing Custom Gestures
- Nomenclature and Origins
- Changes
- Issues
- Links

Features

- Full simultaneous multi-touch gesture support.
- Continuous use of pointer input allows seamless flow from gesture to
gesture without interruption.
- Robust, simple to understand, easy to maintain engine.
- Inertial smoothing capabilities for systems using coarse pointers (e.g. touch
surfaces).
- Ability to enable / disable gestures with keys (e.g. ctrlKey, shiftKey)
- This allows for easy implementation of single-pointer flows that provide
the equivalent behaviour as multi-pointer flows. For example, holding
'CTRL' on a desktop could switch from panning mode to rotating mode.
- Allows for easy implementation and integration of custom gestures using the
four-phase hook structure.

Overview

There are seven classes made available by this module:

Name | Description
----------- | -----------
Gesture | Base class for defining westures gestures
Input | Track a single pointer through its lifetime
Point2D | Store and act on a 2-dimensional point
PointerData | Record data pertaining to a single user input event for a single pointer.
Region | Listen for user input events and respond appropriately
Smoothable | Datatype which provides inertial smoothing capabilities
State | Track inputs within a Region

Additionally, two support files are defined:

Name | Description
--------- | -----------
constants | Constant values used throughout the engine
utils | Helpful utility functions

Basic Usage

- Declaring a Region
- Defining a Gesture Subclass
- Instantiating a Gesture
- Adding a Gesture to a Region

$3

`javascript
const wes = require('westures-core');
`

$3

First, decide what region should listen for events. This could be the
interactable element itself, or a larger region (possibly containing many
interactable elements). Behaviour may differ slightly based on the approach you
take, as a Region will perform locking operations on its interactable elements
and their bound gestures so as to limit interference between elements during
gestures, and no such locking occurs between Regions.

If you have lots of interactable elements on your page, you may find it
convenient to use smaller elements as regions. Test it out in any case, and see
what works better for you.

By default, the window object is used.

`javascript
const region = new wes.Region(document.body);
`

$3

In order to use the engine, you'll need to define gestures. This is done by
extending the Gesture class provided by this module, and overriding any or all
of the four phase hooks ('start', 'move', 'end', and 'cancel') as is appropriate
for your gesture.

Defined here is a very simple gesture that simply reports the centroid of the
input points. Note that the returned value must be an Object!

`javascript
// Define a Gesture subclass
class Follow extends wes.Gesture {
move(state) {
return state.centroid;
}
}
`

$3

When you instantiate a gesture, you need to provide a handler as well as an
Element. The gesture will only be recognized when the first pointer to interact
with the region was inside the given Element. Therefore unless you want to try
something fancy the gesture element should probably be contained inside the
region element. It could even be the region element.

Now for an example. Suppose you have a div within which you want to detect the
Follow gesture we defined above. The div has id 'follow'. We need to find the
element first.

`javascript
const element = document.querySelector('#follow');
`

And we also need a handler. This function will be called whenever a gesture hook
returns non-null data. For Follow, this is just the move phase, but the handler
doesn't need to know that. The data returned by the hook will be available
inside the handler.

`javascript
function followLogger(data) {
console.log(
'The centroid of the points interacting with #follow is:',
'x:', data.x,
'y:', data.y,
)
}
`

Now we're ready to combine the element and its handler into a gesture.

`javascript
const follow = new Follow(element, followLogger);
`

We're not quite done though, as none of this will actually work until you add
the gesture to the region.

$3

Simple:

`javascript
region.addGesture(follow);
`

Now the followLogger function will be called whenever a follow gesture is
detected on the #follow element inside the region.

Implementing Custom Gestures

The core technique used by Westures is to process all user inputs and filter
them through four key lifecycle phases: start, move, end, and cancel.
Gestures are defined by how they respond to these phases. To respond to the
phases, a gesture extends the Gesture class provided by this module and
overrides the method (a.k.a. "hook") corresponding to the name of the phase.

The hook, when called, will receive the current State object of the region. To
maintain responsiveness, the functionality within a hook should be short and as
efficient as possible.

For example, a simple way to implement a Tap gesture would be as follows:

`javascript
const { Gesture } = require('westures-core');

const TIMEOUT = 100;

class Tap extends Gesture {
constructor() {
super('tap');
this.startTime = null;
}

start(state) {
this.startTime = Date.now();
}

end(state) {
if (Date.now() - this.startTime <= TIMEOUT) {
return state.getInputsInPhase('end')[0].current.point;
}
return null;
}
}
`

There are problems with this example, and it should probably not be used as an
actual Tap gesture, it is merely to illustrate the basic idea.

The default hooks for all Gestures simply return null. Data will only be
forwarded to bound handlers when a non-null value is returned by a hook.
Returned values should be packed inside an object. For example, instead of just
return 42;, a custom hook should do return { value: 42 };

If your Gesture subclass needs to track any kind of complex state, remember that
it may be necessary to reset the state in the cancel phase.

For information about what data is accessible via the State object, see the full
documentation here.
Note that his documentation was generated with jsdoc.

$3

As you can see from above, it is the gesture which decides when data gets passed
to handlers, and for the most part what that data will be. Note though that a
few properties will get added to the outgoing data object before the handler is
called. Those properties are:

Name | Type | Value
-------- | -------- | -----
centroid | Point2D | The centroid of the input points.
event | Event | The input event which caused the gesture to be recognized
phase | String | 'start', 'move', 'end', or 'cancel'`
type | String | The name of the gesture as specified by its designer.
target | Element | The Element that is associated with the recognized gesture.

If data properties returned by a hook have a name collision with one of these
properties, the value from the hook gets precedent and the default is
overwritten.

Nomenclature and Origins

In my last year of univerisity, I was working on an API for building
multi-device interfaces called "WAMS" (Workspaces Across Multiple Surfaces),
which included the goal of supporting multi-device gestures.

After an extensive search I found that none of the available multitouch
libraries for JavaScript provided the fidelity I needed, and concluded that I
would need to write my own, or at least fork an existing one. ZingTouch proved
to the be the most approachable, so I decided it would make a good starting
point.

The name "westures" is a mash-up of "WAMS" and "gestures".

Changes

See the changelog for the
most recent updates.

Issues

If you find any issues, please let me know!

Links

$3

- npm
- github
- documentation

$3

- npm
- github
- documentation