iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIPresentationController Class Reference

Options
Deployment Target:

On This Page
Language:

UIPresentationController

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 8.0 and later.

A UIPresentationController object provides advanced view and transition management for presented view controllers. From the time a view controller is presented until the time it is dismissed, UIKit uses a presentation controller to manage various aspects of the presentation process for that view controller. The presentation controller can add its own animations on top of those provided by animator objects, it can respond to size changes, and it can manage other aspects of how the view controller is presented onscreen.

When you present a view controller using the presentViewController:animated:completion: method, UIKit always manages the presentation process. Part of that process involves creating the presentation controller that is appropriate for the given presentation style. For the built-in styles (such as the UIModalPresentationPageSheet style), UIKit defines and creates the needed presentation controller object. The only time your app can provide its own presentation controller is for a view controller whose presentation style is set to UIModalPresentationCustom. For custom presentation styles, you have the option of providing a custom presentation controller or using a default presentation controller. You might provide a custom presentation controller when you want to add a shadow view or decoration views underneath the view controller being presented or when you want to modify the presentation behavior in other ways.

When you want UIKit to use your custom presentation controller, you must vend that object to UIKit through your view controller’s transitioning delegate. UIKit maintains a reference to your presentation controller object while the presented view controller is onscreen. For information about the transitioning delegate and the objects it provides, see UIViewControllerTransitioningDelegate Protocol Reference.

The Presentation Process

The presentation process managed by a presentation controller is divided into three phases:

  • The presentation phase involves moving the new view controller onscreen through a series of transition animations.

  • The management phase involves responding to environment changes (such as device rotations) while the new view controller is onscreen.

  • The dismissal phase involves moving the new view controller off screen through a series of transition animations

The presentation controller’s role during all of these phases is to manage its own custom views and state information. During the presentation and dismissal phases, the presentation controller adds its custom views (if any) to the view hierarchy and creates any appropriate transition animations for those views. The animation of the view controller’s view onto the screen is still managed by an animator object—that is, an object that adopts the UIViewControllerAnimatedTransitioning protocol. UIKit calls separate presentation controller methods at the beginning and end of the presentation and dismissal phases so that the presentation controller can perform any needed cleanup.

Adding Custom Views to a Presentation

The UIPresentationController class defines specific entry points for manipulating the view hierarchy when presenting a view controller. When a view controller is about to be presented, UIKit calls the presentation controller’s presentationTransitionWillBegin method. You can use that method to add views to the view hierarchy and set up any animations related to those views. At the end of the presentation phase, UIKit calls the presentationTransitionDidEnd: method to let you know that the transition finished.

Listing 1 shows a sample implementation of the presentationTransitionWillBegin and presentationTransitionDidEnd: methods for a custom presentation controller. In this example, the view controller adds a dimming view as a backdrop to the presented view controller. (The _dimmingView variable refers to a custom UIView object that you would provide.) When presenting the view controller, the presentationTransitionWillBegin method adds the dimming view first and embeds the view controller content inside that dimming view. It then configures a fade-in animation to run alongside the other transition animations. If the user aborts the presentation process, perhaps through an interactive gesture, the presentationTransitionDidEnd: removes the dimming view. If the presentation succeeds, both the dimming view and the presented view controller remain onscreen until they are dismissed.

Listing 1Adding a custom view during a presentation
  • - (void)presentationTransitionWillBegin {
  • // Add a custom dimming view behind the presented view controller's view
  • [[self containerView] addSubview:_dimmingView];
  • [_dimmingView addSubview:[[self presentedViewController] view]];
  • // Use the transition coordinator to set up the animations.
  • id <UIViewControllerTransitionCoordinatorContext> transitionCoordinator =
  • [[self presentingViewController] transitionCoordinator];
  • // Fade in the dimming view during the transition.
  • [_dimmingView setAlpha:0.0];
  • [transitionCoordinator animateAlongsideTransition:
  • ^(id<UIViewControllerTransitionCoordinatorContext> context) {
  • [_dimmingView setAlpha:1.0];
  • } completion:nil];
  • }
  • - (void)presentationTransitionDidEnd:(BOOL)completed {
  • // Remove the dimming view if the presentation was aborted.
  • if (!completed) {
  • [_dimmingView removeFromSuperview];
  • }
  • }

When dismissing the view controller, use the dismissalTransitionWillBegin method to configure any animations and use the dismissalTransitionDidEnd: method to remove any custom views from the view hierarchy.

Adapting to Size Class Changes

Size class changes signal large-scale changes to how your app should present its content. Presentation controllers manage size class changes by adjusting the presentation style (as needed) for their presented view controller. Adjustments are made only when the current presentation style does not make sense in the new environment. For example, a popover becomes a full-screen presentation when the size class changes from horizontally regular to horizontally compact. For presentation styles that already make sense in the new environment, such as a full-screen presentation style, no adaptive change is made.

When the size class of the presented view controller changes from horizontally regular to horizontally compact, the presentation controller calls its adaptivePresentationStyle method to determine which new style (if any) to apply. When a new style is needed, the presentation controller initiates a transition to the new style, which may also involve replacing the current presentation controller object with a new object. Because the presentation controller object may change, always retrieve the presentation controller from presentationController property of the presented view controller.

When the presentation style changes, the presentation controller also gives you the opportunity to specify a new presented view controller. Before initiating the transition, the presentation controller calls the presentationController:viewControllerForAdaptivePresentationStyle: method of its delegate object. If you implement that method, you can use it to make major or minor adjustments to the presented content. A major adjustment would be to replace the current view controller with an entirely new view controller that was designed specifically for the given size class. A minor adjustment would be to install the current view controller inside a navigation controller to facilitate navigation in the new size class.

Responding to Size Changes

Size changes represent small changes to the width or height of a view controller’s view. Typically, these changes happen when the device rotates between portrait and landscape orientations. When a size change occurs, UIKit calls the presentation controller’s viewWillTransitionToSize:withTransitionCoordinator: method. In a custom presentation, use that method to modify your presentation controller’s custom views or make changes to the view hierarchy. For example, you might swap out custom decoration views with ones that fit the new size better.

After notifying your presentation controller of an impending size change, UIKit begins the normal view layout process. Apps that use auto layout should not need to do anything because the auto layout mechanism resizes views as needed. But if a custom presentation controller needs to make layout-specific changes, it can do so in its containerViewWillLayoutSubviews and containerViewDidLayoutSubviews methods. These methods are equivalent to the viewWillLayoutSubviews and viewDidLayoutSubviews methods of the UIViewController class and used in the same way. UIKit calls them before and after it calls the layoutSubviews methods of the views in the view hierarchy.

Subclassing Notes

For custom presentation styles, you should subclass UIPresentationController and override at least some of its methods to implement your custom presentation behaviors. Use your custom presentation controller to customize the presentation process.

For custom presentation controllers, you must call the initWithPresentedViewController:presentingViewController: method during initialization. That method is the designated initializer of the class. UIKit uses it to perform required initialization for all presentation controller objects.

Methods to Override

If your UIPresentationController subclasses manages one or more custom views, you should consider overriding the following methods:

