iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIGestureRecognizer Class Reference

Options
Deployment Target:

On This Page
Language:

UIGestureRecognizer

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. More...

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.2 and later.
  • Initializes an allocated gesture-recognizer object with a target and an action selector.

    Declaration

    Swift

    init(target target: AnyObject, action action: Selector)

    Objective-C

    - (instancetype)initWithTarget:(id)target action:(SEL)action

    Parameters

    target

    An object that is the recipient of action messages sent by the receiver when it recognizes a gesture. nil is not a valid value.

    action

    A selector that identifies the method implemented by the target to handle the gesture recognized by the receiver. The action selector must conform to the signature described in the class overview. NULL is not a valid value.

    Return Value

    An initialized instance of a concrete UIGestureRecognizer subclass or nil if an error occurred in the attempt to initialize the object.

    Discussion

    This method is the designated initializer. After creating the gesture recognizer, you may associate other target-action pairs with it by calling addTarget:action:.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Adds a target and an action to a gesture-recognizer object.

    Declaration

    Swift

    func addTarget(_ target: AnyObject, action action: Selector)

    Objective-C

    - (void)addTarget:(id)target action:(SEL)action

    Parameters

    target

    An object that is a recipient of action messages sent by the receiver when the represented gesture occurs. nil is not a valid value.

    action

    A selector identifying a method of a target to be invoked by the action message. NULL is not a valid value.

    Discussion

    You may call this method multiple times to specify multiple target-action pairs. However, if you request to add a target-action pair that has already been added, then the request is ignored.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Removes a target and an action from a gesture-recognizer object.

    Declaration

    Swift

    func removeTarget(_ target: AnyObject?, action action: Selector)

    Objective-C

    - (void)removeTarget:(id)target action:(SEL)action

    Parameters

    target

    An object that currently is a recipient of action messages sent by the receiver when the represented gesture occurs. Specify nil if you want to remove all targets from the receiver.

    action

    A selector identifying a method of a target to be invoked by the action message. Specify NULL if you want to remove all actions from the receiver.

    Discussion

    Calling this method removes the specified target-action pair. Passing nil for target matches all targets and passing NULL for action matches all actions.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Returns the point computed as the location in a given view of the gesture represented by the receiver.

    Declaration

    Swift

    func locationInView(_ view: UIView?) -> CGPoint

    Objective-C

    - (CGPoint)locationInView:(UIView *)view

    Parameters

    view

    A UIView object on which the gesture took place. Specify nil to indicate the window.

    Return Value

    A point in the local coordinate system of view that identifies the location of the gesture. If nil is specified for view, the method returns the gesture location in the window’s base coordinate system.

    Discussion

    The returned value is a generic single-point location for the gesture computed by the UIKit framework. It is usually the centroid of the touches involved in the gesture. For objects of the UISwipeGestureRecognizer and UITapGestureRecognizer classes, the location returned by this method has a significance special to the gesture. This significance is documented in the reference for those classes.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Returns the location of one of the gesture’s touches in the local coordinate system of a given view.

    Declaration

    Swift

    func locationOfTouch(_ touchIndex: Int, inView view: UIView?) -> CGPoint

    Objective-C

    - (CGPoint)locationOfTouch:(NSUInteger)touchIndex inView:(UIView *)view

    Parameters

    touchIndex

    The index of a UITouch object in a private array maintained by the receiver. This touch object represents a touch of the current gesture.

    view

    A UIView object on which the gesture took place. Specify nil to indicate the window.

    Return Value

    A point in the local coordinate system of view that identifies the location of the touch. If nil is specified for view, the method returns the touch location in the window’s base coordinate system.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Returns the number of touches involved in the gesture represented by the receiver.

    Declaration

    Swift

    func numberOfTouches() -> Int

    Objective-C

    - (NSUInteger)numberOfTouches

    Return Value

    The number of UITouch objects in a private array maintained by the receiver. Each of these objects represents a touch in the current gesture.

    Discussion

    Using the value returned by this method in a loop, you can ask for the location of individual touches using the locationOfTouch:inView: method.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • state state Property

    The current state of the gesture recognizer. (read-only)

    Declaration

    Swift

    var state: UIGestureRecognizerState { get }

    Objective-C

    @property(nonatomic, readonly) UIGestureRecognizerState state

    Discussion

    The possible states a gesture recognizer can be in are represented by the constants of type UIGestureRecognizerState. Some of these states are not applicable to discrete gestures. The read-only version of the state property is intended for clients of a gesture-recognizer class and not subclasses.

    Special Considerations

    Subclasses of UIGestureRecognizer must use a read-write version of the state property. They get this redeclaration when they import the UIGestureRecognizerSubclass.h header file:

    • @property(nonatomic,readwrite) UIGestureRecognizerState state;

    Recognizers for discrete gestures transition from UIGestureRecognizerStatePossible to UIGestureRecognizerStateFailed or UIGestureRecognizerStateRecognized. Recognizers for continuous gesture transition from UIGestureRecognizerStatePossible to these phases in the given order: UIGestureRecognizerStateBegan, UIGestureRecognizerStateChanged, and UIGestureRecognizerStateEnded. If, however, they receive a cancellation touch, they should transition to UIGestureRecognizerStateCancelled. If recognizers for continuous gestures can’t interpret a multi-touch sequence as their gesture, they transition to UIGestureRecognizerStateFailed.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • view view Property

    The view the gesture recognizer is attached to. (read-only)

    Declaration

    Swift

    var view: UIView? { get }

    Objective-C

    @property(nonatomic, readonly) UIView *view

    Discussion

    You attach (or add) a gesture recognizer to a UIView object using the addGestureRecognizer: method.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • enabled enabled Property

    A Boolean property that indicates whether the gesture recognizer is enabled.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Discussion

    Disables a gesture recognizers so it does not receive touches. The default value is YEStrue. If you change this property to NOfalse while a gesture recognizer is currently recognizing a gesture, the gesture recognizer transitions to a cancelled state.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • A Boolean value affecting whether touches are delivered to a view when a gesture is recognized.

    Declaration

    Swift

    var cancelsTouchesInView: Bool

    Objective-C

    @property(nonatomic) BOOL cancelsTouchesInView

    Discussion

    When this property is YEStrue (the default) and the receiver recognizes its gesture, the touches of that gesture that are pending are not delivered to the view and previously delivered touches are cancelled through a touchesCancelled:withEvent: message sent to the view. If a gesture recognizer doesn’t recognize its gesture or if the value of this property is NOfalse, the view receives all touches in the multi-touch sequence.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • A Boolean value determining whether the receiver delays sending touches in a begin phase to its view.

    Declaration

    Swift

    var delaysTouchesBegan: Bool

    Objective-C

    @property(nonatomic) BOOL delaysTouchesBegan

    Discussion

    When the value of this property is NOfalse (the default), views analyze touch events in UITouchPhaseBegan and UITouchPhaseMoved in parallel with the receiver. When the value of the property is YEStrue, the window suspends delivery of touch objects in the UITouchPhaseBegan phase to the view. If the gesture recognizer subsequently recognizes its gesture, these touch objects are discarded. If the gesture recognizer, however, does not recognize its gesture, the window delivers these objects to the view in a touchesBegan:withEvent: message (and possibly a follow-up touchesMoved:withEvent: message to inform it of the touches’ current locations). Set this property to YEStrue to prevent views from processing any touches in the UITouchPhaseBegan phase that may be recognized as part of this gesture.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • A Boolean value determining whether the receiver delays sending touches in a end phase to its view.

    Declaration

    Swift

    var delaysTouchesEnded: Bool

    Objective-C

    @property(nonatomic) BOOL delaysTouchesEnded

    Discussion

    When the value of this property is YEStrue (the default) and the receiver is analyzing touch events, the window suspends delivery of touch objects in the UITouchPhaseEnded phase to the attached view. If the gesture recognizer subsequently recognizes its gesture, these touch objects are cancelled (via a touchesCancelled:withEvent: message). If the gesture recognizer does not recognize its gesture, the window delivers these objects in an invocation of the view’s touchesEnded:withEvent: method. Set this property to NOfalse to have touch objects in the UITouchPhaseEnded delivered to the view while the gesture recognizer is analyzing the same touches.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Creates a dependency relationship between the receiver and another gesture recognizer.

    Declaration

    Swift

    func requireGestureRecognizerToFail(_ otherGestureRecognizer: UIGestureRecognizer)

    Objective-C

    - (void)requireGestureRecognizerToFail:(UIGestureRecognizer *)otherGestureRecognizer

    Parameters

    otherGestureRecognizer

    Another gesture-recognizer object (an instance of a subclass of UIGestureRecognizer).

    Discussion

    This method creates a relationship with another gesture recognizer that delays the receiver’s transition out of UIGestureRecognizerStatePossible. The state that the receiver transitions to depends on what happens with otherGestureRecognizer:

    An example where this method might be called is when you want a single-tap gesture require that a double-tap gesture fail.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • delegate delegate Property

    The delegate of the gesture recognizer.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIGestureRecognizerDelegate?

    Objective-C

    @property(nonatomic, assign) id< UIGestureRecognizerDelegate > delegate

    Discussion

    The gesture recognizer maintains a weak reference to its delegate. The delegate must adopt the UIGestureRecognizerDelegate protocol and implement one or more of its methods.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

