iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIViewControllerTransitionCoordinator Protocol Reference

Options
Deployment Target:

On This Page
Language:

UIViewControllerTransitionCoordinator

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.

  • Runs the specified animations at the same time as the view controller transition animations.

    Declaration

    Swift

    func animateAlongsideTransition(_ animation: ((UIViewControllerTransitionCoordinatorContext) -> Void)?, completion completion: ((UIViewControllerTransitionCoordinatorContext) -> Void)?) -> Bool

    Objective-C

    - (BOOL)animateAlongsideTransition:(void (^ nullable)(id<UIViewControllerTransitionCoordinatorContext> nonnull context))animation completion:(void (^ nullable)(id<UIViewControllerTransitionCoordinatorContext> nonnull context))completion

    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.

    The block has no return value and takes the following parameter:

    context

    The contextual information for performing the animations. Use this object to get the animation-related information, including the container view in which to run your animations. For more information, see UIViewControllerTransitionCoordinatorContext Protocol Reference.

    The animation you specify must take place in a view descended from the container view.

    completion

    The block of code to execute after the transition finishes. You may specify nil for this parameter. The block has no return value and takes the following parameter:

    context

    The contextual information for performing the animations. Use this object to get the animation-related information, including the container view in which to run your animations. For more information, see UIViewControllerTransitionCoordinatorContext Protocol Reference.

    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.

    Availability

    Available in iOS 7.0 and later.

  • Runs the specified animations in a view that is outside of the designated container view.

    Declaration

    Swift

    func animateAlongsideTransitionInView(_ view: UIView?, animation animation: ((UIViewControllerTransitionCoordinatorContext) -> Void)?, completion completion: ((UIViewControllerTransitionCoordinatorContext) -> Void)?) -> Bool

    Objective-C

    - (BOOL)animateAlongsideTransitionInView:(UIView * nullable)view animation:(void (^ nullable)(id<UIViewControllerTransitionCoordinatorContext> nonnull context))animation completion:(void (^ nullable)(id<UIViewControllerTransitionCoordinatorContext> nonnull context))completion

    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.

    The block has no return value and takes the following parameter:

    context

    The contextual information for performing the animations. Use this object to get the animation-related information. For more information, see UIViewControllerTransitionCoordinatorContext Protocol Reference.

    completion

    The block of code to execute after the transition finishes. You may specify nil for this parameter. The block has no return value and takes the following parameter:

    context

    The contextual information for performing the animations. Use this object to get the animation-related information. For more information, see UIViewControllerTransitionCoordinatorContext Protocol Reference.

    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.

    Availability

    Available in iOS 7.0 and later.

  • Registers a block to be executed when a transition changes from interactive to non-interactive.

    Declaration

    Swift

    func notifyWhenInteractionEndsUsingBlock(_ handler: (UIViewControllerTransitionCoordinatorContext) -> Void)

    Objective-C

    - (void)notifyWhenInteractionEndsUsingBlock:(void (^ nonnull)(id<UIViewControllerTransitionCoordinatorContext> nonnull context))handler

    Parameters

    handler

    The block to execute when the transition changes from interactive to noninteractive. The block has no return value and takes the following parameter:

    context

    The contextual information for performing the animations. Use this object to get the animation-related information. For more information, see UIViewControllerTransitionCoordinatorContext Protocol Reference.

    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.

    Inside your block, you can get the value of the isCancelled method of the transition coordinator context and use that value to determine the appropriate course of action. For example, if the transition was cancelled, you might use this block to remove any extra views that were added to the view hierarchy by a previous call to animateAlongsideTransition:completion: or animateAlongsideTransitionInView:animation:completion:.

    You can call this method multiple times to register multiple blocks. All of the registered blocks are executed when the transition state changes.

    Availability

    Available in iOS 7.0 and later.