Starting Animations Using the Block-Based Methods

In iOS 4 and later, you use the block-based class methods to initiate animations. There are several block-based methods that offer different levels of configuration for the animation block. These methods are:

• animateWithDuration:animations:

• animateWithDuration:animations:completion:

• animateWithDuration:delay:options:animations:completion:

Because these are class methods, the animation blocks you create with them are not tied to a single view. Thus, you can use these methods to create a single animation that involves changes to multiple views. For example, Listing 4-1 shows the code needed to fade in one view while fading out another over a one second time period. When this code executes, the specified animations are started immediately on another thread so as to avoid blocking the current thread or your application’s main thread.

Listing 4-1  Performing a simple block-based animation

[UIView animateWithDuration:1.0 animations:^{

        firstView.alpha = 0.0;

        secondView.alpha = 1.0;

}];

The animations in the preceding example run only once using an ease-in, ease-out animation curve. If you want to change the default animation parameters, you must use the animateWithDuration:delay:options:animations:completion: method to perform your animations. This method lets you customize the following animation parameters:

• The delay to use before starting the animation

• The type of timing curve to use during the animation

• The number of times the animation should repeat

• Whether the animation should reverse itself automatically when it reaches the end

• Whether touch events are delivered to views while the animations are in progress

• Whether the animation should interrupt any in-progress animations or wait until those are complete before starting

Another thing that both the animateWithDuration:animations:completion: and animateWithDuration:delay:options:animations:completion: methods support is the ability to specify a completion handler block. You might use a completion handler to signal your application that a specific animation has finished. Completion handlers are also the way to link separate animations together.

Listing 4-2 shows an example of an animation block that uses a completion handler to initiate a new animation after the first one finishes. The first call to animateWithDuration:delay:options:animations:completion: sets up a fade-out animation and configures it with some custom options. When that animation is complete, its completion handler runs and sets up the second half of the animation, which fades the view back in after a delay.

Using a completion handler is the primary way that you link multiple animations.

Listing 4-2  Creating an animation block with custom options

- (IBAction)showHideView:(id)sender

{

    // Fade out the view right away

    [UIView animateWithDuration:1.0

        delay: 0.0

        options: UIViewAnimationOptionCurveEaseIn

        animations:^{

             thirdView.alpha = 0.0;

        }

        completion:^(BOOL finished){

            // Wait one second and then fade in the view

            [UIView animateWithDuration:1.0

                 delay: 1.0

                 options:UIViewAnimationOptionCurveEaseOut

                 animations:^{

                    thirdView.alpha = 1.0;

                 }

                 completion:nil];

        }];

}

Starting Animations Using the Begin/Commit Methods

If your application runs in iOS 3.2 and earlier, you must use the beginAnimations:context: and commitAnimations class methods of UIView to define your animation blocks. These methods mark the beginning and end of your animation block. Any animatable properties you change between these methods are animated to their new values after you call the commitAnimations method. Execution of the animations occurs on a secondary thread so as to avoid blocking the current thread or your application’s main thread.

Listing 4-3 shows the code needed to implement the same behavior as Listing 4-1 but using the begin/commit methods. As in Listing 4-1, this code fades one view out while fading another in over one second of time. However, in this example, you must set the duration of the animation using a separate method call.

Listing 4-3  Performing a simple begin/commit animation

    [UIView beginAnimations:@"ToggleViews" context:nil];

    [UIView setAnimationDuration:1.0];

    // Make the animatable changes.

    firstView.alpha = 0.0;

    secondView.alpha = 1.0;

    // Commit the changes and perform the animation.

    [UIView commitAnimations];

By default, all animatable property changes within an animation block are animated. If you want to animate some changes but not others, use the setAnimationsEnabled: method to disable animations temporarily, make any changes that you do not want animated, and then call setAnimationsEnabled: again to reenable animations. You can determine if animations are current enabled by calling the areAnimationsEnabled class method.

