Is it necessary to test the BOOL finished in a completion handler for UIView animation?

Question

I've never given any thought to the returned BOOL finished of a UIView animation completion handler, but reading some sample code in the Apple UIView Programming Guide shows this:

completion:^(BOOL finished) {
 if (finished) {

Is this necessary? The completion block shouldn't run unless the animation has finished anyway, right? The test seems redundant.

Answer 1

The actual action being undertaken in that code snippet is quite significant. The animation is transitioning from one view to another -- the first is being replaced, and then a boolean is set to keep track of which one is currently displayed. The boolean is set in the completion block.

[UIView transitionFromView:(displayingPrimary ? primaryView : secondaryView)
    toView:(displayingPrimary ? secondaryView : primaryView)
    duration:1.0
    options:(displayingPrimary ? UIViewAnimationOptionTransitionFlipFromRight :
                UIViewAnimationOptionTransitionFlipFromLeft)
    completion:^(BOOL finished) {
        if (finished) {
            displayingPrimary = !displayingPrimary;
        }
}];

In this case, if the animation (for whatever reason) doesn't complete, then the views haven't been exchanged, and you absolutely don't want to flip the value of displayingPrimary, because you'll then have an inaccurate record of your status. That's why the finished flag is checked in this case.

Notice that in most (if not all) of the other code samples in that guide, the flag isn't checked -- that's because it's not significant in those cases (running another animation after the first, e.g., or changing some value that doesn't depend on the successful completion of the animation).

Answer 2

Yes you really should honor that bool in your handler. The user might initiate the animation, but before that animation completes normally, the user does something else to cancel it early. This bool well let you know of such cases.

-- update -- Just to elaborate. Imagine some animation that moves a view across the screen. The handler might fire when the view is done moving. Suppose the user touches somewhere else to cause a new animation that essentially cancels this first one in progress. You could use the provided bool to detect that.