Gesture Events

Article
10/20/2016

Gesture events are built on top of the W3C Pointer Events model. Use gesture events to help recognize and respond to more complex touch-based user interactions (such as pinch, rotate, swipe, and drag) without having to capture and interpret individual pointer events yourself.

Note The APIs we discuss in this section aren't supported in Windows 7 or earlier.

Gesture events and the MSGesture object

The first step for handling gestures in your site is to instantiate a gesture object.

var myGesture = new MSGesture();

Next, give the gesture a target element. This is the element to which the browser will fire gesture events. It’s also the element that determines the coordinate space for the events.

elm = document.getElementById("someElement");
myGesture.target = elm;
elm.addEventListener("MSGestureChange", handleGesture);

Finally, tell the gesture object which pointers to process in its gesture recognition.

elm.addEventListener("pointerdown", function (evt) {
// adds the current mouse, pen, or touch contact for gesture recognition
myGesture.addPointer(evt.pointerId);
});

Note Use touchAction Cascading Style Sheets (CSS) property to configure the element so it doesn't perform default touch actions like panning and zooming, and instead provide pointer events for the input. See Controlling the default touch experience for more details.

Handling gesture events

Once a gesture object has a valid target and at least one pointer added to it, it starts to fire gesture events. The MSGestureEvent object that's dispatched upon these events contains information about scale (pinch), rotation, translation, and velocity. Its detail property contains additional information about the status of the gesture event in the form of a bitmask of flags:

Gesture flag	Value	Description
MSGESTURE_FLAG_NONE	0	Normal status.
MSGESTURE_FLAG_BEGIN	1	The gesture event has started.
MSGESTURE_FLAG_END	2	The gesture event has ended.
MSGESTURE_FLAG_CANCEL	4	The gesture event has been cancelled. This often comes ANDed with MSGESTURE_FLAG_END.
MSGESTURE_FLAG_INERTIA	8	The gesture is in its inertia phase. This flag is continuously sent through a MSGestureChange event while an element on the screen is moving.

For more info, see the "Remarks" section of the Gesture flags reference.

Simple and complex gestures

Gesture events can either be simple (like tap or hold) or complex (like pinch, rotate, or swipe).

Tap

The most basic gesture recognition is a tap. When a tap is detected, the MSGestureTap event is fired at the target element of the gesture object. Different from the click event, the tap gesture only fires when a user touches (or presses a mouse button, or touches a pen) down and up without moving. This is useful if you want to differentiate between a user tapping on an element versus dragging the element.

Press and hold

A press and hold gesture happens when a user touches down with one finger, holds for a moment, and lifts without moving. During a press and hold interaction, the MSGestureHold event fires more than one time for the various states of the gesture:

element.addEventListener("MSGestureHold", handleHold);
function handleHold(evt) {
if (evt.detail & evt.MSGESTURE_FLAG_BEGIN) {
// Begin signals the start of a gesture. For the hold gesture, this means the user has been holding long enough in place that the gesture will become a complete press & hold if the finger is lifted.
}
if (evt.detail & evt.MSGESTURE_FLAG_END) {
// End signals the end of the gesture.
}
if (evt.detail & evt.MSGESTURE_FLAG_CANCEL) {
// Cancel signals the user started the gesture but cancelled it. For hold, this occurs when the user drags away before lifting. This flag is sent together with the End flag, signaling the gesture recognition is complete.
}
}

Complex gestures (pinch, rotate, swipe, and drag)

Dynamic gestures, like pinch or rotate, are reported in the form of transforms similar to CSS2D Transforms. Three events are fired for dynamic gestures: MSGestureStart, MSGestureChange (fires repeatedly as the gesture continues), and MSGestureEnd.

Because dynamic gestures report transforms, it’s easy to use MSGesture with CSS 2D transforms to manipulate an element like a photo or puzzle piece. You can enable scaling, rotating, and dragging of an element using code similar to this:

targetElement.addEventListener("MSGestureChange", manipulateElement);
function manipulateElement(e) {
// Uncomment the following code if you want to disable the built-in inertia provided by dynamic gesture recognition
// if (e.detail == e.MSGESTURE_FLAG_INERTIA)
// return;
 
var m = new MSCSSMatrix(e.target.style.transform); // Get the latest CSS transform on the element
e.target.style.transform = m
.translate(e.offsetX, e.offsetY) // Move the transform origin under the center of the gesture
.rotate(e.rotation * 180 / Math.PI) // Apply Rotation
.scale(e.scale) // Apply Scale
.translate(e.translationX, e.translationY) // Apply Translation
.translate(-e.offsetX, -e.offsetY); // Move the transform origin back
}

Dynamic gestures like scale and rotate are supported with mouse by rotating the mouse wheel with the CTRL or SHIFT modifier keys, respectively.

About inertia

Inertia is movement that continues after you remove the contact with the screen. Inertia support is built into gesture objects and doesn't require additional code other than handlers for the events. The MSInertiaStart event is followed by a series of MSGestureChange events, depending on the speed of the swipe, before an MSGestureEnd event is fired. The MSInertiaStart event fires only when there's enough speed to a swipe and can help your code differentiate between a slow move and a quick flick.