TouchGesturesModule Overview
TouchGesturesModule Overview
TouchGesturesModule Overview

TouchGesturesModule

Enables detection of touch gestures and exposes classes that describe various types of touch interaction.

By default touch gestures will be registered on the entire screen unless an object is specified in the gesture method call, for example: TouchGestures.onTap(plane).

Importing this module automatically enables the Touch Gestures capability within the project's Properties. Gesture types must be individually enabled within the capability to enable detection.

Example

//============================================================================
// The following example demonstrates how to subscribe to touch events to
// control the rotation, scale, position, material and opacity of a plane.
//
// Project setup:
// - One plane: plane0
//
// Required project capabilities:
// - Touch Gestures >  Pinch Gesture
// - Touch Gestures >  Rotate Gesture
// - Touch Gestures >  Tap Gesture
// - Touch Gestures >  Long Press Gesture
//
//============================================================================

// Load in the required modules
const Scene = require('Scene');
const TouchGestures = require('TouchGestures');
const Diagnostics = require('Diagnostics');

(async function() { // Enable async/await in JS [part 1]


  //==========================================================================
  // Detect pinch gestures that occur on the screen
  //==========================================================================

  // Subscribe to pinch gestures
  TouchGestures.onPinch().subscribe(() => {

    // Code here will run when the pinch gesture is detected anywhere on
    // the screen
  });


  //==========================================================================
  // Detect rotation gestures that occur on a specific object
  //==========================================================================

  // Locate the plane in the scene
  const plane = await Scene.root.findFirst('plane0');

  // Subscribe to rotation gestures that occur on the plane
  TouchGestures.onRotate(plane).subscribe(() => {

    // Code here will run when a rotation gesture is detected on the plane
  });


  //==========================================================================
  // Access properties of a detected gesture
  //==========================================================================

  // Subscribe to tap gestures
  TouchGestures.onTap().subscribe((gesture) => {

    // Access the location property of the TapGesture object via 'gesture'
    const location = gesture.location;

    // Coordinates of the gesture are returned in screen space,
    // for example: [1250, 400]
    Diagnostics.log(location);
  });


  //==========================================================================
  // Configure the options for a detected gesture
  //==========================================================================

  // Subscribe to tap gestures that occur on the plane object, and normalize
  // the coordinates of the gesture location
  TouchGestures.onTap({object: plane, normalizeCoordinates: true})
    .subscribe((gesture) => {

      // Coordinates of the gesture are returned in normalized screen space,
      // for example: [0.95, 0.30]
      Diagnostics.log(gesture.location);
  });


  //==========================================================================
  // Detect when a gesture has ended
  //==========================================================================

  // Subscribe to long press gestures
  TouchGestures.onLongPress().subscribe((gesture) => {

    // Log a message to the console when the gesture begins
    Diagnostics.log("Long press gesture has begun");

    // Subscribe to changes in the value of the gesture state
    gesture.state.monitor().subscribe((state) => {

      // Log a message to the console when the gesture ends
      if (state.newValue == 'ENDED') {
        Diagnostics.log("Long press gesture has ended");

        // Code here will run when the gesture ends
      }
    });
  });

})(); // Enable async/await in JS [part 2]

Properties

This module exposes no properties.

Methods

MethodDescription
onLongPress
onLongPress(options?: SceneObjectBase | {normalizeCoordinates?: false | true, object?: SceneObjectBase}): EventSource<LongPressGesture>


Returns an EventSource that emits a new LongPressGesture object for each long press interaction.
* options - an optional configuration for the long press gesture event. You can either pass in a scene object, or a JSON formatted configuration with additional parameters.

When passing a JSON formatted object as an argument, the following fields are valid:
* object - the object to register long press gestures for. When specified, this event will ignore long press gestures that occur on objects other than object.
* normalizeCoordinates - whether to normalize the coordinates of the registered touch gesture's location. Normalized coordinates return a value between 0 and 1 in each axis.
onPan
onPan(options?: SceneObjectBase | {normalizeCoordinates?: false | true, object?: SceneObjectBase}): EventSource<PanGesture>


Returns an EventSource that emits a new PanGesture object for each pan interaction.
* options - an optional configuration for the pan gesture event. You can either pass in a scene object, or a JSON formatted configuration with additional parameters.

When passing a JSON formatted object as an argument, the following fields are valid:
* object - the object to register pan gestures for. When specified, this event will ignore pan gestures that occur on objects other than object.
* normalizeCoordinates - whether to normalize the coordinates of the registered touch gesture's location. Normalized coordinates return a value between 0 and 1 in each axis.
onPinch
onPinch(options?: SceneObjectBase | {normalizeCoordinates?: false | true, object?: SceneObjectBase}): EventSource<PinchGesture>


Returns an EventSource that emits a new PinchGesture object for each pinch interaction.
* options - an optional configuration for the pinch gesture event. You can either pass in a scene object, or a JSON formatted configuration with additional parameters.

When passing a JSON formatted object as an argument, the following fields are valid:
* object - the object to register pinch gestures for. When specified, this event will ignore pinch gestures that occur on objects other than object.
* normalizeCoordinates - whether to normalize the coordinates of the registered touch gesture's location. Normalized coordinates return a value between 0 and 1 in each axis.
onRotate
onRotate(options?: SceneObjectBase | {normalizeCoordinates?: false | true, object?: SceneObjectBase}): EventSource<RotateGesture>


Returns an EventSource that emits a new RotateGesture object for each rotation interaction.
* options - an optional configuration for the rotation gesture event. You can either pass in a scene object, or a JSON formatted configuration with additional parameters.

When passing a JSON formatted object as an argument, the following fields are valid:
* object - the object to register rotation gestures for. When specified, this event will ignore rotation gestures that occur on objects other than object.
* normalizeCoordinates - whether to normalize the coordinates of the registered touch gesture's location. Normalized coordinates return a value between 0 and 1 in each axis.
onTap
onTap(options?: SceneObjectBase | {normalizeCoordinates?: false | true, object?: SceneObjectBase}): EventSource<TapGesture>


Returns an EventSource that emits a new TapGesture object for each tap interaction.
* options - an optional configuration for the tap gesture event. You can either pass in a scene object, or a JSON formatted configuration with additional parameters.

When passing a JSON formatted object as an argument, the following fields are valid:
* object - the object to register tap gestures for. When specified, this event will ignore tap gestures that occur on objects other than object.
* normalizeCoordinates - whether to normalize the coordinates of the registered touch gesture's location. Normalized coordinates return a value between 0 and 1 in each axis.

Classes

ClassDescription
GestureExposes details of a detected gesture, common to all touch gesture types.
LongPressGestureExposes details of a detected long press gesture.
PanGestureExposes details of a detected pan gesture.
PinchGestureExposes details of a detected pinch gesture.
RotateGestureExposes details of a detected rotation gesture.
TapGestureExposes details of a detected tap gesture.

Enums

EnumDescription
GestureTypeThe GestureType enum describes the type of a given Gesture.

Was this article helpful?