// This method begins the first animation.

- (IBAction)showHideView:(id)sender

{

    [UIView beginAnimations:@"ShowHideView" context:nil];

    [UIView setAnimationCurve:UIViewAnimationCurveEaseIn];

    [UIView setAnimationDuration:1.0];

    [UIView setAnimationDelegate:self];

    [UIView setAnimationDidStopSelector:@selector(showHideDidStop:finished:context:)];

    // Make the animatable changes.

    thirdView.alpha = 0.0;

    // Commit the changes and perform the animation.

    [UIView commitAnimations];

}

// Called at the end of the preceding animation.

- (void)showHideDidStop:(NSString *)animationID finished:(NSNumber *)finished context:(void *)context

{

    [UIView beginAnimations:@"ShowHideView2" context:nil];

    [UIView setAnimationCurve:UIViewAnimationCurveEaseOut];

    [UIView setAnimationDuration:1.0];

    [UIView setAnimationDelay:1.0];

    thirdView.alpha = 1.0;

    [UIView commitAnimations];

}

- (void)animationWillStart:(NSString *)animationID context:(void *)context;

- (void)animationDidStop:(NSString *)animationID finished:(NSNumber *)finished context:(void *)context;

Nesting Animation Blocks

You can assign different timing and configuration options to parts of an animation block by nesting additional animation blocks. As the name implies, a nested animation block is a new animation block created inside an existing animation block. Nested animations are started at the same time as any parent animations but run (for the most part) with their own configuration options. By default, nested animations do inherit the parent’s duration and animation curve but even those options can be overridden as needed.

Listing 4-5 shows an example of how a nested animation is used to change the timing, duration, and behavior of some animations in the overall group. In this case, two views are being faded to total transparency, but the transparency of the anotherView object is changed back and forth several times before it is finally hidden. The UIViewAnimationOptionOverrideInheritedCurve and UIViewAnimationOptionOverrideInheritedDuration keys used in the nested animation block allow the curve and duration values from the first animation to be modified for the second animation. If these keys were not present, the duration and curve of the outer animation block would be used instead.

Listing 4-5  Nesting animations that have different configurations

[UIView animateWithDuration:1.0

        delay: 1.0

        options:UIViewAnimationOptionCurveEaseOut

        animations:^{

            aView.alpha = 0.0;

            // Create a nested animation that has a different

            // duration, timing curve, and configuration.

            [UIView animateWithDuration:0.2

                 delay:0.0

                 options: UIViewAnimationOptionOverrideInheritedCurve |

                          UIViewAnimationOptionCurveLinear |

                          UIViewAnimationOptionOverrideInheritedDuration |

                          UIViewAnimationOptionRepeat |

                          UIViewAnimationOptionAutoreverse

                 animations:^{

                      [UIView setAnimationRepeatCount:2.5];

                      anotherView.alpha = 0.0;

                 }

                 completion:nil];

        }

        completion:nil];

If you are using the begin/commit methods to create your animations, nesting works in much the same way as with the block-based methods. Each successive call to beginAnimations:context: within an already open animation block creates a new nested animation block that you can configure as needed. Any configuration changes you make apply to the most recently opened animation block. All animation blocks must be closed with a call to commitAnimations before the animations are submitted and executed.

Implementing Animations That Reverse Themselves

When creating reversible animations in conjunction with a repeat count, consider specifying a non integer value for the repeat count. For an autoreversing animation, each complete cycle of the animation involves animating from the original value to the new value and back again. If you want your animation to end on the new value, adding 0.5 to the repeat count causes the animation to complete the extra half cycle needed to end at the new value. If you do not include this half step, your animation will animate to the original value and then snap quickly to the new value, which may not be the visual effect you want.

Changing the Subviews of a View

Changing the subviews of a view allows you to make moderate changes to the view. For example, you might add or remove subviews to toggle the superview between two different states. By the time the animations finish, the same view is displayed but its contents are now different.

