The base class for concrete gesture recognizers.
SDKs
- iOS 3.2+
- Mac Catalyst 13.0+
- tvOS 9.0+
Framework
- UIKit
Declaration
@interface UIGestureRecognizer : NSObject
Overview
A gesture-recognizer object—or, simply, a gesture recognizer—decouples the logic for recognizing a sequence of touches (or other input) 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.
The concrete subclasses of UIGesture
are the following:
The UIGesture
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 UIGesture
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 UIView
method add
. 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:
- (void)handleGesture;
- (void)handleGesture:(UIGestureRecognizer *)gestureRecognizer;
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 UIRotation
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 location
or location
.
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 cancels
, delays
, delays
properties:
cancels
—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 (Touches In View touches
) message. If a gesture recognizer doesn’t recognize its gesture, the view receives all touches in the multi-touch sequence.Cancelled: with Event: delays
—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 theTouches Began UITouch
phase 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’sPhase Began touches
method (and possibly a follow-upBegan: with Event: touches
invocation to inform it of the touches current location).Moved: with Event: delays
—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 theTouches Ended UITouch
phase to the attached view. If the gesture recognizer subsequently recognizes its gesture, the touches are cancelled (in aPhase Ended touches
message). If the gesture recognizer doesn’t recognize its gesture, the window delivers these objects in an invocation of the view’sCancelled: with Event: touches
method.Ended: with Event:
Note that "recognize” in the above descriptions doesn’t necessarily equate to a transition to the Recognized state.
Subclassing Notes
You may create a subclass of UIGesture
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 UIGesture
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 (UIGesture
). Discrete gestures transition from Possible to either Recognized (UIGesture
) or Failed (UIGesture
), 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 UIGesture
. (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 ignore
method.
Special Considerations
The state
property is declared in UIGesture
as being read-only. This property declaration is intended for clients of gesture recognizers. Subclasses of UIGesture
must import UIGesture
. This header file contains a redeclaration of state
that makes it read-write.