UIGestureRecognizer is an abstract base class for concrete gesture-recognizer classes. A gesture-recognizer object—or, simply, a gesture recognizer—decouples the logic for recognizing a gesture and acting on that recognition. When one of these objects recognizes a common gesture or, in some cases, a change in the gesture, it sends an action message to each designated target object.
- iOS 3.2+
- tvOS 3.2+
The concrete subclasses of
UIGestureRecognizer are the following:
UIGestureRecognizer class defines a set of common behaviors that can be configured for all concrete gesture recognizers. It can also communicate with its delegate (an object that adopts the
UIGestureRecognizerDelegate protocol), thereby enabling finer-grained customization of some behaviors.
A gesture recognizer operates on touches hit-tested to a specific view and all of that view’s subviews. It thus must be associated with that view. To make that association you must call the
addGestureRecognizer(_:). A gesture recognizer doesn’t participate in the view’s responder chain.
A gesture recognizer has one or more target-action pairs associated with it. If there are multiple target-action pairs, they are discrete, and not cumulative. Recognition of a gesture results in the dispatch of an action message to a target for each of the associated pairs. The action methods invoked must conform to one of the following signatures:
Methods conforming to the latter signature permit the target in some cases to query the gesture recognizer sending the message for additional information. For example, the target could ask a
UIRotationGestureRecognizer object for the angle of rotation (in radians) since the last invocation of the action method for this gesture. Clients of gesture recognizers can also ask for the location of a gesture by calling
The gesture interpreted by a gesture recognizer can be either discrete or continuous. A discrete gesture, such as a double tap, occurs but once in a multi-touch sequence and results in a single action sent. However, when a gesture recognizer interprets a continuous gesture such as a rotation gesture, it sends an action message for each incremental change until the multi-touch sequence concludes.
A window delivers touch events to a gesture recognizer before it delivers them to the hit-tested view attached to the gesture recognizer. Generally, if a gesture recognizer analyzes the stream of touches in a multi-touch sequence and doesn’t recognize its gesture, the view receives the full complement of touches. If a gesture recognizer recognizes its gesture, the remaining touches for the view are cancelled. The usual sequence of actions in gesture recognition follows a path determined by default values of the
cancelsTouchesInView—If a gesture recognizer recognizes its gesture, it unbinds the remaining touches of that gesture from their view (so the window won’t deliver them). The window cancels the previously delivered touches with a (
touchesCancelled(_:with:)) message. If a gesture recognizer doesn’t recognize its gesture, the view receives all touches in the multi-touch sequence.
delaysTouchesBegan—As long as a gesture recognizer, when analyzing touch events, has not failed recognition of its gesture, the window withholds delivery of touch objects in the
beganphase to the attached view. If the gesture recognizer subsequently recognizes its gesture, the view doesn’t receive these touch objects. If the gesture recognizer doesn’t recognize its gesture, the window delivers these objects in an invocation of the view’s
touchesBegan(_:with:)method (and possibly a follow-up
touchesMoved(_:with:)invocation to inform it of the touches current location).
delaysTouchesEnded—As long as a gesture recognizer, when analyzing touch events, has not failed recognition of its gesture, the window withholds delivery of touch objects in the
endedphase to the attached view. If the gesture recognizer subsequently recognizes its gesture, the touches are cancelled (in a
touchesCancelled(_:with:)message). If the gesture recognizer doesn’t recognize its gesture, the window delivers these objects in an invocation of the view’s
Note that "recognize” in the above descriptions doesn’t necessarily equate to a transition to the Recognized state.
You may create a subclass of
UIGestureRecognizer that recognizes a distinctive gesture—for example, a “check mark” gesture. If you are going to create such a concrete gesture recognizer, be sure to import the
UIGestureRecognizerSubclass.h header file. This header file declares all the methods and properties a subclass must either override, call, or reset.
Gesture recognizers operate within a predefined state machine, transitioning to subsequent states as they handle multi-touch events. The states and their possible transitions differ for continuous and discrete gestures. All gesture recognizers begin a multi-touch sequence in the Possible state (
possible). Discrete gestures transition from Possible to either Recognized (
recognized) or Failed (
failed), depending on whether they successfully interpret the gesture or not. If the gesture recognizer transitions to Recognized, it sends its action message to its target.
For continuous gestures, the state transitions a gesture recognizer might make are more numerous, as indicated in the following diagram:
Possible ----> Began ----> [Changed] ----> Cancelled
Possible ----> Began ----> [Changed] ----> Ended
The Changed state is optional and may occur multiple times before the Cancelled or Ended state is reached. The gesture recognizer sends action messages at each state transition. Thus for a continuous gesture such as a pinch, action messages are sent as the two fingers move toward or away from each other. The
enum constants representing these states are of type
UIGestureRecognizerState. (Note that the constants for Recognized and Ended states are synonymous.)
Subclasses must set the
state property to the appropriate value when they transition between states.
Methods to Override
The methods that subclasses must override are described in Methods for Subclasses. Subclasses must also periodically reset the
state property (as described above) and may call the
state property is declared in
UIGestureRecognizer.h as being read-only. This property declaration is intended for clients of gesture recognizers. Subclasses of
UIGestureRecognizer must import
UIGestureRecognizerSubclass.h. This header file contains a redeclaration of
state that makes it read-write.