Gestures Library Overview

The Gestures library provides gesture recognizers to detect gestures through touch events that occur when you place one or more fingers on a touch screen.

What are gestures?

A gesture is an interaction between users and your application through a touch screen.

Tap

One touch with one finger.

Double tap

Two touches in quick succession with one finger.

Triple tap

Three touches in quick succession with one finger.

Long press

One touch with a pause before releasing.

Press and tap

One long press with one finger, followed by a touch with a second finger.

Two-finger tap

One touch with two fingers.

Swipe

One continuous horizontal or vertical motion consisting of a tap, a movement, and a release with one finger.

Pinch

One continuous motion consisting of a two-finger tap, a movement inward or outward, and a release.

Rotate

One long press with one finger, followed shortly by a swipe in an arc by your second finger

Two-finger pan

One continuous motion consisting of a long press, a movement, and a release with two fingers

There are two classes of gestures:

Composite
A composite (also called transform or continuous) gesture is one that may send multiple notifications to the application as you continue to touch or move your fingers on the screen. The composite gestures are:
  • Swipe
  • Pinch
  • Rotate
  • Two-finger pan
Discrete
Discrete gestures send only a single notification to the application. The discrete gestures are:
  • Tap
  • Double tap
  • Triple tap
  • Long press
  • Press and tap
  • Two-finger tap

What are gesture recognizers?

A gesture recognizer is a self-contained state machine. It progresses through its various states in reaction to the touch events that it receives. Depending on the gesture, a gesture recognizer may need to interpret single- or multiple-touch events in order to detect a single gesture. That is, a gesture recognizer could transition through multiple states before being able to determine the gesture that the user intended. Once the gesture recognizer detects a gesture, its gesture callback is invoked. It is the responsibility of your application to handle the detected gesture in your gesture callback function. In the context of the Gestures library, you will see that the gesture recognizers are simply referred to as gestures.

Gesture recognizers for some of the widely used gestures are already provided for you by the Gestures library:

Gesture Recognizer Gesture class Uses timer(s)
Tap Discrete
Double tap Discrete
Triple tap Discrete
Long press Discrete
Press and tap Discrete
Two-finger tap Discrete
Swipe Composite
Pinch Composite
Rotate Composite
Two-finger pan Composite

Some gesture recognizers use timers as part of their detection of gestures. If you need to detect a gesture that isn't supported by the Gestures library, you can define your own gesture recognizer.

What are touch events?

Touch events are events generated by the touch controller. In the Gestures library, touch events are represented by the data structure mtouch_event_t. mtouch_event_t contains various types of information about the touch event, such as the type of touch event (touch, move, or release), the timestamp of the event, the coordinates of the touch, and so on. Touch events that are represented by this data structure are referred to as mtouch events. See the file input/event_types.h for more information.

What are gesture sets?

A gesture set is a set of gesture recognizers; it can detect multiple types of gestures. Your application defines a gesture set by allocating, to the set, the gesture recognizers that detect the gestures that are of interest to you.

You can think of a gesture set as the interface between gesture recognizers and the application. The application sends mtouch events to a gesture set, not to individual gesture recognizers. Individual gesture recognizers must belong to a gesture set to be able to receive mtouch events and invoke callback functions when the gesture recognizer state transitions happen.

Inter-gesture recognizer relationships and dependencies are to be managed completely by the gesture set. Therefore, individual gesture recognizers are simple to implement and allow the application to customize the desired gesture-recognizer relationships for its own needs. Also, applications that are interested only in a small subset of gestures can choose its gesture recognizers of interest.

A gesture set handles all that is required of the state transition. Examples of what the gesture set handles are:

  • invoking the gesture recognizer callback function when valid
  • resetting each gesture recognizer when all those in the gesture set have transitioned to either GESTURE_STATE_COMPLETE or GESTURE_STATE_FAILED
  • managing failure dependencies between gesture recognizers
  • timer handling for gesture recognizers that need timer events (as opposed to mtouch events)
  • failure notification when all gestures recognizers in a set have transitioned to GESTURE_STATE_FAILED
For information about: See:
Recognizing gestures

Gesture recognition

Simultaneous recognition

State transitions of gesture recognizers State transitions
The gesture callback Callback invocation
Timers

Timer support

Timer callback

Failures

Failure dependencies

Failure notifications

Resets Reset
Defining your own gesture recognizer Custom gestures
Tutorials Gestures Tutorials
What's in the Gestures library? Gestures Library Reference