Class: UIGestureRecognizer

Inherits:
NSObject show all

Overview

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.

Direct Known Subclasses

UILongPressGestureRecognizer, UIPanGestureRecognizer, UIPinchGestureRecognizer, UIRotationGestureRecognizer, UISwipeGestureRecognizer, UITapGestureRecognizer

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (Boolean) cancelsTouchesInView

A Boolean value affecting whether touches are delivered to a view when a gesture is recognized. When this property is YES (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 NO, the view receives all touches in the multi-touch sequence.

Returns:

  • (Boolean)

- (Boolean) delaysTouchesBegan

A Boolean value determining whether the receiver delays sending touches in a begin phase to its view. When the value of this property is NO (the default), views analyze touch events in UITouchPhaseBegan and UITouchPhaseMoved in parallel with the receiver. When the value of the property is YES, 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 YES to prevent views from processing any touches in the UITouchPhaseBegan phase that may be recognized as part of this gesture.

Returns:

  • (Boolean)

- (Boolean) delaysTouchesEnded

A Boolean value determining whether the receiver delays sending touches in a end phase to its view. When the value of this property is YES (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 NO to have touch objects in the UITouchPhaseEnded delivered to the view while the gesture recognizer is analyzing the same touches.

Returns:

  • (Boolean)

- (Object) delegate

The delegate of the gesture recognizer. 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.

Returns:

- (Boolean) enabled

A Boolean property that indicates whether the gesture recognizer is enabled. Disables a gesture recognizers so it does not receive touches. The default value is YES. If you change this property to NO while a gesture recognizer is currently recognizing a gesture, the gesture recognizer transitions to a cancelled state.

Returns:

  • (Boolean)

- (UIGestureRecognizerState) state (readonly)

The current state of the gesture recognizer. (read-only) 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.

Returns:

- (UIView) view (readonly)

The view the gesture recognizer is attached to. (read-only) You attach (or add) a gesture recognizer to a UIView object using the addGestureRecognizer: method.

Returns:

Instance Method Details

- (Object) addTarget(target, action:action)

Adds a target and an action to a gesture-recognizer object. 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.

Parameters:

  • target (Object) —

    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 (Symbol) —

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

Returns:

- (Boolean) canBePreventedByGestureRecognizer(preventingGestureRecognizer)

Overridden to indicate that the specified gesture recognizer can prevent the receiver from recognizing a gesture. Overriding these methods enables the same behavior as implementing the UIGestureRecognizerDelegate methods gestureRecognizerShouldBegin: and gestureRecognizer:shouldReceiveTouch:. However, by overriding them, subclasses can define class-wide prevention rules. For example, a UITapGestureRecognizer object never prevents another UITapGestureRecognizer object with a higher tap count.

Parameters:

Returns:

  • (Boolean) —

    YES to indicate that preventingGestureRecognizer can block the receiver from recognizing its gesture, otherwise NO.

- (Boolean) canPreventGestureRecognizer(preventedGestureRecognizer)

Overridden to indicate that the receiver can prevent the specified gesture recognizer from recognizing its gesture. Overriding these methods enables the same behavior as implementing the UIGestureRecognizerDelegate methods gestureRecognizerShouldBegin: and gestureRecognizer:shouldReceiveTouch:. However, by overriding them, subclasses can define class-wide prevention rules. For example, a UITapGestureRecognizer object never prevents another UITapGestureRecognizer object with a higher tap count.

Parameters:

Returns:

  • (Boolean) —

    YES to indicate that the receiver can block preventedGestureRecognizer from recognizing its gesture, otherwise NO.

- (Object) ignoreTouch(touch, forEvent:event)

Tells the gesture recognizer to ignore a specific touch of the given event. If a touch isn't part of this gesture you may pass it to this method, causing it to be ignored. UIGestureRecognizer does not cancel ignored touches on the associated view even if cancelsTouchesInView is YES. This method is intended to be called, not overridden.

Parameters:

  • touch (UITouch) —

    A UITouch object that is part of the current multi-touch sequence and associated with event.

  • event (UIEvent) —

    A UIEvent object that includes a reference to touch.

Returns:

- (Object) initWithTarget(target, action:action)

Initializes an allocated gesture-recognizer object with a target and an action selector. This method is the designated initializer. After creating the gesture recognizer, you may associate other target-action pairs with it by calling addTarget:action:.

Parameters:

  • target (Object) —

    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 (Symbol) —

    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.

Returns:

  • (Object) —

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

- (CGPoint) locationInView(view)

Returns the point computed as the location in a given view of the gesture represented by the receiver. 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.

Parameters:

  • view (UIView) —

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

Returns:

  • (CGPoint) —

    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.

- (CGPoint) locationOfTouch(touchIndex, inView:view)

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

Parameters:

  • touchIndex (Integer) —

    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 (UIView) —

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

Returns:

  • (CGPoint) —

    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.

- (Integer) numberOfTouches

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

Returns:

  • (Integer) —

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

- (Object) removeTarget(target, action:action)

Removes a target and an action from a gesture-recognizer object. Calling this method removes the specified target-action pair. Passing nil for target matches all targets and passing NULL for action matches all actions.

Parameters:

  • target (Object) —

    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 (Symbol) —

    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.

Returns:

- (Object) requireGestureRecognizerToFail(otherGestureRecognizer)

Creates a dependency relationship between the receiver and another gesture recognizer. 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: If otherGestureRecognizer transitions to UIGestureRecognizerStateFailed, the receiver transitions to its normal next state.if otherGestureRecognizer transitions to UIGestureRecognizerStateRecognized or UIGestureRecognizerStateBegan, the receiver transitions to UIGestureRecognizerStateFailed.An example where this method might be called is when you want a single-tap gesture require that a double-tap gesture fail.

Parameters:

Returns:

- (Object) reset

Overridden to reset internal state when a gesture is recognized. The runtime calls this method after the gesture-recognizer state has been set to UIGestureRecognizerStateEnded or UIGestureRecognizerStateRecognized. Subclasses should reset any internal state in preparation for a new attempt at gesture recognition. After this method is called, the runtime ignores all remaining active touches; that is, the gesture recognizer receives no further updates for touches that have begun but haven't ended.

Returns:

- (Object) touchesBegan(touches, withEvent:event)

Sent to the receiver when one or more fingers touch down in the associated view. This method has the same exact signature as the corresponding one declared by UIResponder. Through this method a gesture recognizer receives touch objects (in their UITouchPhaseBegan phase) before the view attached to the gesture recognizer receives them. UIGestureRecognizer objects are not in the responder chain, yet observe touches hit-tested to their view and their view's subviews. After observation, the delivery of touch objects to the attached view, or their disposition otherwise, is affected by the cancelsTouchesInView, delaysTouchesBegan, and delaysTouchesEnded properties.If the gesture recognizer is interpreting a continuous gesture, it should set its state to UIGestureRecognizerStateBegan upon receiving this message. If at any point in its handling of the touch objects the gesture recognizer determines that the multi-touch event sequence is not its gesture, it should set it state to UIGestureRecognizerStateCancelled.Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the attached view instance to YES.

Parameters:

  • touches (NSSet) —

    A set of UITouch instances in the event represented by event that represent the touches in the UITouchPhaseBegan phase.

  • event (UIEvent) —

    A UIEvent object representing the event to which the touches belong.

Returns:

- (Object) touchesCancelled(touches, withEvent:event)

Sent to the receiver when a system event (such as a low-memory warning) cancels a touch event. This method has the same exact signature as the corresponding one declared by UIResponder. Through this method a gesture recognizer receives touch objects (in their UITouchPhaseCancelled phase) before the view attached to the gesture recognizer receives them. UIGestureRecognizer objects are not in the responder chain, yet observe touches hit-tested to their view and their view's subviews. After observation, the delivery of touch objects to the attached view, or their disposition otherwise, is affected by the cancelsTouchesInView, delaysTouchesBegan, and delaysTouchesEnded properties.Upon receiving this message, the gesture recognizer for a continuous gesture should set its state to UIGestureRecognizerStateCancelled; a gesture recognizer for a discrete gesture should set its state to UIGestureRecognizerStateFailed.

Parameters:

  • touches (NSSet) —

    A set of UITouch instances in the event represented by event that represent the touches in the UITouchPhaseCancelled phase.

  • event (UIEvent) —

    A UIEvent object representing the event to which the touches belong.

Returns:

- (Object) touchesEnded(touches, withEvent:event)

Sent to the receiver when one or more fingers lift from the associated view. This method has the same exact signature as the corresponding one declared by UIResponder. Through this method a gesture recognizer receives touch objects (in their UITouchPhaseEnded phase) before the view attached to the gesture recognizer receives them. UIGestureRecognizer objects are not in the responder chain, yet observe touches hit-tested to their view and their view's subviews. After observation, the delivery of touch objects to the attached view, or their disposition otherwise, is affected by the cancelsTouchesInView, delaysTouchesBegan, and delaysTouchesEnded properties.If the gesture recognizer is interpreting a continuous gesture, it should set its state to UIGestureRecognizerStateEnded upon receiving this message. If it is interpreting a discrete gesture, it should set its state to UIGestureRecognizerStateRecognized. If at any point in its handling of the touch objects the gesture recognizer determines that the multi-touch event sequence is not its gesture, it should set it state to UIGestureRecognizerStateCancelled.Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the attached view instance to YES.

Parameters:

  • touches (NSSet) —

    A set of UITouch instances in the event represented by event that represent the touches in the UITouchPhaseEnded phase.

  • event (UIEvent) —

    A UIEvent object representing the event to which the touches belong.

Returns:

- (Object) touchesMoved(touches, withEvent:event)

Sent to the receiver when one or more fingers move in the associated view. This method has the same exact signature as the corresponding one declared by UIResponder. Through this method a gesture recognizer receives touch objects (in their UITouchPhaseMoved phase) before the view attached to the gesture recognizer receives them. UIGestureRecognizer objects are not in the responder chain, yet observe touches hit-tested to their view and their view's subviews. After observation, the delivery of touch objects to the attached view, or their disposition otherwise, is affected by the cancelsTouchesInView, delaysTouchesBegan, and delaysTouchesEnded properties.If the gesture recognizer is interpreting a continuous gesture, it should set its state to UIGestureRecognizerStateChanged upon receiving this message. If at any point in its handling of the touch objects the gesture recognizer determines that the multi-touch event sequence is not its gesture, it should set it state to UIGestureRecognizerStateCancelled .Multiple touches are disabled by default. In order to receive multiple touch events you must set the a multipleTouchEnabled property of the attached view instance to YES.

Parameters:

  • touches (NSSet) —

    A set of UITouch instances in the event represented by event that represent touches in the UITouchPhaseMoved phase.

  • event (UIEvent) —

    A UIEvent object representing the event to which the touches belong.

Returns: