📺 "One project. One language. Three apps." Learn more in our upcoming code sharing webinar!

NativeScript Core

Gestures

This module allows users to interact with an app via a set of different gestures. NativeScript provides a variety of APIs to help you create gestures.

Overview

Gestures, such as tap, slide and pinch, allow users to interact with your app by manipulating UI elements on the screen. In NativeScript, View (the base class for all NativeScript UI elements) has on and off methods that let you subscribe or unsubscribe to all events and gestures recognized by the UI element. As the first parameter, you pass an on or off method and the type of gesture you want to track. The second parameter is a function that is called each time the specified gesture is recognized. The function arguments contain additional information about the gesture, if applicable.

  • on( type Number | name String | names Comma separated String, callback Function... **)

    • type - Number | name - String | names - Comma separated String
    • callback - Function(args GestureEventData)
  • off( type Number | name String | names Comma separated String, callback Function... **)

    • type - Number | name - String | names - Comma separated String
    • callback - Function(args GestureEventData)

Example

myView.on("tap", () => {
    console.log("myView tapped!");
})
myView.on("tap", () => {
    console.log("myView tapped!");
})

Gestures events can also be implemented directly in the XML layout by providing the callback method.

<StackLayout tap="onTap"/>
exports.onTap = function(args) {
    console.log("Label tapped!");
};
export function onTap(args) {
    console.log("Label tapped!");
};

Double Tap

Action: Two taps in a quick succession.

<Label text="Double Tap me!" doubleTap="onDoubleTap" />
function onDoubleTap(args) {
    // args is of type GesturesEventData
    alert(`${args.eventName} event triggered for ${args.view}`);
}
exports.onDoubleTap = onDoubleTap;
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onDoubleTap(args: GestureEventData) {
    // args is of type GesturesEventDatae
    alert(`${args.eventName} event triggered for ${args.view}`);
}

Possible implementations for doubleTap gesture:

  • Scale up the object with a predefined percentage, centered around the double-tapped region. If a user keeps repeating the double tap gesture, continue to scale up until the maximum scale is reached.
  • Scale up the smallest targetable view or returns it to its original scale in nested views.
  • Select text.

Improve this document

Demo Source


Long Press

Action: Press your finger against the screen for a few moments.

<Label text="Long Press me!" longPress="onLongPress"/>
function onLongPress(args) {
    // args is of type GesturesEventData
    alert(`${args.eventName} gesture event triggered for ${args.view}`);
}
exports.onLongPress = onLongPress;
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onLongPress(args: GestureEventData) {
    // args is of type GesturesEventData
    alert(`${args.eventName} gesture event triggered for ${args.view}`);
}

Possible implementation for longPress gesture:

  • Select one or more items in a view and act upon the data using a contextual action bar.
  • Enter data selection mode.

Tip: Avoid using long press for displaying contextual menus.

Improve this document

Demo Source


Pan

Action: Press your finger down and immediately start moving it around. Pans are executed more slowly and allow for more precision, and the screen stops responding as soon as the finger is lifted off it.

<Label text="Pan me!" pan="onPan"/>
function onPan(args) {
    // args is of type PanGestureEventData
    console.log(`${args.eventName} event triggered for ${args.view}`);
    console.log(`deltaX: ${args.deltaX}`);
    console.log(`deltaY: ${args.deltaY}`);
    console.log(`state: ${args.state}`);

}
exports.onPan = onPan;
import { PanGestureEventData } from "tns-core-modules/ui/gestures";

export function onPan(args: PanGestureEventData) {
    // args is of type PanGestureEventData
    console.log(`${args.eventName} event triggered for ${args.view}`);
    console.log(`deltaX: ${args.deltaX}`);
    console.log(`deltaY: ${args.deltaY}`);
    console.log(`state: ${args.state}`);

}

Possible implementations for pan gesture:

  • Drag'n'Drop functionality

Improve this document

Demo Source


Pinch

Action: Touch the screen using two of your fingers, then move them towards each other or away from each other.

<Label text="Pinch me!" pinch="onPinch" />
function onPinch(args) {
    // args is of type PinchGestureEventData
    console.log(`scale: ${args.scale}`);
    console.log(`tate: ${args.state}`);
    console.log(`getFocusX(): ${args.getFocusX()}`);
    console.log(`getFocusY(): ${args.getFocusY()}`);
}
exports.onPinch = onPinch;
import { PinchGestureEventData } from "tns-core-modules/ui/gestures";

