UIViewControllerContextTransitioning Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 7.0 and later.
Declared in
UIViewControllerTransitioning.h

Overview

Use the methods of the UIViewControllerContextTransitioning protocol to retrieve view transition context information in a custom transition delegate (a custom object that conforms to the UIViewControllerAnimatorTransitioning or UIViewControllerInteractiveTransitioning protocol).

iOS represents transition context in instances of system classes that adopt this protocol. The system passes such objects to your transition delegate during a view transition.

Call the updateInteractiveTransition: method, from an interactive animator, to report the completion status of an animation. When a user gesture indicates that a transition should end, call the finishInteractiveTransition or cancelInteractiveTransition method, depending on the user’s intent.

Tasks

Accessing the Transition Objects

Defining the Transition Behaviors

Reporting the Transition Progress

Getting the Transition Frame Rectangles

Instance Methods

cancelInteractiveTransition

Notifies the system that user interactions canceled the transition. (required)

- (void)cancelInteractiveTransition
Discussion

While tracking user interactions, your gesture recognizer or event-handling code would call this method when interactions suggest that the user wants to cancel or abort the view controller transition. For example, if the user reverses the swipe direction and then touch events end, suggesting that the user decided against the transition, you would call this method.

You typically follow calls to this method with a call to the completeTransition: method to finalize the transition.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

completeTransition:

Notifies the system that the transition animation is done. (required)

- (void)completeTransition:(BOOL)didComplete
Parameters
didComplete

Pass YES if the transition to the presented view controller completed successfully or NO if the original view controller is still being displayed.

Discussion

Call this method after your animations have completed to notify the system that the transition animation is done. The default implementation of this method calls the animator’s animationEnded: method to give it a chance to perform any last minute cleanup.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

containerView

The view that acts as the superview for the views involved in the transition. (required)

- (UIView *)containerView
Return Value

The view that contains both views involved in the transition.

Discussion

The views associated with the transitioning view controllers should use the container view as their superview during the animation sequence. The view of the currently active view controller is likely already a subview of this container view but the view belonging to the view controller being presented may need to be added. You should make any changes needed to reflect the view hierarchy that you ultimately want.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

finalFrameForViewController:

Returns the ending frame rectangle for the specified view controller’s view. (required)

- (CGRect)finalFrameForViewController:(UIViewController *)vc
Parameters
vc

The view controller whose frame rectangle you want.

Return Value

The frame rectangle for the view or CGRectZero if the frame rectangle is not known or the view is not visible.

Discussion

The rectangle returned by this method represents the size of the corresponding view at the end of the transition. For the starting view controller, the value returned by this method might be CGRectZero if the corresponding view was completely covered during the transition, but it might also be a valid frame rectangle.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

finishInteractiveTransition

Notifies the system that user interactions signaled the completion of the transition. (required)

- (void)finishInteractiveTransition
Discussion

While tracking user interactions, your gesture recognizer or event-handling code should call this methods when the interactions suggest that the transition is now complete. For example, if the user swipes a finger, and the touch events indicate that the swipe distance crossed the threshold needed to complete the gesture, call this method when the corresponding touch events end to let the system know that it can now complete the transition.

You typically follow calls to this method with a call to the completeTransition: method to finalize the transition.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

initialFrameForViewController:

Returns the starting frame rectangle for the specified view controller’s view. (required)

- (CGRect)initialFrameForViewController:(UIViewController *)vc
Parameters
vc

The view controller whose frame rectangle you want.

Return Value

The frame rectangle for the view or CGRectZero if the frame rectangle is not known or the view is not visible.

Discussion

The rectangle returned by this method represents the size of the corresponding view at the beginning of the transition. For the view controller being presented, the value returned by this method is typically CGRectZero because the view is not yet on screen.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

isAnimated

Returns a Boolean value indicating, in the case of a modal presentation style, whether the transition should be animated. (required)

- (BOOL)isAnimated
Return Value

Always returns YES for modal presentations styles other than the UIModalPresentationCustom style. For the UIModalPresentationCustom style, returns YES if the transition should be animated or NO if it should not.

Discussion

Call this method to determine whether a custom transition should be animated into place. If this method returns NO, insert the final views into the container view without animating the change.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

isInteractive

Returns a Boolean value indicating whether the transition is interactive. (required)

- (BOOL)isInteractive
Return Value

YES if the transition is interactive or NO if it is not.

Discussion

A transition is interactive only if the view controller’s delegate provides a corresponding interactive animator object.

Interactive transitions are drive by user-generated events. One common scenario is to use a gesture recognizer to report on the current progress of the animation. The gesture recognizer calls methods of this context object that indicate the completion percentage of the transition or indicate that the transition was canceled or completed by the user.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

presentationStyle

Returns the presentation style for the view controller transition. (required)

- (UIModalPresentationStyle)presentationStyle
Return Value

The presentation style to use when presenting the final view controller.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

transitionWasCancelled

A Boolean value that indicates whether or not the transition was canceled. (required)

- (BOOL)transitionWasCancelled
Return Value

YES if the transition was canceled; otherwise, NO.

Discussion

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

updateInteractiveTransition:

Updates the completion percentage of the transition. (required)

- (void)updateInteractiveTransition:(CGFloat)percentComplete
Discussion

While tracking user events, your code should call this method regularly to update the current progress toward completing the transition. If, during tracking, the interactions cross a threshold that you consider signifies the completion or cancellation of the transition, stop tracking events and call the finishInteractiveTransition or cancelInteractiveTransition method.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

viewControllerForKey:

Returns the specified view controller involved in the transition. (required)

- (UIViewController *)viewControllerForKey:(NSString *)key
Parameters
key

The key identifying the view controller you want. For a list of possible keys, see “View Controller Transition Keys.”

Return Value

The view controller object for the specified key or nil if the view controller could not be found.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIViewControllerTransitioning.h

Constants

View Controller Transition Keys

The keys you use to identify the view controllers involved in a transition.

NSString *const UITransitionContextFromViewControllerKey;
NSString *const UITransitionContextToViewControllerKey;
Constants
UITransitionContextFromViewControllerKey

Identifies the view controller that is visible at the beginning of the transition (and at the end of a canceled transition). This view controller is typically the one presenting the "to” view controller or is the one being replaced by the "to” view controller.

Available in iOS 7.0 and later.

Declared in UIViewControllerTransitioning.h.

UITransitionContextToViewControllerKey

Identifies the view controller that is visible at the end of a completed transition. This view controller is the one being presented.

Available in iOS 7.0 and later.

Declared in UIViewControllerTransitioning.h.