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?

Answer 1

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.