export function onPinch(args: PinchGestureEventData) {
    // args is of type PinchGestureEventData
    console.log(`scale: ${args.scale}`);
    console.log(`tate: ${args.state}`);
    console.log(`getFocusX(): ${args.getFocusX()}`);
    console.log(`getFocusY(): ${args.getFocusY()}`);
}

Possible implementations for pinch gesture:

  • Zoom into content or out of content.

Improve this document

Demo Source


Rotation

Action: Touch the screen using two of your fingers, then rotate them simultaneously left or right.

<Label text="Rotate me!" rotation="onRotation"/>
function onRotation(args) {
    // args is of type RotationGestureEventData
    console.log(`${args.eventName} event triggered for ${args.view}`);
    console.log(`rotation:  ${args.rotation}`);
    console.log(`state:  ${args.state}`);
}
exports.onRotation = onRotation;
import { RotationGestureEventData } from "tns-core-modules/ui/gestures";

export function onRotation(args: RotationGestureEventData) {
    // args is of type RotationGestureEventData
    console.log(`${args.eventName} event triggered for ${args.view}`);
    console.log(`rotation:  ${args.rotation}`);
    console.log(`state:  ${args.state}`);
}

Improve this document

Demo Source


Swipe

Action: Swiftly slide your finger across the screen. Swipes are quick and affect the screen even after the finger is lifted off the screen.

<Label text="Swipe me!" swipe="onSwipe"/>
function onSwipe(args) {
    // args is of type SwipeGestureEventData
    alert(`${args.eventName} event triggered for ${args.view}`);
    console.log(`direction ${args.direction}`); // SwipeDirection enumeration: up, down, left, right
}
exports.onSwipe = onSwipe;
import { SwipeDirection, SwipeGestureEventData } from "tns-core-modules/ui/gestures";

export function onSwipe(args: SwipeGestureEventData) {

    alert(`${args.eventName} event triggered for ${args.view}`);

    let direction: SwipeDirection = args.direction;
    console.log(`direction ${direction}`); // SwipeDirection enumeration: up, down, left, right
}

Possible implementation for swipe gesture:

  • Navigate between views in the same hierarchy.

Improve this document

Demo Source


Tap

Action: Briefly touch the screen.

<Label text="Tap me!" tap="onTap"/>
function onTap(args) {
    // args is of type GestureEventData
    alert(`${args.eventName} event triggered for ${args.view}`);
}
exports.onTap = onTap;
import { GestureEventData } from "tns-core-modules/ui/gestures";

export function onTap(args: GestureEventData) {
    console.log(`${args.eventName} event triggered for ${args.view}`);
    alert(`${args.eventName} event triggered for ${args.view}`);
}

Improve this document

Demo Source


Touch

Action: A finger action was performed.

This is a general purpose gesture that is triggered whenever a pointer (usually a finger) has performed a touch action (up, down, move or cancel). TouchGestureEventData provides information about all the pointers currently on the screen and their position inside the view that triggered the event.

<Label text="Touch me!" touch="onTouch"/>
function onTouch(args) {
    // args is of type TouchGestureEventData
    console.log(`${args.eventName} event triggered for ${args.view}`);
    console.log(args.action); // action: "up" | "move" | "down" | "cancel"
    console.log("getX(): ", args.getX());
    console.log("getY(): ", args.getY());
}
exports.onTouch = onTouch;
import {
    TouchAction,
    TouchGestureEventData
} from "tns-core-modules/ui/gestures";

export function onTouch(args: TouchGestureEventData) {
    console.log(`${args.eventName} event triggered for ${args.view}`);
    let action = args.action;
    switch (action) {
        case TouchAction.cancel:
            console.log("canceled");
            break;
        case TouchAction.down:
            console.log("Down!");
            break;
        case TouchAction.up:
            console.log("Up!");
            break;
        case TouchAction.move:
            console.log("Moving");
            break;
        default:
            break;
    }
    console.log("getX(): ", args.getX());
    console.log("getY(): ", args.getY());
}

Improve this document

Demo Source


API References