Scripting Object Reference
TouchGesturesModule
TouchGesturesModule Overview

TouchGesturesModule

The TouchGesturesModule class enables touch gesture detection.

Example

//==============================================================================
// The following example demonstrates how to subscribe to all touch events to
// control the rotation, scale, position, material and opacity of a plane.
//
// Project setup:
// - Insert a plane
// - Increase the x and y-axis scale values of the plane to 2
// - Create two materials with different colors
// - Assign one of the materials to the plane
// - Enable all Touch Gestures under the Touch Gesture capability
//==============================================================================

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

// Enable async/await in JS [part 1]
(async function() {
  // Locate the plane in the Scene
  // and the materials in the Assets
  const [plane, material, material2] = await Promise.all([
    Scene.root.findFirst('plane0'),
    Materials.findFirst('defaultMaterial0'),
    Materials.findFirst('defaultMaterial1')
  ]);

  //==============================================================================
  // Change the material applied to the plane when the plane is tapped
  //==============================================================================

  var isFirstMaterialSelected = true;

  // Subscribe to tap gestures on the plane
  TouchGestures.onTap(plane).subscribe((gesture) => {
    // Switch materials depending on which one is currently applied to the plane
    if (isFirstMaterialSelected) {
      plane.material = material2;
      isFirstMaterialSelected = false;
    } else {
      plane.material = material;
      isFirstMaterialSelected = true;
    }
  });

  //==============================================================================
  // Make the plane's material transparent when the plane is long pressed
  //==============================================================================

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

    // Set the opacity to 50%
    plane.material.opacity = 0.5;

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

      // Return the opacity to 100% when the gesture ends
      if (state.newValue !== 'BEGAN' && state.newValue !== 'CHANGED') {
        plane.material.opacity = 1;
      }

    });

  });

  //==============================================================================
  // Move the plane across the screen when dragging it with a finger
  //==============================================================================

  // Store a reference to the transform of the plane
  const planeTransform = plane.transform;

  // Subscribe to pan gestures on the plane
  TouchGestures.onPan(plane).subscribe((gesture) => {

    // Translate the position of the finger on the screen to the plane's
    // co-ordinate system
    const gestureTransform = Scene.unprojectToFocalPlane(gesture.location);

    // Update the position of the plane
    planeTransform.x = gestureTransform.x;
    planeTransform.y = gestureTransform.y;

  });

  //==============================================================================
  // Scale the plane when pinching it with two fingers
  //==============================================================================

  // Subscribe to pinch gestures on the plane
  TouchGestures.onPinch(plane).subscribe((gesture) => {

    // Store the last known x and y-axis scale values of the plane
    const lastScaleX = planeTransform.scale.x.pinLastValue();
    const lastScaleY = planeTransform.scale.y.pinLastValue();

    // Update the scale of the plane by multiplying the last known scale with the
    // scale returned by the gesture
    planeTransform.scaleX = gesture.scale.mul(lastScaleX);
    planeTransform.scaleY = gesture.scale.mul(lastScaleY);

  });

  //==============================================================================
  // Rotate the plane when rotating it with two fingers
  //==============================================================================

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

    // Store the last known z-axis rotation value of the plane
    const lastRotationZ = planeTransform.rotationZ.pinLastValue();

    // Update the z-axis rotation of the plane by adding the gesture rotation and
    // multiply it by -1 to have it rotate in the correct direction
    planeTransform.rotationZ = gesture.rotation.mul(-1).add(lastRotationZ);

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

Properties

This module exposes no properties.

Methods

MethodDescription
onLongPress
onLongPress(): EventSource
onLongPress(object: SceneObjectBase): EventSource
onLongPress(options: {object?: SceneObjectBase, normalizeCoordinates?: boolean}): EventSource


Returns an [EventSource](/docs/camera-effects/reference/reactive_module/eventsource_class), to which you may subscribe, that emits a [LongPressGesture](/docs/camera-effects/reference/touchgestures_module/longpressgesture_class) object for each long-press interaction.

When object is specified, only events for the specified object are emitted.
onPan
onPan(): EventSource
onPan(object: SceneObjectBase): EventSource
onPan(options: {object?: SceneObjectBase, normalizeCoordinates?: boolean}): EventSource


Returns an [EventSource](/docs/camera-effects/reference/reactive_module/eventsource_class), to which you may subscribe, that emits a [PanGesture](/docs/camera-effects/reference/touchgestures_module/pangesture_class) object for each pan interaction.

When object is specified, only events for the specified object are emitted.
onPinch
onPinch(): EventSource
onPinch(object: SceneObjectBase): EventSource
onPinch(options: {object?: SceneObjectBase, normalizeCoordinates?: boolean}): EventSource


Returns an [EventSource](/docs/camera-effects/reference/reactive_module/eventsource_class), to which you may subscribe, that emits a [PinchGesture](/docs/camera-effects/reference/touchgestures_module/pinchgesture_class) object for each pinch interaction.

When object is specified, only events for the specified object are emitted.
onRotate
onRotate(): EventSource
onRotate(object: SceneObjectBase): EventSource
onRotate(options: {object?: SceneObjectBase, normalizeCoordinates?: boolean}): EventSource


Returns an [EventSource](/docs/camera-effects/reference/reactive_module/eventsource_class), to which you may subscribe, that emits a [RotateGesture](/docs/camera-effects/reference/touchgestures_module/rotategesture_class) object for each rotate interaction.

When object is specified, only events for the specified object are emitted.
onTap
onTap(): EventSource
onTap(object: SceneObjectBase): EventSource
onTap(options: {object?: SceneObjectBase, normalizeCoordinates?: boolean}): EventSource


Returns an [EventSource](/docs/camera-effects/reference/reactive_module/eventsource_class), to which you may subscribe, that emits a [TapGesture](/docs/camera-effects/reference/touchgestures_module/tapgesture_class) object for each tap interaction.

When object is specified, only events for the specified object are emitted.

Classes

ClassDescription
GestureThe Gesture class encapsulates details of a detected gesture.
LongPressGestureThe LongPressGesture class contains the details of a detected long-press gesture.
PanGestureThe PanGesture class contains the details of a detected pan gesture.
PinchGestureThe PinchGesture class contains the details of a detected pinch gesture.
RawTouchGestureThe RawTouchGesture class encapsulates raw touch data.
RotateGestureThe RotateGesture class contains the details of a detected rotate gesture.
TapGestureThe TapGesture class contains the details of a detected tap gesture.