Data Types

  • The current state a gesture recognizer is in.

    Declaration

    Swift

    enum UIGestureRecognizerState : Int { case Possible case Began case Changed case Ended case Cancelled case Failed }

    Objective-C

    typedef enum { UIGestureRecognizerStatePossible, UIGestureRecognizerStateBegan, UIGestureRecognizerStateChanged, UIGestureRecognizerStateEnded, UIGestureRecognizerStateCancelled, UIGestureRecognizerStateFailed, UIGestureRecognizerStateRecognized = UIGestureRecognizerStateEnded } UIGestureRecognizerState;

    Constants

    • Possible

      UIGestureRecognizerStatePossible

      The gesture recognizer has not yet recognized its gesture, but may be evaluating touch events. This is the default state.

      Available in iOS 3.2 and later.

    • Began

      UIGestureRecognizerStateBegan

      The gesture recognizer has received touch objects recognized as a continuous gesture. It sends its action message (or messages) at the next cycle of the run loop.

      Available in iOS 3.2 and later.

    • Changed

      UIGestureRecognizerStateChanged

      The gesture recognizer has received touches recognized as a change to a continuous gesture. It sends its action message (or messages) at the next cycle of the run loop.

      Available in iOS 3.2 and later.

    • Ended

      UIGestureRecognizerStateEnded

      The gesture recognizer has received touches recognized as the end of a continuous gesture. It sends its action message (or messages) at the next cycle of the run loop and resets its state to UIGestureRecognizerStatePossible.

      Available in iOS 3.2 and later.

    • Cancelled

      UIGestureRecognizerStateCancelled

      The gesture recognizer has received touches resulting in the cancellation of a continuous gesture. It sends its action message (or messages) at the next cycle of the run loop and resets its state to UIGestureRecognizerStatePossible.

      Available in iOS 3.2 and later.

    • Failed

      UIGestureRecognizerStateFailed

      The gesture recognizer has received a multi-touch sequence that it cannot recognize as its gesture. No action message is sent and the gesture recognizer is reset to UIGestureRecognizerStatePossible.

      Available in iOS 3.2 and later.

    • UIGestureRecognizerStateRecognized

      UIGestureRecognizerStateRecognized

      The gesture recognizer has received a multi-touch sequence that it recognizes as its gesture. It sends its action message (or messages) at the next cycle of the run loop and resets its state to UIGestureRecognizerStatePossible.

      Available in iOS 3.2 and later.

    Discussion

    Gesture recognizers recognize a discrete event such as a tap or a swipe but don’t report changes within the gesture. In other words, discrete gestures don’t transition through the Began and Changed states and they can’t fail or be cancelled.

    Import Statement

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.