Subclasses may override other methods of this class as needed to provide custom behavior. For example, you might override the shouldPresentInFullscreen or frameOfPresentedViewInContainerView methods and return different values than those provided by the default implementations.

  • Initializes and returns a presentation controller for transitioning between the specified view controllers

    Declaration

    Swift

    init(presentedViewController presentedViewController: UIViewController!, presentingViewController presentingViewController: UIViewController!)

    Objective-C

    - (instancetype)initWithPresentedViewController:(UIViewController *)presentedViewController presentingViewController:(UIViewController *)presentingViewController

    Parameters

    presentedViewController

    The view controller being presented modally.

    presentingViewController

    The view controller whose content represents the starting point of the transition.

    Return Value

    An initialized presentation controller object or nil if the presentation controller could not be initialized.

    Discussion

    This method is the designated initializer for the presentation controller. You must call it from any custom initialization methods you define for your presentation controller subclasses.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The view controller that is the starting point for the presentation. (read-only)

    Declaration

    Swift

    var presentingViewController: UIViewController { get }

    Objective-C

    @property(nonatomic, retain, readonly) UIViewController *presentingViewController

    Discussion

    The object in this property could be the root view controller of the window, a parent view controller that is marked as defining the current context, or the last view controller that was presented onscreen. This view controller may or may not be the same one whose presentViewController:animated:completion: method was called to initiate the presentation process. It may also not be the view controller used to initialize your presentation controller.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The view controller being presented. (read-only)

    Declaration

    Swift

    var presentedViewController: UIViewController { get }

    Objective-C

    @property(nonatomic, retain, readonly) UIViewController *presentedViewController

    Discussion

    This object corresponds to the one passed as the first parameter of the presentViewController:animated:completion: method. The successful conclusion of the presentation process causes this view controller’s content to be displayed onscreen.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The view in which the presentation occurs. (read-only)

    Declaration

    Swift

    var containerView: UIView! { get }

    Objective-C

    @property(nonatomic, readonly) UIView *containerView

    Discussion

    UIKit sets the value of this property shortly after receiving the presentation controller from your transitioning delegate. The container view is always an ancestor of both the presenting view controller’s view and the presented view controller’s view. When adding custom views to a presentation, add them to the container view.

    If your transition also employs custom animator objects, those objects can get this container view from the containerView property of the context object provided by UIKit.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The view to be animated during the presentation.

    Declaration

    Swift

    func presentedView() -> UIView!

    Objective-C

    - (UIView *)presentedView

    Return Value

    The view to present. This view must be either the presented view controller’s view or an ancestor of that view.

    Discussion

    The default implementation of this method returns the presented view controller’s view. If you want to animate a different view, you may override this method and return that view. The view you specify must either be the presented view controller’s view or must be one of its ancestors.

    The view returned by this method is also provided to any animator objects implementing the transition. The animator objects can get the view using the viewForKey: method of the context object provided by UIKit.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The frame rectangle to assign to the presented view at the end of the animations.

    Declaration

    Swift

    func frameOfPresentedViewInContainerView() -> CGRect

    Objective-C

    - (CGRect)frameOfPresentedViewInContainerView

    Return Value

    The rectangle of the presented view controller’s view, specified in the container view’s coordinate system.

    Discussion

    The default implementation of this method returns the frame rectangle of the container view, which results in the presented view controller’s content occupying the entire presentation space. You can override this method and return a different frame rectangle as needed. For example, you might specify a smaller frame rectangle if you want some of the underlying content to show around the edges of the presented view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Interface traits for the presented view controller, to use in place of traits from the iOS environment.

    Declaration

    Swift

    @NSCopying var overrideTraitCollection: UITraitCollection?

    Objective-C

    @property(nonatomic, copy) UITraitCollection *overrideTraitCollection

    Discussion

    Use this property to provide an interface trait collection for the presented view controller, overriding one or more values in the iOS trait environment.

    Each value you place in the overrideTraitCollection property overrides the corresponding value in the iOS trait environment. For example, the following code snippet shows how to override the display scale for the presented view controller, leaving other traits as they are provided by the system. Place such code, typically, in the implementation file for the presenting view controller:

    • presentedVC.presentationController.overrideTraitCollection = [UITraitCollection traitCollectionWithDisplayScale: 1.5];
    • [self presentViewController: presentedVC animated: NO completion: nil];

    The presenting view controller is not affected by use of this property.

    The default value of the overrideTraitCollection property is nil, which results in the full iOS trait environment being used by the presented view controller.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Notifies the presentation controller that layout is about to begin on the views of the container view.

    Declaration

    Swift

    func containerViewWillLayoutSubviews()

    Objective-C

    - (void)containerViewWillLayoutSubviews

    Discussion

    UIKit calls this method before adjusting the layout of the views in the container view. Use this method and the containerViewDidLayoutSubviews method to update any custom views managed by your presentation controller.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Called to notify the presentation controller that layout ended on the views of the container view.

    Declaration

    Swift

    func containerViewDidLayoutSubviews()

    Objective-C

    - (void)containerViewDidLayoutSubviews

    Discussion

    UIKit calls this method after adjusting the layout of the views in the container view. Use this method to make any additional changes to the view hierarchy.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Notifies the presentation controller that the presentation animations are about to start.

    Declaration

    Swift

    func presentationTransitionWillBegin()

    Objective-C

    - (void)presentationTransitionWillBegin

    Discussion

    The default implementation of this method does nothing. Subclasses can override it and use it to add custom views to the view hierarchy and to create any animations associated with those views. To create your animations, get the transition coordinator of the presented view controller and use its animateAlongsideTransition:completion: or animateAlongsideTransitionInView:animation:completion: method to enqueue the animations. Calling those methods ensures that your animations are executed at the same time as any other transition animations.

    For an example of how to implement this method, see Adding Custom Views to the Presentation.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Notifies the presentation controller that the presentation animations finished.

    Declaration

    Swift

    func presentationTransitionDidEnd(_ completed: Bool)

    Objective-C

    - (void)presentationTransitionDidEnd:(BOOL)completed

    Parameters

    completed

    YEStrue if the animations completed and the presented view controller is now visible or NOfalse if the animations were canceled and the presenting view controller is still visible.

    Discussion

    The default implementation of this method does nothing. Subclasses can override this method and use it to perform any required cleanup. For example, if the completed parameter is NOfalse, you would use this method to remove any custom views from the view hierarchy.

    For an example of how to implement this method, see Adding Custom Views to the Presentation.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Notifies the presentation controller that the dismissal animations are about to start.

    Declaration

    Swift

    func dismissalTransitionWillBegin()

    Objective-C

    - (void)dismissalTransitionWillBegin

    Discussion

    The default implementation of this method does nothing. Subclasses can override this method and use it to configure any animations associated with the custom presentation views. To create your animations, get the transition coordinator of the presented view controller and use its animateAlongsideTransition:completion: or animateAlongsideTransitionInView:animation:completion: method to perform the animations. Calling those methods ensures that your animations are executed at the same time as any other transition animations.

    You should not use this method to remove your views from the view hierarchy. Remove your views in the dismissalTransitionDidEnd: method instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Notifies the presentation controller that the dismissal animations finished.

    Declaration

    Swift

    func dismissalTransitionDidEnd(_ completed: Bool)

    Objective-C

    - (void)dismissalTransitionDidEnd:(BOOL)completed

    Parameters

    completed

    YEStrue if the animations completed and the presented view controller was dismissed or NOfalse if the animations were canceled and the presented view controller is still visible.

    Discussion

    The default implementation of this method does nothing. Subclasses can override this method and use it to remove any custom views that the presentation controller added to the view hierarchy. Remove your views only if the completed parameter is YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The presentation style of the presented view controller. (read-only)

    Declaration

    Swift

    var presentationStyle: UIModalPresentationStyle { get }

    Objective-C

    @property(nonatomic, readonly) UIModalPresentationStyle presentationStyle

    Discussion

    This property is set to the presentation style of the presented view controller. The presentation controller uses this style to determine the initial appearance of the presented content.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Returns the presentation style to use when the presented view controller becomes horizontally compact.

    Declaration

    Swift

    func adaptivePresentationStyle() -> UIModalPresentationStyle

    Objective-C

    - (UIModalPresentationStyle)adaptivePresentationStyle

    Return Value

    The value provided by the presentation controller’s delegate or UIModalPresentationNone if a delegate was not provided or does not return a valid value.

    Discussion

    After the content managed by the presentation controller is onscreen, this method returns the presentation style to use when transitioning to a horizontally compact environment. The default implementation of this method consults its delegate object and returns the value provided by that object’s adaptivePresentationStyleForPresentationController: method. Some system-supplied presentation controllers may also provide a new style that is more suited for a compact environment. For example, presentation controllers that manage popovers and form sheets return the UIModalPresentationFullScreen value.

    This method only returns the presentation style to use in a horizontally compact environment. It does not initiate a transition to the new style. The system initiates the transition to the new style when the size class actually changes. When transitioning to a new style, the actual presentation controller object may change. As a result, do not cache the presentation controller object in your code. Always retrieve it from your view controller’s presentationController property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the presentation covers the entire screen.

    Declaration

    Swift

    func shouldPresentInFullscreen() -> Bool

    Objective-C

    - (BOOL)shouldPresentInFullscreen

    Return Value

    YEStrue if the presentation covers the screen or NOfalse if it covers all or part of the current view controller only.

    Discussion

    The default implementation of this method returns YEStrue, indicating that the presentation covers the entire screen. You can override this method and return NOfalse to force the presentation to display only in the current context.

    If you override this method, do not call super.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A Boolean value indicating whether the presenting view controller’s view should be removed when the presentation animations finish.

    Declaration

    Swift

    func shouldRemovePresentersView() -> Bool

    Objective-C

    - (BOOL)shouldRemovePresentersView

    Return Value

    YEStrue if the view should be removed or NOfalse if it should not.

    Discussion

    The default implementation of this method returns NOfalse. If you implement a presentation that does not cover the presenting view controller’s content entirely, override this method and return NOfalse.

    If you override this method, do not call super.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • delegate delegate Property

    The delegate object for managing adaptive presentations.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIAdaptivePresentationControllerDelegate?

    Objective-C

    @property(nonatomic, assign) id< UIAdaptivePresentationControllerDelegate > delegate

    Discussion

    When the app’s size changes, the presentation controller works with this delegate object to determine an appropriate response. View controllers presented using the UIModalPresentationFormSheet, UIModalPresentationPopover, or UIModalPresentationCustom style must change to use one of the full-screen presentation styles instead. The delegate can also opt to change the presented view controller entirely.

    The object you assign to this property must conform to the UIAdaptivePresentationControllerDelegate protocol.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.