westures-core

Westures is an n-pointer gesture detection library for JavaScript. Gestures can continue as input points are added and removed, with each active input point available to the gesture.

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 has no runtime dependencies. It uses Pointer Events when available and otherwise listens to mouse and touch events. The package's CommonJS entry point is a bundled build; applications that target older browsers may need to transpile it as part of their own build pipeline.

Westures is a fork of ZingTouch.

Quick Example

// 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 {
  constructor(element, handler, options) {
    super('follow', element, handler, options);
  }

  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
• Installation
• Basic Usage
• Implementing Custom Gestures
• Nomenclature and Origins
• Changes
• Issues
• Contributing
• 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

The package also exports its constants and utility functions, including PHASES, STATE_KEYS, angularDifference, and setFilter.

Installation

npm install westures-core

The package uses CommonJS:

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

Region requires a browser environment by default. For server-side or test use, create it in headless mode and provide events directly to arbitrate(event), cancel(event), and handleKeyboardEvent(event). Events passed to a headless region must include a target so the region can select the gesture to evaluate.

Basic Usage

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

Declaring a Region

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.

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

Defining a Gesture Subclass

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!

// Define a Gesture subclass
class Follow extends wes.Gesture {
  constructor(element, handler, options) {
    super('follow', element, handler, options);
  }

  move(state) {
    return state.centroid;
  }
}

Instantiating a Gesture

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.

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

And we also need a handler. This function will be called whenever a gesture hook returns an object. 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.

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.

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.

Adding a Gesture to a Region

Simple:

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:

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

const TIMEOUT = 100;

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

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

  end(state) {
    if (Date.now() - this.startTime <= TIMEOUT) {
      const point = state.getInputsInPhase('end')[0].current.point;
      return { centroid: point, ...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 an object 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.

Default Data Passed to Handlers

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 | null | The centroid of the active 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.

Ending Inputs

State.active, State.activePoints, and the default centroid represent only active inputs. During an end hook, this means that inputs ending in the current event are excluded; when the final input ends, the default centroid is null.

Gestures based on released inputs should read them with state.getInputsInPhase('end'), retain any data they need, and return their own result. A tap gesture, for example, can compute its own centroid from the ending inputs and return it as centroid, as in the example above.

Nomenclature and Origins

In my last year of university, 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!

Contributing

See CONTRIBUTING.md for the development workflow and pull request guidelines.

Links

westures

• npm
• github
• documentation

westures-core

• npm
• github
• documentation