UIViewControllerTransitionCoordinator

Important

This is a preliminary document for an API or technology in development. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein for use on Apple-branded products. This information is subject to change, and software implemented according to this document should be tested with final operating system software and final documentation. Newer versions of this document may be provided with future betas of the API or technology.

An object that adopts the UIViewControllerTransitionCoordinator protocol provides support for animations associated with a view controller transition. Typically, you do not adopt this protocol in your own classes. When you present or dismiss a view controller, UIKit creates a transition coordinator object automatically and assigns it to the view controller’s transitionCoordinator property. That transition coordinator object is ephemeral and lasts for the duration of the transition animation.

You can use a transition coordinator object to perform tasks that are related to a transition but that are separate from what the animator objects are doing. During a transition, the animator objects are responsible for putting the new view controller content onscreen, but there may be other visual elements that need to be displayed too. For example, a presentation controller might want to animate the appearance or disappearance of decoration views that are separate from the view controller content. In that case, it uses the transition coordinator to perform those animations.

The transition coordinator works with the animator objects to ensure that any extra animations are performed in the same animation group as the transition animations. Having the animations in the same group means that they execute at the same time and can all respond to timing changes provided by an interactive animator object. These timing adjustments happen automatically and do not require any extra code on your part.

Using the transition coordinator to handle view hierarchy animations is preferred over making those same changes in the viewWillAppear: or similar methods of your view controllers. The blocks you register with the methods of this protocol are guaranteed to execute at the same time as the transition animations. More importantly, the transition coordinator provides important information about the state of the transition, such as whether it was cancelled, to your animation blocks through the UIViewControllerTransitionCoordinatorContext object.

In addition to registering animations to perform during the transition, you can call the notifyWhenInteractionEndsUsingBlock: method to register a block to clean up animations associated with an interactive transition. Cleaning up is particularly important when the user cancels a transition interactively. When a cancellation occurs, you need to return to the original view hierarchy state as it existed before the transition.

Because the transition coordinator is in effect only during a transition, UIKit releases the object when the transition finishes and the final callback is made.

Parameters

animation

A block containing the animations you want to perform. These animations run in the same context as the transition animations and therefore have the same default attributes. You may specify nil for this parameter.

Return Value

YEStrue if the animations were successfully queued to run or NOfalse if they were not.

Discussion

Use this method to perform animations that are not handled by the animator objects themselves. All of the animations you specify must occur inside the animation context’s container view (or one of its descendants). Use the containerView property of the context object to get the container view. To perform animations in a view that does not descend from the container view, use the animateAlongsideTransitionInView:animation:completion: method instead.

The animations in the animation parameter are normally performed concurrently with the view controller transition animations. That behavior applies when the animator object’s animateTransition: method is implemented using UIView-based animations. If the animator object uses Core Animation to animate the layer contents directly, your animations are run shortly after the animateTransition: method returns.

This method returns NOfalse when the block in the animation parameter cannot be queued to run. The completion block can still run even when this method returns NOfalse.

Parameters

view

The view (or one of its ancestors) in which the specified animations take place. This parameter must not be nil.

animation

A block containing the animations you want to perform. These animations run in the same context as the transition animations and therefore have the same default attributes. You may specify nil for this parameter.

Return Value

YEStrue if the specified animation is successfully queued to run; otherwise NOfalse.

Discussion

Use this method to perform animations that are not handled by the animator objects themselves. The animations you specify in the animation parameter must all take place in a view descended from the view you specify in the view parameter.

The animations in the animation parameter are normally performed concurrently with the view controller transition animations. That behavior applies when the animator object’s animateTransition: method is implemented using UIView-based animations. If the animator object uses Core Animation to animate the layer contents directly, your animations are run shortly after the animateTransition: method returns.

This method returns NOfalse when the block in the animation parameter cannot be queued to run. The completion block can still run even when this method returns NOfalse.

Discussion

Your block is executed both when the transition completes normally and when the user cancels the transition. In the case where the user cancels the transition, UIKit executes your context block, calls the viewWillDisappear: method on the presented view controller, and finally calls the viewWillAppear: method on the original view controller to signal that it is once again visible.