Gesture Recognizer Classes

A gesture recognizer (a subclass of UIGestureRecognizer) is an object whose job is to detect that a multitouch sequence equates to one particular type of gesture. It is attached to a UIView, which has for this purpose methods addGestureRecognizer(_:) and removeGestureRecognizer(_:), and a gestureRecognizers property.

A UIGestureRecognizer implements the four touch methods, but it is not a responder (a UIResponder), so it does not participate in the responder chain. If, however, a new touch is going to be delivered to a view, it is also associated with and delivered to that view’s gesture recognizers if it has any, and to that view’s superview’s gesture recognizers if it has any, and so on up the view hierarchy. Thus, the place of a gesture recognizer in the view hierarchy matters, even though it isn’t part of the responder chain.

UITouch and UIEvent provide complementary ways of learning how touches and gesture recognizers are associated. UITouch’s gestureRecognizers lists the gesture recognizers that are currently handling this touch. UIEvent’s touches(for:) can take a gesture recognizer parameter; it then lists the touches that are currently being handled by that gesture recognizer.

Each gesture recognizer maintains its own state as touch events arrive, building up evidence as to what kind of gesture this is. When one of them decides that it has recognized its own particular type of gesture, it emits either a single message (to indicate, for example, that a finger has tapped) or a series of messages (to indicate, for example, that a finger is moving); the distinction here is between a discrete and a continuous gesture.

What message a gesture recognizer emits, and to what object it sends it, is set through a target–action dispatch table attached to the gesture recognizer; a gesture recognizer is rather like a UIControl in this regard. Indeed, one might say that a gesture recognizer simplifies the touch handling of any view to be like that of a control. The difference is that one control may report several different control events, whereas each gesture recognizer reports only one gesture type, with different gestures being reported by different gesture recognizers.

UIGestureRecognizer itself is abstract, providing methods and properties to its subclasses. Among these are:

init(target:action:)

The designated initializer. Each message emitted by a UIGestureRecognizer is a matter of sending the action message to the target. Further target–action pairs may be added with addTarget(_:action:) and removed with removeTarget(_:action:).

Two forms of action: selector are possible: either there is no parameter, or there is a single parameter which will be the gesture recognizer. Most commonly, you’ll use the second form, so that the target can identify and query the gesture recognizer through one of its various methods and properties.

location(ofTouch:in:)

The second parameter is the view whose coordinate system you want to use. The touch is specified by an index number. The numberOfTouches property provides a count of current touches; the touches themselves are inaccessible by way of the gesture recognizer.

isEnabled

A convenient way to turn a gesture recognizer off without having to remove it from its view.

state, view

I’ll discuss state later on. The view is the view to which this gesture recognizer is attached.

Built-in UIGestureRecognizer subclasses are provided for six common gesture types: tap, pinch (inward or outward), pan (drag), swipe, rotate, and long press. Each embodies properties and methods likely to be needed for each type of gesture, either in order to configure the gesture recognizer beforehand or in order to query it as to the state of an ongoing gesture:

UITapGestureRecognizer (discrete)

Configuration: numberOfTapsRequired, numberOfTouchesRequired (“touches” means simultaneous fingers).

UIPinchGestureRecognizer (continuous)

Two fingers moving toward or away from each other. State: scale, velocity.

UIRotationGestureRecognizer (continuous)

Two fingers moving round a common center. State: rotation, velocity.

UISwipeGestureRecognizer (discrete)

A straight-line movement in one of the four cardinal directions. Configuration: direction (meaning permitted directions, a bitmask), numberOfTouchesRequired.

UIPanGestureRecognizer (continuous)

Dragging. Configuration: minimumNumberOfTouches, maximumNumberOfTouches. State: translation(in:), setTranslation(_:in:), velocity(in:); the coordinate system of the specified view is used.

UIScreenEdgePanGestureRecognizer

A UIPanGestureRecognizer subclass. It recognizes a pan gesture that starts at an edge of the screen. It adds a configuration property, edges, a UIRectEdge; despite the name (and the documentation), this must be set to a single edge.

UILongPressGestureRecognizer (continuous)

Configuration: numberOfTapsRequired, numberOfTouchesRequired, minimumPressDuration, allowableMovement. The numberOfTapsRequired is the count of taps before the tap that stays down, so it can be 0 (the default). The allowableMovement setting lets you compensate for the fact that the user’s finger is unlikely to remain steady during an extended press; thus we need to provide some limit before deciding that this gesture is, say, a drag, and not a long press after all. On the other hand, once the long press is recognized, the finger is permitted to drag as part of the long press gesture.

UIGestureRecognizer also provides a location(in:) method. This is a single point, even if there are multiple touches. The subclasses implement this variously. For example, for UIPanGestureRecognizer, the location is where the touch is if there’s a single touch, but it’s a sort of midpoint (“centroid”) if there are multiple touches.

