What exactly does bool parameter do in animateWithDuration:animations:completion:

Question

I referred to the DOC and it said:

completion
... This block has no return value and takes a single Boolean argument that indicates whether or not the animations actually finished before the completion handler was called. ...

But I find that no matter you use the bool parameter or not, the completion: block will always execute after animations: block. Just like the two simple block-based animation code snippets shown below, both of them are doing the same.

[UIView animateWithDuration:0.3f
                  delay:0.0f
                options:UIViewAnimationCurveEaseInOut
             animations:^{
                 [myView setAlpha:0.0f];
             }
             completion:^(BOOL finished) {
                 [myView removeFromSuperview];
             }];

and

[UIView animateWithDuration:0.3f
                  delay:0.0f
                options:UIViewAnimationCurveEaseInOut
             animations:^{
                 [myView setAlpha:0.0f];
             }
             completion:^(BOOL finished) {
                 if (finished) [myView removeFromSuperview];
             }];

And I find that most people(including me) use the first one(even the apple's official doc example). So,

• what's the finished parameter used for here exactly?
• or what's the situation will be used?

Solution

The finished parameter will be NO when the animation was cancelled: typically, when you have interrupted the animation to start another one (e.g. you have begun a new animation, before the current one has ended, with the parameter to begin from the current state) or you have directly cancelled the animation.

In effect this cancels the current animation, but the completion block is still called. If you were chaining a sequence of animations you would want that chain to stop, so you would only continue the chain of the previous animation had finished.

As an example, imagine you had a game where a bomb was flying across the screen. If the user doesn't tap the bomb, it explodes when it reaches the edge. So you'd have one animation to move the bomb, and your completion block would have another animation to show the explosion, and maybe a call to some method to decrease a score or something.

If the user taps the bomb, you'd cancel the moving animation and have the bomb fly harmlessly away. Your original completion block would still be executed, so you'd need to know if the animation had finished on its own, or been cancelled.

Comments

[Kjuly]

Thanks for your answer! "you have interrupted the animation to start another one", that may be the situation to use this parameter! But can you offer a simple example? :p "If you were chaining a sequence of animations you would want that chain to stop, so you would only continue the chain of the previous animation had finished", but it won't continue the chain of animations until the previous one had finished without the finished parameter, either. I did by this way(without if statement) for sequence of animations in my app and without any wrong order error.

[jrturton]

I've added a simple example.

[Senseful]

It's unclear how you would "cancel the moving animation" in such a way that would cause finished == false. Any idea how to do so?

[jrturton]

@Senseful I give an example in the first paragraph. If you're interested in cancelling or interrupting animations then you should look at UIViewPropertyAnimator, new in iOS 10.