Gesture and Touch Events

Gesture Events

In Tabris.js there are 13 high-level gesture events based on 4 basic gesture types:

Gesture Description
tap Fired once when a finger briefly touched the widget.
longPress Fired when a finger touched the widget for a longer period of time (about a second, may depend on the platform), and again when lifting the finger.
pan Starts firing continuously as soon as a finger moved in any direction for a certain distance (about 5px, may depend on the platform). The event is always fired on the widget where the finger first touched, even if the finger is moved outside the widget.
panLeft Starts firing continuously as soon as a finger moved to the left for a certain distance.
panRight Starts firing continuously as soon as a finger moved to the right for a certain distance.
panUp Starts firing continuously as soon as a finger moved upwards for a certain distance.
panDown Starts firing continuously as soon as a finger moved downwards for a certain distance.
panHorizontal Starts firing continuously as soon as a finger moved to the left or right for a certain distance.
panVertical Starts firing continuously as soon as a finger moved upwards or downwards for a certain distance.
swipeLeft Fired once when a finger quickly moved to the left for a certain (longer) distance (may depend on platform).
swipeRight Fired once when a finger quickly moved to the right for a certain (longer) distance (may depend on platform).
swipeUp Fired once when a finger quickly moved upwards for a certain (longer) distance (may depend on platform).
swipeDown Fired once when a finger quickly moved downwards for a certain (longer) distance (may depend on platform).

All gesture event objects provide (in addition to EventObject API) a touches property which is an array of coordinates, i.e. {x: number, y: number}[]. The x/y values values are DIP (device independent pixel) coordinates relative to the top-left corner of the widget that fires the event.

Example:

widget.onSwipeLeft(ev => console.log(`Swiped left by ${ev.touches[0].x}px`));

Some gesture events also provide a state property of the type string:

State Description
"start" The gesture started, i.e. the finger starts moving (pan) or has been held down long enough (longPress).
"change" The gesture continued by moving a finger (pan only).
"end" The gesture ended by lifting all fingers (pan and longPress).
"cancel" The gesture was interrupted, e.g. by a dialog pop-up (pan and longPress).

Example:

widget.onLongPress(e => {
  if (e.state === 'start') {
    widget.background = 'red';
  } else {
    widget.background = 'transparent';
  }
});

Pan gesture events also contain these additional properties of the type number:

Property Description
translationX Current touch coordinates relative to the coordinates of the first touch
translationY Current touch coordinates relative to the coordinates of the first touch
velocityX Current touch velocity in pixels per second
velocityY Current touch velocity in pixels per second

Gestures in scrollable/panable Widgets

In a scrollable widget, like ScrollView or CollectionView, a recognized pan or swipe gesture in a non-scrollable direction will prevent scrolling. Therefore, attaching a panHorizontal listener to a widget in a vertically scrolling ScrollView, will prevent scrolling for any gesture that starts with a horizontal movement. When no pan listener is attached or the movement starts in a vertical direction, scrolling is still possible.

Touch Events

Touch events are a low-level alternative to gesture events. They should only be used in case an interaction can not be accurately represented by a gesture. The target of all touch events is the widget that was touched first. Available touch event types are:

Event Description
touchStart Fired when a finger touches the widget.
touchMove Fired repeatedly while swiping across the screen after initiating a touchStart event.
touchEnd Fired when the touch interaction ends (i.e. the finger is lifted up) on the same widget that received the touchStart event.
touchCancel Fired instead of touchEnd when the touch interaction ends on another widget than it started.

All touch event objects provide (in addition to EventObject API) a touches property which is an array of “touch” objects providing multiple coordinates as number values representing DIP (device independent pixel).

Touch Property Description
x Horizontal offset of the touch relative to the widget’s left edge.
y Vertical offset of the touch relative to the widget’s top edge.
absoluteX Horizontal offset of the touch relative to its ContentView.
absoluteY Vertical offset of the touch relative to its ContentView.

:point_right: Since multiple touches are currently not supported, the touches array always has one element.

Example:

widget.onTouchStart(ev => {
  const x = ev.touches[0].absoluteX;
  const y = ev.touches[0].absoluteY;
  // ...
});