We already know enough to implement, using a gesture recognizer, a view that responds to a single tap, or a view that responds to a double tap. Here’s code (probably from our view controller’s viewDidLoad) that implements a view (self.v) that responds to a single tap by calling our singleTap method:

let t1 = UITapGestureRecognizer(target:self, action:#selector(singleTap))
self.v.addGestureRecognizer(t1)

And here’s code that implements a view (self.v) that responds to a double tap by calling our doubleTap method:

let t2 = UITapGestureRecognizer(target:self, action:#selector(doubleTap))
t2.numberOfTapsRequired = 2
self.v.addGestureRecognizer(t2)

For a continuous gesture like dragging, we need to know both when the gesture is in progress and when the gesture ends. This brings us to the subject of a gesture recognizer’s state.

A gesture recognizer implements a notion of states (the state property, UIGestureRecognizerState); it passes through these states in a definite progression. The gesture recognizer remains in the .possible state until it can make a decision one way or the other as to whether this is in fact the correct gesture. The documentation neatly lays out the possible progressions:

Wrong gesture

.possible → .failed. No action message is sent.

Discrete gesture (like a tap), recognized

.possible → .ended. One action message is sent, when the state changes to .ended.

Continuous gesture (like a drag), recognized

.possible → .began → .changed (repeatedly) → .ended. Action messages are sent once for .began, as many times as necessary for .changed, and once for .ended.

Continuous gesture, recognized but later cancelled

.possible → .began → .changed (repeatedly) → .cancelled. Action messages are sent once for .began, as many times as necessary for .changed, and once for .cancelled.

The same action message arrives at the same target every time, so the action method must differentiate by asking about the gesture recognizer’s state. The usual implementation involves a switch statement.

To illustrate, we will implement, using a gesture recognizer, a view that lets itself be dragged around in any direction by a single finger. Our maintenance of state is greatly simplified, because a UIPanGestureRecognizer maintains a delta (translation) for us. This delta, available using translation(in:), is reckoned from the touch’s initial position. We don’t even need to record the view’s original center, because we can reset the UIPanGestureRecognizer’s delta, using setTranslation(_:in:):

func viewDidLoad {
    super.viewDidLoad()
    let p = UIPanGestureRecognizer(target:self, action:#selector(dragging))
    self.v.addGestureRecognizer(p)
}
func dragging(_ p : UIPanGestureRecognizer) {
    let v = p.view!
    switch p.state {
    case .began, .changed:
        let delta = p.translation(in:v.superview)
        var c = v.center
        c.x += delta.x; c.y += delta.y
        v.center = c
        p.setTranslation(.zero, in: v.superview)
    default: break
    }
}

To illustrate the use of a UIPanGestureRecognizer’s velocity(in:), let’s imagine a view that the user can drag, but which then springs back to where it was. We can express “springs back” with a spring animation (Chapter 4). All we have to do is add an .ended case to our dragging method (dest is the original center of our view v):

case .ended:
    let anim = UIViewPropertyAnimator(
        duration: 0.4,
        timingParameters: UISpringTimingParameters(
            dampingRatio: 0.6,
            initialVelocity: .zero))
    anim.addAnimations {
        v.center = dest
    }
    anim.startAnimation()

That’s good, but it would be even better if the view had some momentum at the moment the user lets go of it. If the user drags the view quickly away from its home and lets go, the view should keep moving a little in the same direction before springing back into place. That’s what the spring animation’s initialVelocity: parameter is for! We can easily find out what the view’s velocity is, at the moment the user releases it, by asking the gesture recognizer:

let vel = p.velocity(in: v.superview!)

Unfortunately, we cannot use this value directly as the spring animation’s initialVelocity; there’s a type impedance mismatch. The view’s velocity is expressed as a CGPoint measured in points per second. But the spring’s initialVelocity is expressed as a CGVector measured as a proportion of the distance to be travelled over the course of the animation. Fortunately, the conversion is easy:

case .ended:
    let vel = p.velocity(in: v.superview!)
    let c = v.center
    let distx = abs(c.x - dest.x)
    let disty = abs(c.y - dest.y)
    let anim = UIViewPropertyAnimator(
        duration: 0.4,
        timingParameters: UISpringTimingParameters(
            dampingRatio: 0.6,
            initialVelocity: CGVector(vel.x/distx, vel.y/disty)))
    anim.addAnimations {
        v.center = dest
    }
    anim.startAnimation()

A pan gesture recognizer can be used also to make a view draggable under the influence of a UIDynamicAnimator (Chapter 4). The strategy here is that the view is attached to one or more anchor points through a UIAttachmentBehavior; as the user drags, we move the anchor point(s), and the view follows. In this example, I set up the whole UIKit dynamics “stack” of objects as the gesture begins, anchoring the view at the point where the touch is; then I move the anchor point to stay with the touch. Instance properties self.anim and self.att store the UIDynamicAnimator and the UIAttachmentBehavior, respectively; self.view is our view’s superview, and is the animator’s reference view:

@IBAction func dragging(_ p: UIPanGestureRecognizer) {
    switch p.state {
    case .began:
        self.anim = UIDynamicAnimator(referenceView:self.view)
        let loc = p.location(ofTouch:0, in:p.view)
        let cen = CGPoint(p.view!.bounds.midX, p.view!.bounds.midY)
        let off = UIOffsetMake(loc.x-cen.x, loc.y-cen.y)
        let anchor = p.location(ofTouch:0, in:self.view)
        let att = UIAttachmentBehavior(item:p.view!,
            offsetFromCenter:off, attachedToAnchor:anchor)
        self.anim.addBehavior(att)
        self.att = att
    case .changed:
        self.att.anchorPoint = p.location(ofTouch:0, in: self.view)
    default:
        self.anim = nil
    }
}

The outcome is that the view both moves and rotates in response to dragging, like a plate being pulled about on a table by a single finger.

By adding behaviors to the dynamic animator, we can limit further what the view is permitted to do as it is being dragged by its anchor. For example, imagine a view that can be lifted vertically and dropped, but cannot be moved horizontally. As I demonstrated earlier, you can prevent horizontal dragging through the implementation of your response to touch events (and later in this chapter, I’ll show how to do this by subclassing UIPanGestureRecognizer). But the same sort of limitation can imposed by way of the underlying physics of the world in which the view exists — with a sliding attachment, for example.

Gesture Recognizer Conflicts

The question naturally arises of what happens when multiple gesture recognizers are in play. This isn’t a matter merely of multiple recognizers attached to a single view; as I have said, if a view is touched, not only its own gesture recognizers but also any gesture recognizers attached to views further up the view hierarchy are in play simultaneously. I like to think of a view as surrounded by a swarm of gesture recognizers — its own, and those of its superview, and so on. (In reality, it is a touch that has a swarm of gesture recognizers; that’s why a UITouch has a gestureRecognizers property, in the plural.)

The superview gesture recognizer swarm comes as a surprise to beginners, but it makes sense, because without it, certain gestures would be impossible. Imagine, for example, a pair of views, each of which the user can tap individually, but which the user can also touch simultaneously (one finger on each view) to rotate them together around their mutual centroid. Neither view can detect the rotation qua rotation, because neither view receives both touches; only the superview can detect it, so the fact that the views themselves respond to touches must not prevent the superview’s gesture recognizer from operating.

In general, once a gesture recognizer succeeds in recognizing its gesture, any other gesture recognizers associated with its touches are forced into the .failed state, and whatever touches were associated with those gesture recognizers are no longer sent to them; in effect, the first gesture recognizer in a swarm that recognizes its gesture owns the gesture (and its touches) from then on.

In many cases, this “first past the post” behavior, on its own, will correctly eliminate conflicts. If it doesn’t, you can modify it.

For example, we can add both our UITapGestureRecognizer for a single tap and our UIPanGestureRecognizer to a view and everything will just work; dragging works, and single tap works. Thus, “first past the post” is exactly the desired behavior.

What happens, though, if we also add the UITapGestureRecognizer for a double tap? Dragging works, and single tap works; double tap works too, but without preventing the single tap from working. So, on a double tap, both the single tap action method and the double tap action method are called. If that isn’t what we want, we don’t have to use delayed performance, as we did earlier. Instead, we can create a dependency between one gesture recognizer and another, telling the first to suspend judgement until the second has decided whether this is its gesture. We can do this by sending the first gesture recognizer the require(toFail:) message. (This method is rather badly named; it doesn’t mean “force this other recognizer to fail,” but rather, “you can’t succeed unless this other recognizer has failed.”)

So our view self.v is now configured as follows:

let t2 = UITapGestureRecognizer(target:self, action:#selector(doubleTap))
t2.numberOfTapsRequired = 2
self.v.addGestureRecognizer(t2)
let t1 = UITapGestureRecognizer(target:self, action:#selector(singleTap))
t1.require(toFail:t2) // *
self.v.addGestureRecognizer(t1)
let p = UIPanGestureRecognizer(target: self, action: #selector(dragging))
self.v.addGestureRecognizer(p)

Another conflict that can arise is between a gesture recognizer and a view that already knows how to respond to the same gesture, such as a UIControl. This problem pops up particularly when the gesture recognizer belongs to the UIControl’s superview. The UIControl’s mere presence does not “block” the superview’s gesture recognizer from recognizing a gesture on the UIControl, even if it is a UIControl that responds autonomously to touches. For example, your window’s root view might have a UITapGestureRecognizer attached to it (perhaps because you want to be able to recognize taps on the background), but there is also a UIButton within it. How is that gesture recognizer to ignore a tap on the button?

The UIView instance method gestureRecognizerShouldBegin(_:) solves the problem. It is called automatically; to modify its behavior, use a custom UIView subclass and override it. Its parameter is a gesture recognizer belonging to this view or to a view further up the view hierarchy. That gesture recognizer has recognized its gesture as taking place in this view; but by returning false, the view can tell the gesture recognizer to bow out and do nothing, not sending any action messages, and permitting this view to respond to the touch as if the gesture recognizer weren’t there.

Thus, for example, a UIButton could return false for a single tap UITapGestureRecognizer; a single tap on the button would then trigger the button’s action message and not the gesture recognizer’s action message. And in fact a UIButton, by default, does return false for a single tap UITapGestureRecognizer whose view is not the UIButton itself. (If the gesture recognizer is for some gesture other than a tap, then the problem never arises, because a tap on the button won’t cause the gesture recognizer to recognize in the first place.) Other built-in controls may also implement gestureRecognizerShouldBegin(_:) in such a way as to prevent accidental interaction with a gesture recognizer; the documentation says that a UISlider implements it in such a way that a UISwipeGestureRecognizer won’t prevent the user from sliding the “thumb,” and there may be other cases that aren’t documented explicitly. Naturally, you can take advantage of this feature in your own UIView subclasses as well.

Another way of resolving possible gesture recognizer conflicts is through the gesture recognizer’s delegate, or with a gesture recognizer subclass. I’ll discuss those in a moment.

Subclassing Gesture Recognizers

To subclass UIGestureRecognizer or a built-in gesture recognizer subclass, you must do the following things:

• Import UIKit.UIGestureRecognizerSubclass. This allows you to set a gesture recognizer’s state (which is otherwise read-only), and exposes declarations for the methods you may need to override.

• Override any touch methods you need to (as if the gesture recognizer were a UIResponder); if you’re subclassing a built-in gesture recognizer subclass, you will almost certainly call super so as to take advantage of the built-in behavior. In overriding a touch method, you need to think like a gesture recognizer. As these methods are called, a gesture recognizer is setting its state; you must participate in that process.

To illustrate, we will subclass UIPanGestureRecognizer so as to implement a view that can be moved only horizontally or vertically. Our strategy will be to make two UIPanGestureRecognizer subclasses — one that allows only horizontal movement, and another that allows only vertical movement. They will make their recognition decisions in a mutually exclusive manner, so we can attach an instance of each to our view. This encapsulates the decision-making logic in a gorgeously object-oriented way — a far cry from the spaghetti code we wrote earlier to do this same task.

I will show only the code for the horizontal drag gesture recognizer, because the vertical recognizer is symmetrically identical. We maintain just one property, self.origLoc, which we will use once to determine whether the user’s initial movement is horizontal. We override touchesBegan(_:with:) to set our property with the first touch’s location:

override func touchesBegan(_ touches: Set<UITouch>, with e: UIEvent) {
    self.origLoc = touches.first!.location(in:self.view!.superview)
    super.touchesBegan(touches, with:e)
}

We then override touchesMoved(_:with:); all the recognition logic is here. This method will be called for the first time with the state still at .possible. At that moment, we look to see if the user’s movement is more horizontal than vertical. If it isn’t, we set the state to .failed. But if it is, we just step back and let the superclass do its thing:

override func touchesMoved(_ touches: Set<UITouch>, with e: UIEvent) {
    if self.state == .possible {
        let loc = touches.first!.location(in:self.view!.superview)
        let deltaX = abs(loc.x - self.origLoc.x)
        let deltaY = abs(loc.y - self.origLoc.y)
        if deltaY >= deltaX {
            self.state = .failed
        }
    }
    super.touchesMoved(touches, with:e)
}

We now have a view that moves only if the user’s initial gesture is horizontal. But that isn’t the entirety of what we want; we want a view that, itself, moves horizontally only. To implement this, we’ll simply lie to our client about where the user’s finger is, by overriding translation(in:):

override func translation(in view: UIView?) -> CGPoint {
    var proposedTranslation = super.translation(in:view)
    proposedTranslation.y = 0
    return proposedTranslation
}

That example was simple, because we subclassed a fully functional built-in UIGestureRecognizer subclass. If you were to write your own UIGestureRecognizer subclass entirely from scratch, there would be more work to do:

• You should definitely implement all four touch methods. Their job, at a minimum, is to advance the gesture recognizer through the canonical progression of its states. When the first touch arrives at a gesture recognizer, its state will be .possible; you never explicitly set the recognizer’s state to .possible yourself. As soon as you know this can’t be our gesture, you set the state to .failed (Apple says that a gesture recognizer should “fail early, fail often”). If the gesture gets past all the failure tests, you set the state instead either to .ended (for a discrete gesture) or to .began (for a continuous gesture); if .began, then you might set it to .changed, and ultimately you must set it to .ended. Action messages will be sent automatically at the appropriate moments.

• You should probably implement reset. This is called after you reach the end of the progression of states to notify you that the gesture recognizer’s state is about to be set back to .possible; it is your chance to return your state machine to its starting configuration (resetting properties, for example).

Keep in mind that your gesture recognizer might stop receiving touches without notice. Just because it gets a touchesBegan(_:with:) call for a particular touch doesn’t mean it will ever get touchesEnded(_:with:) for that touch. If your gesture recognizer fails to recognize its gesture, either because it declares failure or because it is still in the .possible state when another gesture recognizer recognizes, it won’t get any more touch method calls for any of the touches that were being sent to it. This is why reset is so important; it’s the one reliable signal that it’s time to clean up and get ready to receive the beginning of another possible gesture.

Gesture Recognizer Delegate

A gesture recognizer can have a delegate (UIGestureRecognizerDelegate), which can perform two types of task.

These delegate methods can block a gesture recognizer’s operation:

gestureRecognizerShouldBegin(_:)

Sent to the delegate before the gesture recognizer passes out of the .possible state; return false to force the gesture recognizer to proceed to the .failed state. (This happens after gestureRecognizerShouldBegin(_:) has been sent to the view in which the touch took place. That view must not have returned false, or we wouldn’t have reached this stage.)

gestureRecognizer(_:shouldReceive:)

Sent to the delegate before a touch is sent to the gesture recognizer’s touchesBegan(_:with:) method; return false to prevent that touch from ever being sent to the gesture recognizer.

These delegate methods can mediate gesture recognition conflict:

gestureRecognizer(_:shouldRecognizeSimultaneouslyWith:)

Sent when a gesture recognizer recognizes its gesture, if this will force the failure of another gesture recognizer, to the delegates of both gesture recognizers. Return true to prevent that failure, thus allowing both gesture recognizers to operate simultaneously. For example, a view could respond to both a two-fingered pinch and a two-fingered pan, the one applying a scale transform, the other changing the view’s center.

gestureRecognizer(_:shouldRequireFailureOf:)

gestureRecognizer(_:shouldBeRequiredToFailBy:)

Sent very early in the life of a gesture, when all gesture recognizers in a view’s swarm are still in the .possible state, to the delegates of all of them, pairing the gesture recognizer whose delegate this is with each of the other gesture recognizers in the swarm. Return true to prioritize between this pair of gesture recognizers, saying that one cannot succeed until the other has first failed. In essence, these delegate methods turn the decision made once and permanently in require(toFail:) into a live decision that can be made freshly every time a gesture occurs.

As an example, we will use delegate messages to combine a UILongPressGestureRecognizer and a UIPanGestureRecognizer, as follows: the user must perform a tap-and-a-half (tap, then tap and hold) to “get the view’s attention,” which we will indicate by a pulsing animation on the view; then (and only then) the user can drag the view.

The UIPanGestureRecognizer’s action method will take care of the drag, as shown earlier in this chapter. The UILongPressGestureRecognizer’s action method will take care of starting and stopping the animation:

func longPress(_ lp:UILongPressGestureRecognizer) {
    switch lp.state {
    case .began:
        let anim = CABasicAnimation(keyPath: #keyPath(CALayer.transform))
        anim.toValue = CATransform3DMakeScale(1.1, 1.1, 1)
        anim.fromValue = CATransform3DIdentity
        anim.repeatCount = .infinity
        anim.autoreverses = true
        lp.view!.layer.add(anim, forKey:nil)
    case .ended, .cancelled:
        lp.view!.layer.removeAllAnimations()
    default: break
    }
}

As we created our gesture recognizers, we kept a reference to the UILongPressGestureRecognizer (self.longPresser), and we made ourself the UIPanGestureRecognizer’s delegate. So we will receive delegate messages. If the UIPanGestureRecognizer tries to declare success while the UILongPressGestureRecognizer’s state is .failed or still at .possible, we prevent it. If the UILongPressGestureRecognizer succeeds, we permit the UIPanGestureRecognizer to operate as well:

func gestureRecognizerShouldBegin(_ g: UIGestureRecognizer) -> Bool {
    switch self.longPresser.state {
    case .possible, .failed:
        return false
    default:
        return true
    }
}
func gestureRecognizer(_ g: UIGestureRecognizer,
    shouldRecognizeSimultaneouslyWith g2: UIGestureRecognizer) -> Bool {
        return true
}

The result is that the view can be dragged only while it is pulsing; in effect, what we’ve done is to compensate, using delegate methods, for the fact that UIGestureRecognizer has no require(toSucceed:) method.

If you are subclassing a gesture recognizer class, you can incorporate delegate-like behavior into the subclass, by overriding the following methods:

• canPrevent(_:)

• canBePrevented(by:)

• shouldRequireFailure(of:)

• shouldBeRequiredToFail(by:)

The prevent methods are similar to the delegate shouldBegin method, and the fail methods are similar to the delegate fail methods. In this way, you can mediate gesture recognizer conflict at the class level. The built-in gesture recognizer subclasses already do this; that is why, for example, a single tap UITapGestureRecognizer does not, by recognizing its gesture, cause the failure of a double tap UITapGestureRecognizer.

You can also, in a gesture recognizer subclass, send ignore(_:for:) directly to a gesture recognizer (typically, to self) to ignore a specific touch of a specific event. This has the same effect as the delegate method gestureRecognizer(_:shouldReceive:) returning false, blocking all future delivery of that touch to the gesture recognizer. For example, if you’re in the middle of an already recognized gesture and a new touch arrives, you might elect to ignore it.

Gesture Recognizers in the Nib

Instead of instantiating a gesture recognizer in code, you can create and configure it in a .xib or .storyboard file. In the nib editor, drag a gesture recognizer from the Object library onto a view; the gesture recognizer becomes a top-level nib object, and the view’s gestureRecognizers outlet is connected to the gesture recognizer. (You can add more than one gesture recognizer to a view in the nib: the view’s gestureRecognizers property is an array, and its gestureRecognizers outlet is an outlet collection.) The gesture recognizer’s properties are configurable in the Attributes inspector, and the gesture recognizer has a delegate outlet. The gesture recognizer is a full-fledged nib object, so you can make an outlet to it.

To configure a gesture recognizer’s target–action pair in the nib editor, treat it like a UIControl’s control event. The action method’s signature should be marked @IBAction, and it should take a single parameter, which will be a reference to the gesture recognizer. You will then be able to form the Sent Action connection in the usual way. (A gesture recognizer can have multiple target–action pairs, but only one target–action pair can be configured for a gesture recognizer using the nib editor.) A view retains its gesture recognizers, so there will usually be no need for additional memory management on a gesture recognizer instantiated from a nib.

Performing Hit-Testing

You can perform hit-testing yourself at any moment where it might prove useful. In calling hitTest(_:with:), supply a point in the coordinates of the view to which the message is sent. The second parameter is supposed to be a UIEvent, but it can be nil if you have no event.

For example, suppose we have a superview with two UIImageView subviews. We want to detect a tap in either UIImageView, but we want to handle this at the level of the superview. We can attach a UITapGestureRecognizer to the superview, but then the gesture recognizer’s view is the superview, so how will we know which subview, if any, the tap was in?

First, ensure that isUserInteractionEnabled is true for both UIImageViews. UIImageView is one of the few built-in view classes where this property is false by default, and a view whose isUserInteractionEnabled is false won’t normally be the result of a call to hitTest(_:with:). Then, when our gesture recognizer’s action method is called, we can perform hit-testing to determine where the tap was:

// g is the gesture recognizer
let p = g.location(ofTouch:0, in: g.view)
let v = g.view?.hitTest(p, with: nil)
if let v = v as? UIImageView { // ...

Hit-Test Munging

You can override hitTest(_:with:) in a view subclass, to alter its results during touch delivery, thus customizing the touch delivery mechanism. I call this hit-test munging. Hit-test munging can be used selectively as a way of turning user interaction on or off in an area of the interface. In this way, some unusual effects can be produced.

An important use of hit-test munging is to permit the touching of parts of subviews outside the bounds of their superview. If a view’s clipsToBounds is false, a paradox arises: the user can see the regions of its subviews that are outside its bounds, but can’t touch them. This can be confusing and seems wrong. The solution is for the view to override hitTest(_:with:) as follows:

override func hitTest(_ point: CGPoint, with e: UIEvent?) -> UIView? {
    if let result = super.hitTest(point, with:e) {
        return result
    }
    for sub in self.subviews.reversed() {
        let pt = self.convert(point, to:sub)
        if let result = sub.hitTest(pt, with:e) {
            return result
        }
    }
    return nil
}

Hit-Testing For Layers

Layers do not receive touches. A touch is reported to a view, not a layer. A layer, except insofar as it is a view’s underlying layer and gets touch reporting because of its view, is completely untouchable; from the point of view of touches and touch reporting, it’s as if the layer weren’t on the screen at all. No matter where a layer may appear to be, a touch falls through the layer, to whatever view is behind it.

Nevertheless, hit-testing for layers is possible. It doesn’t happen automatically, as part of sendEvent(_:) or anything else; it’s up to you. It’s just a convenient way of finding out which layer would receive a touch at a point, if layers did receive touches. To hit-test layers, call hitTest(_:) on a layer, with a point in superlayer coordinates.

In the case of a layer that is a view’s underlying layer, you don’t need hit-testing. It is the view’s drawing; where it appears is where the view is. So a touch in that layer is equivalent to a touch in its view. Indeed, one might say (and it is often said) that this is what views are actually for: to provide layers with touchability.

The only layers on which you’d need special hit-testing, then, would presumably be layers that are not themselves any view’s underlying layer, because those are the only ones you don’t find out about by normal view hit-testing. However, all layers, including a layer that is its view’s underlying layer, are part of the layer hierarchy, and can participate in layer hit-testing. So the most comprehensive way to hit-test layers is to start with the topmost layer, the window’s layer. In this example, we subclass UIWindow (see Chapter 1) and override its hitTest(_:with:) so as to get layer hit-testing every time there is view hit-testing:

override func hitTest(_ point: CGPoint, with e: UIEvent?) -> UIView? {
    let lay = self.layer.hitTest(point)
    // ... possibly do something with that information
    return super.hitTest(point, with:e)
}

In that example, self is the window, which is a special case. In general, you’ll have to convert to superlayer coordinates. In this next example, we return to the CompassView developed in Chapter 3, in which all the parts of the compass are layers; we want to know whether the user tapped on the arrow layer, and if so, we’ll rotate the arrow. For simplicity, we’ve given the CompassView a UITapGestureRecognizer, and this is its action method, in the CompassView itself. We convert to our superview’s coordinates, because these are also our layer’s superlayer coordinates:

@IBAction func tapped(_ t:UITapGestureRecognizer) {
    let p = t.location(ofTouch:0, in: self.superview)
    let hitLayer = self.layer.hitTest(p)
    let arrow = (self.layer as! CompassLayer).arrow!
    if hitLayer == arrow { // respond to touch
        arrow.transform = CATransform3DRotate(
            arrow.transform, .pi/4.0, 0, 0, 1)
    }
}

Layer hit-testing knows nothing of the restrictions on touch delivery; it just reports on every sublayer, even one whose view (for example) has isUserInteractionEnabled set to false.

Hit-Testing For Drawings

The preceding example (letting the user tap on the compass arrow) does work, but we might complain that it is reporting a hit on the arrow layer even if the hit misses the drawing of the arrow. That’s true for view hit-testing as well. A hit is reported if we are within the view or layer as a whole; hit-testing knows nothing of drawing, transparent areas, and so forth.

If you know how the region is drawn and can reproduce the edge of that drawing as a CGPath, you can call contains(_:using:transform:) to test whether a point is inside it. So, in our compass layer, we could override hitTest(_:) along these lines:

override func hitTest(_ p: CGPoint) -> CALayer? {
    var lay = super.hitTest(p)
    if lay == self.arrow {
        let pt = self.arrow.convert(p, from:self.superlayer)
        let path = CGMutablePath()
        path.addRect(CGRect(10,20,20,80))
        path.move(to:CGPoint(0, 25))
        path.addLine(to:CGPoint(20, 0))
        path.addLine(to:CGPoint(40, 25))
        path.closeSubpath()
        if !path.contains(pt, using: .winding) {
            lay = nil
        }
    }
    return lay
}

Alternatively, it might be the case that if a pixel of the drawing is transparent, it’s outside the drawn region, so that it suffices to detect whether the pixel tapped is transparent. Unfortunately, there’s no built-in way to ask a drawing (or a view, or a layer) for the color of a pixel. Instead, you have to make a bitmap graphics context and copy the drawing into it, and then ask the bitmap for the color of a pixel. If you can reproduce the content as an image, and all you care about is transparency, you can make a one-pixel alpha-only bitmap, draw the image in such a way that the pixel you want to test is the pixel drawn into the bitmap, and examine the transparency of the resulting pixel. In this example, im is our UIImage and point is the coordinates of the pixel we want to test:

let info = CGImageAlphaInfo.alphaOnly.rawValue
let pixel = UnsafeMutablePointer<UInt8>.allocate(capacity:1)
defer {
    pixel.deinitialize(count: 1)
    pixel.deallocate(capacity:1)
}
pixel[0] = 0
let sp = CGColorSpaceCreateDeviceGray()
let context = CGContext(data: pixel,
    width: 1, height: 1, bitsPerComponent: 8, bytesPerRow: 1,
    space: sp, bitmapInfo: info)!
UIGraphicsPushContext(context)
im.draw(at:CGPoint(-point.x, -point.y))
UIGraphicsPopContext()
let p = pixel[0]
let alpha = Double(p)/255.0
let transparent = alpha < 0.01

However, there may not be a one-to-one relationship between the pixels of the underlying drawing and the points of the drawing as portrayed on the screen — because the drawing is stretched, for example. In many cases, the CALayer method render(in:) can be helpful here. This method allows you to copy a layer’s actual drawing into a graphics context of your choice. If that context is an image context (Chapter 2), you can use the resulting image as im in the preceding code.

Hit-Testing During Animation

Making a view user-touchable while it is being animated is a tricky problem. The reason is that the view may not be located where the user sees it. Recall (from Chapter 4) that the animation is just an “animation movie” — what the user sees is the presentation layer. The view itself, which the user is trying to touch, is at the location of the model layer.

Therefore, if user interaction is allowed during an animation that moves a view from one place to another, then if the user taps where the animated view appears to be, the tap might mysteriously fail because the actual view is elsewhere; conversely, the user might accidentally tap where the view actually is, and the tap will hit the animated view even though it appears to be elsewhere.

A simple solution is to disallow touchability entirely during an animation. You can temporarily turn off your entire interface’s touchability with UIApplication’s beginIgnoringInteractionEvents, as I mentioned earlier in this chapter. Even if you don’t do that, view animation ordered through a UIView class method, by default, turns off touchability of a view while it is being animated — though you can override that with .allowUserInteraction in the options: argument.

But what if you do want the user to be able to interact with an animated view? New in iOS 10, there’s a simple solution for that, too: use a property animator! A property animator makes touching an animated view easy; that is part of its purpose.

Before demonstrating that, let’s talk about what you have to do if you’re not using a property animator. The trick, in that case, to hit-test the presentation layer. In this simple example, we have a superview containing a subview. To allow the user to tap on the subview even when it is being animated, we implement hit-test munging in the subview:

override func hitTest(_ point: CGPoint, with e: UIEvent?) -> UIView? {
    let pres = self.layer.presentation()!
    let suppt = self.convert(point, to: self.superview!)
    let prespt = self.superview!.layer.convert(suppt, to: pres)
    return super.hitTest(prespt, with: e)
}

That works. At the same time, however, the animated view, as Apple puts it in the WWDC 2011 videos, “swallows the touch.” For example, suppose the view in motion is a button. Although our hit-test munging makes it possible for the user to tap the button as it is being animated, and although the user sees the button highlight in response, the button’s action message is not sent in response to this highlighting if the animation is in-flight when the tap takes place. This behavior seems unfortunate, but it’s generally possible to work around it — for instance, with a gesture recognizer.

How does a property animator help? By default, a property animator’s isUserInteractionEnabled is true. That means the animated view is touchable. As long as you don’t set the property animator’s isManualHitTestingEnabled to true, the property animator will hit-test the animated view’s presentation layer for you, so that you don’t have to. (If you do set isManualHitTestingEnabled to true, the job of hit-testing is turned back over to you; you might want to do this in complicated situations where the property animator’s hit-test munging isn’t sufficient.)

So view touchability, with a property animator, is the default. Moreover, the animated view doesn’t “swallow the touch.” To animate a button that remains tappable while the animation is in-flight, just animate the button:

let anim = UIViewPropertyAnimator(duration: 10, curve: .linear) {
    self.button.center = goal
}
anim.startAnimation()

So a property animator’s animated view is touchable by the user. And, as I explained in Chapter 4, a property animator’s animation is interruptible. Together, these two facts mean that, with a property animator, it is easy to alternate between a view’s being animated and the same view’s being manipulated by the user.

In this example, we extend the preceding example. The view is slowly animating its way toward the goal position. But at any time, the user can grab it and drag it around (during which time, the animation is interrupted). As soon as the user releases the view, the animation resumes: the view continues on its way toward the goal position.

Obviously, in order to be draggable, the view has a UIPanGestureRecognizer. All the work takes place in the gesture recognizer’s action method. As usual, we have a switch statement that tests the gesture recognizer’s state. In the .began case, we interrupt the animation so that dragging can happen:

case .began:
    if anim.state == .active {
        anim.stopAnimation(true)
    }
    fallthrough

The .changed case is our usual code for making a view draggable, so I won’t bother to repeat it here. The .ended case is the really interesting part.

Our aim here is to resume animating the view from wherever it now is toward the goal. We can do this by supplying the same animation and calling continueAnimation(withTimingParameters:durationFactor:). But we need first to calculate the durationFactor: argument. This needs to be a ratio proportional to our original duration. In my implementation, the speed at which the view moves should remain the same. Thus, the ratio of durations is the ratio of distances — the distance of the view’s original position from the goal, and its current distance from the goal:

case .ended:
    // how far are we from the goal relative to original distance?
    func pyth(_ pt1:CGPoint, _ pt2:CGPoint) -> CGFloat {
        let x = pt1.x - pt2.x
        let y = pt1.y - pt2.y
        return sqrt(x*x + y*y)
    }
    let origd = pyth(self.oldButtonCenter, self.goal)
    let curd = pyth(v.center, self.goal)
    let factor = curd/origd
    anim.addAnimations {
        self.button.center = self.goal
    }
    anim.startAnimation()
    anim.pauseAnimation()
    anim.continueAnimation(
        withTimingParameters: anim.timingParameters,
        durationFactor: factor)