In iOS 4 and later, you use the transitionWithView:duration:options:animations:completion: method to initiate a transition animation for a view. In the animations block passed to this method, the only changes that are normally animated are those associated with showing, hiding, adding, or removing subviews. Limiting animations to this set allows the view to create a snapshot image of the before and after versions of the view and animate between the two images, which is more efficient. However, if you need to animate other changes, you can include the UIViewAnimationOptionAllowAnimatedContent option when calling the method. Including that option prevents the view from creating snapshots and animates all changes directly.

Listing 4-6 is an example of how to use a transition animation to make it seem as if a new text entry page has been added. In this example, the main view contains two embedded text views. The text views are configured identically, but one is always visible while the other is always hidden. When the user taps the button to create a new page, this method toggles the visibility of the two views, resulting in a new empty page with an empty text view ready to accept text. After the transition is complete, the view saves the text from the old page using a private method and resets the now hidden text view so that it can be reused later. The view then arranges its pointers so that it can be ready to do the same thing if the user requests yet another new page.

Listing 4-6  Swapping an empty text view for an existing one

- (IBAction)displayNewPage:(id)sender

{

    [UIView transitionWithView:self.view

        duration:1.0

        options:UIViewAnimationOptionTransitionCurlUp

        animations:^{

            currentTextView.hidden = YES;

            swapTextView.hidden = NO;

        }

        completion:^(BOOL finished){

            // Save the old text and then swap the views.

            [self saveNotes:temp];

            UIView*    temp = currentTextView;

            currentTextView = swapTextView;

            swapTextView = temp;

        }];

}

If you need to perform view transitions in iOS 3.2 and earlier, you can use the setAnimationTransition:forView:cache: method to specify the parameters for the transition. The view you pass to that method is the same one you would pass in as the first parameter to the transitionWithView:duration:options:animations:completion: method. Listing 4-7 shows the basic structure of the animation block you need to create. Note that to implement the completion block shown in Listing 4-6, you would need to configure an animation delegate with a did-stop handler as described in Configuring an Animation Delegate.

Listing 4-7  Changing subviews using the begin/commit methods

    [UIView beginAnimations:@"ToggleSiblings" context:nil];

    [UIView setAnimationTransition:UIViewAnimationTransitionCurlUp forView:self.view cache:YES];

    [UIView setAnimationDuration:1.0];

    // Make your changes

    [UIView commitAnimations];

Replacing a View with a Different View

Replacing views is something you do when you want your interface to be dramatically different. Because this technique swaps only views (and not view controllers), you are responsible for designing your application’s controller objects appropriately. This technique is simply a way of presenting new views quickly using some standard transitions.

In iOS 4 and later, you use the transitionFromView:toView:duration:options:completion: method to transition between two views. This method actually removes the first view from your hierarchy and inserts the other, so you should make sure you have a reference to the first view if you want to keep it. If you want to hide views instead of remove them from your view hierarchy, pass the UIViewAnimationOptionShowHideTransitionViews key as one of the options.

Listing 4-8 shows the code needed to swap between two main views managed by a single view controller. In this example, the view controller’s root view always displays one of two child views (primaryView or secondaryView). Each view presents the same content but does so in a different way. The view controller uses the displayingPrimary member variable (a Boolean value) to keep track of which view is displayed at any given time. The flip direction changes depending on which view is being displayed.

Listing 4-8  Toggling between two views in a view controller

- (IBAction)toggleMainViews:(id)sender {

    [UIView transitionFromView:(displayingPrimary ? primaryView : secondaryView)

        toView:(displayingPrimary ? secondaryView : primaryView)

        duration:1.0

        options:(displayingPrimary ? UIViewAnimationOptionTransitionFlipFromRight :

                    UIViewAnimationOptionTransitionFlipFromLeft)

        completion:^(BOOL finished) {

            if (finished) {

                displayingPrimary = !displayingPrimary;

            }

    }];

}