Device agnostic touch handling.

Usage

Require this module doing either

angular.module('myApp', ['mobile-angular-ui.gestures']);

Or standalone

angular.module('myApp', ['mobile-angular-ui.gestures.touch']);

Then you will be able to use the $touch service like that:

var unbindFn = $touch.bind(element, {
   start: function(touchInfo, e);
   move: function(touchInfo, e);
   end: function(touchInfo, e);
   cancel: function(touchInfo, e);
}, options);

Services

$touch service

  • $touchProvider - class
  • TouchInfo - class
  • bind - method

$touch is an abstraction of touch event handling that works with any kind of input devices.

It is intended for single touch only and provides extended infos about touch like: movement, direction, velocity, duration, and more. $touch service is intended as base to build any single-touch gesture handlers.

Usage

var unbindFn = $touch.bind(element, {
   start: function(touchInfo, e);
   move: function(touchInfo, e);
   end: function(touchInfo, e);
   cancel: function(touchInfo, e);
}, options);

Provider in $touch

$touchProvider
class in $touch

Configurable provider for $touch service

Methods

setValid
method in $touchProvider

$touchProvider.setValid(validityFunction)

Set default validity function for a touch.

The default is defined as always true:

$touchProvider.setValid(function(touch, event) {
  return true;
});
ParamTypeDescription
validityFunctionfunction

The validity function. A function that takes two arguments: touchInfo and event, and returns a Boolean indicating wether the corresponding touch should be considered valid and its handlers triggered, or considered invalid and its handlers be ignored.

setMovementThreshold
method in $touchProvider

$touchProvider.setMovementThreshold(threshold)

Set default amount of pixels of movement before start to trigger touchmove handlers.

Default is 1.

ie.

$touchProvider.setMovementThreshold(120);
ParamTypeDescription
thresholdinteger

The new treeshold.

setSensitiveArea
method in $touchProvider

$touchProvider.setSensitiveArea(sensitiveArea)

Set default sensitive area.

The sensitive area of a touch is the area of the screen inside what we consider a touch to be meaningful thus triggering its handlers.

NOTE: if movement goes out the sensitive area the touch event is not cancelled, instead its handler are just ignored.

By default sensitive area is defined as ownerDocument bounding rectangle of the bound element.

ie.

$touchProvider.setSensitiveArea(function($element) {
  return $element[0].ownerDocument.documentElement.getBoundingClientRect();
});
ParamTypeDescription
sensitiveAreafunction | Element | TextRectangle

The new default sensitive area, either static or as function taking an element and returning another element or a rectangle.

Methods in $touch

bind
method in $touch

$touch.bind(element, eventHandlers, [options]) ⟶ function

Bind touch handlers for an element.

var unbind = $touch.bind(elem, {
  end: function(touch) {
    console.log('Avg Speed:', touch.averageVelocity);
    unbind();
  }
});
ParamTypeDescription
elementElement | $element

The element to bound to.

eventHandlersobject

An object with handlers for specific touch events.

[eventHandlers.start]function

The callback for touchstart event.

[eventHandlers.end]function

The callback for touchend event.

[eventHandlers.move]function

The callback for touchmove event.

[eventHandlers.cancel]function

The callback for touchcancel event.

[options]object

Options.

[options.movementThreshold]integer

Amount of pixels of movement before start to trigger touchmove handlers.

[options.valid]function

Validity function. A function(TouchInfo, event)⟶boolean deciding if a touch should be handled or ignored.

[options.sensitiveArea]function | Element | TextRectangle

A Bounding Client Rect or an element or a function that takes the bound element and returns one of the previous. Sensitive area define bounduaries to release touch when movement is outside.

[options.pointerTypes]array

Pointer types to handle. An array of pointer types that is intended to be a subset of keys from default pointer events map (see $touchProvider.setPointerEvents).

Types in $touch

TouchInfo
class in $touch

TouchInfo is an object containing the following extended informations about any touch event.

Properties
PropTypeDescription
typestring

Normalized event type. Despite of pointer device is always one of touchstart, touchend, touchmove, touchcancel.

timestampDate

The time object corresponding to the moment this touch event happened.

durationinteger

The difference between this touch event and the corresponding touchstart.

startXfloat

X coord of related touchstart.

startYfloat

Y coord of related touchstart.

prevXfloat

X coord of previous touchstart or touchmove.

prevYfloat

Y coord of previous touchstart or touchmove.

xfloat

X coord of this touch event.

yfloat

Y coord of this touch event.

stepfloat

Distance between [prevX, prevY] and [x, y] points.

stepXfloat

Distance between prevX and x.

stepYfloat

Distance between prevY and y.

velocityfloat

Instantaneous velocity of a touch event in pixels per second.

averageVelocityfloat

Average velocity of a touch event from its corresponding touchstart in pixels per second.

distancefloat

Distance between [startX, startY] and [x, y] points.

distanceXfloat

Distance between startX and x.

distanceYfloat

Distance between startY and y.

totalfloat

Total number of pixels covered by movement, taking account of direction changes and turnarounds.

totalXfloat

Total number of pixels covered by horizontal movement, taking account of direction changes and turnarounds.

totalYfloat

Total number of pixels covered by vertical, taking account of direction changes and turnarounds.

directionstring

The current prevalent direction for this touch, one of LEFT, RIGHT, TOP, BOTTOM.

anglefloat

Angle in degree between x axis and the vector [x, y], is null when no movement happens.

comments powered by Disqus