Gesture Recognizer Overview

This document describes the process by which Touch Events received by a root window are transformed into Gesture Events.

Contents

1 Gesture Recognizer Overview
2 Finding a Target
1. 2.1 Possible ways of establishing a target
2. 2.2 Complications
  1. 2.2.1 preventDefault’ed Release
  2. 2.2.2 Touch Capture
3 Generating Gesture Events
1. 3.1 Gesture Sequences
2. 3.2 Gesture Sequence State Machine
4 Where To Start

Touch Events

Type: Press, Move, Release, Cancel
Location
Timestamp
Touch id: Assigned on touch Press, unassigned on touch Release or Cancel

Gesture Events

Tap Down
Tap
Double Tap
Long Press
Three Fingered Swipe

Associated Direction

Scroll Begin
Scroll Update

Associated change in position

Scroll End

Associated velocity, for fling

Pinch Begin
Pinch Update

Associated scale

Pinch End

Associated scale

Two Finger Tap

Terminology

Touch Lock:

The association between an existing touch and its target.

Touch Capture:

If a window is capturing touches, new touches will be targetted at the capturing window.

Touch Id:

The global id given to each touch. Contiguous starting at 0, but not contiguous within a Gesture Sequence.

Point Id:

The id of a touch local to a Gesture Sequence. Contiguous starting at 0.

Rail Scroll:

A scroll which is locked to only move vertically or horizontally.

Fling:

When scrolling, if the user releases their fingers, but the scroll should continue, this is known as a fling.

Finding a Target

Possible ways of establishing a target

If a touch is already locked to a target, keep it.
If a window is capturing touches, target that window.
If it's outside the root window, target the root window.
If it's near another touch, use the other touch's target.
Otherwise, use whichever window the touch is above.

In the following images, a filled in circle represents a touch down, and the outline of a circle represents a position the touch has moved to. The dotted green line indicates the window that a touch is targeted at. The rounded rectangle represents a window, and the outer rectangle represents the root window.

1. If a touch is already locked to a target, keep it.	2. If a window is capturing touches, target that window.
3. If it's outside the root window, target the root window.	4. If it's near another touch, use the other touch's target.
5. Otherwise, use whichever window the touch is above.

Complications

preventDefault’ed Release

When Javascript calls preventDefault on a touch release, we need to make sure that no gesture events are created, but we also need to ensure that the GestureRecognizer knows that the associated finger isn’t down any more. To accomplish this, we turn the touch release into a touch cancel event.

Touch Capture

When a touch capture occurs, all touches on windows other than the window gaining capture need to be ignored until they are released. To do this, we fire a touch cancel for each of these touches, and retarget them to a dummy window, which ignores all further events.

Generating Gesture Events

Gesture Sequences

Each touch-id has an associated window, and each window has an associated GestureSequence.

Inside a GestureSequence, touches are renumbered with point-ids, which are local to the GestureSequence, and contiguous from 0 to the number of touches.

Gesture Sequence State Machine

The GestureSequence state machine starts in state GS_NO_GESTURE. In the diagram below, a transition labelled XN indicates that the N'th finger took action X.