UIGestureRecognizer

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 UIGestureRecognizer are the following:

• UITapGestureRecognizer

• UIPinchGestureRecognizer

• UIRotationGestureRecognizer

• UISwipeGestureRecognizer

• UIPanGestureRecognizer

• UIScreenEdgePanGestureRecognizer

• UILongPressGestureRecognizer

The 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 UIView method 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:

- (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 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 locationInView: or locationOfTouch:inView:.

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, delaysTouchesBegan, delaysTouchesEnded properties:

• 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:withEvent:) 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 UITouchPhaseBegan 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’s touchesBegan:withEvent: method (and possibly a follow-up touchesMoved:withEvent: 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 UITouchPhaseEnded phase to the attached view. If the gesture recognizer subsequently recognizes its gesture, the touches are cancelled (in a touchesCancelled:withEvent: message). If the gesture recognizer doesn’t recognize its gesture, the window delivers these objects in an invocation of the view’s touchesEnded:withEvent: method.

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 (UIGestureRecognizerStatePossible). Discrete gestures transition from Possible to either Recognized (UIGestureRecognizerStateRecognized) or Failed (UIGestureRecognizerStateFailed), 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.

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 ignoreTouch:forEvent: method.

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.