iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIPopoverPresentationController Class Reference

Options
Deployment Target:

On This Page
Language:

UIPopoverPresentationController

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 8.0 and later.

A UIPopoverPresentationController object manages the display of content in a popover. From the time a popover is presented until the time it is dismissed, UIKit uses an instance of this class to manage the presentation behavior. You use instances of this class as-is to configure aspects of the popover appearance and behavior for view controllers whose presentation style is set to UIModalPresentationPopover.

In nearly all cases, you use this class as-is and do not create instances of it directly. UIKit creates an instance of this class automatically when you present a view controller using the UIModalPresentationPopover style. You can retrieve that instance from the presented view controller’s popoverPresentationController property and use it to configure the popover behavior.

If you do not want to configure a popover immediately after presenting a view controller, you can use a delegate object to configure the popover instead. During the presentation process, the popover presentation controller calls various methods of its delegate—an object that conforms to the UIPopoverPresentationControllerDelegate protocol—to ask for information and to inform it about the state of the presentation. Your delegate object can use those methods to configure the popover and adjust its behavior as needed. For information about how to implement a delegate for a popover presentation controller, see UIPopoverPresentationControllerDelegate Protocol Reference.

Configuring a Popover for Display

To display a popover, set the presentation style of your view controller to UIModalPresentationPopover and call the presentViewController:animated:completion: method. Presenting a view controller with the popover style creates a popover presentation controller to manage the presentation process. You can retrieve that presentation controller from the presented view controller’s popoverPresentationController property and use the object to configure the popover behavior.

Listing 1 shows an example of how you present a view controller using the popover style. After setting the style and calling the presentViewController:animated:completion: method, you can fetch the presentation controller and modify its properties. When configuring popovers, always specify either a bar button item or a source view and rectangle as the anchor point for the popover. You can configure other properties as well to accommodate the presented content.

Listing 1Presenting a popover
  • // Present the view controller using the popover style.
  • myPopoverViewController.modalPresentationStyle = UIModalPresentationPopover;
  • [self presentViewController:myPopoverViewController animated: YES completion: nil];
  • // Get the popover presentation controller and configure it.
  • UIPopoverPresentationController *presentationController =
  • [myPopoverViewController popoverPresentationController];
  • presentationController.permittedArrowDirections =
  • UIPopoverArrowDirectionLeft | UIPopoverArrowDirectionRight;
  • presentationController.sourceView = myView;
  • presentationController.sourceRect = sourceRect;

Configuring the popover presentation controller after calling presentViewController:animated:completion: might seem counter-intuitive but UIKit does not create a presentation controller until after you initiate a presentation. In addition, UIKit must wait until the next update cycle to display new content onscreen anyway. That delay gives you time to configure the presentation controller for your popover.

  • The margins that define the portion of the screen in which it is permissible to display the popover.

    Declaration

    Swift

    var popoverLayoutMargins: UIEdgeInsets

    Objective-C

    @property(nonatomic, readwrite) UIEdgeInsets popoverLayoutMargins

    Discussion

    The edge inset values are measured in points from the edges of the screen, relative to the current device orientation. Thus, the top-edge inset always reflects the top edge of the device from the user’s perspective, which changes depending on whether the user is holding the device in a portrait or landscape orientation. Remember that the device orientation is not always the same as the interface orientation—that is, the orientation of your window and views. Window orientations are typically fixed and view orientations are controlled by the owning view controller. In addition, if the rotation lock option is engaged, the interface does not change orientation at all, even when the device orientation changes.

    The default edge insets are 10 points along each edge. The popover presentation controller automatically subtracts the status bar from the viable area when determining where to display the popover, so you do not need to factor the status bar height into your insets.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The color of the popover’s backdrop view.

    Declaration

    Swift

    @NSCopying var backgroundColor: UIColor!

    Objective-C

    @property(nonatomic, copy) UIColor *backgroundColor

    Discussion

    Use this property to customize the background color of your popover. Changing the value of this property while the popover is visible triggers an animated change to the new color. The default value of this property is nil, which corresponds to the default background color.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • An array of views that the user can interact with while the popover is visible.

    Declaration

    Swift

    var passthroughViews: [AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSArray *passthroughViews

    Discussion

    When a popover is active, interactions with other views are normally disabled until the popover is dismissed. Assigning an array of UIView objects to this property causes UIKit to continue dispatching touch event to the views you specified.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The class to use for displaying the popover background content.

    Declaration

    Swift

    var popoverBackgroundViewClass: AnyObject.Type?

    Objective-C

    @property(nonatomic, readwrite, retain) Class< UIPopoverBackgroundViewMethods > popoverBackgroundViewClass

    Discussion

    The default value of this property is nil, which causes the presentation controller to use the default popover appearance. Setting this property to a value other than nil causes the presentation controller to use the specified class to draw the popover’s background content. The class you specify must be a subclass of UIPopoverBackgroundView.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The bar button item on which to anchor the popover.

    Declaration

    Swift

    var barButtonItem: UIBarButtonItem!

    Objective-C

    @property(nonatomic, retain) UIBarButtonItem *barButtonItem

    Discussion

    Assign a value to this property to anchor the popover to the specified bar button item. When presented, the popover’s arrow points to the specified item. Alternatively, you may specify the anchor location for the popover using the sourceView and sourceRect properties.

    Prior to presentation, the presentation controller adds all sibling bar button items of the specified item (but not the item itself) to the popover’s list of passthrough views. UIKit automatically intercepts taps in the specified item and uses them to dismiss the popover. If you want taps in the other bar button items to dismiss the popover, you must add code to the action handlers of those items to do so yourself.

    The default value of this property is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The view containing the anchor rectangle for the popover.

    Declaration

    Swift

    var sourceView: UIView!

    Objective-C

    @property(nonatomic, retain) UIView *sourceView

    Discussion

    Use this property in conjunction with the sourceRect property to specify the anchor location for the popover. Alternatively, you may specify the anchor location for the popover using the barButtonItem property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The rectangle in the specified view in which to anchor the popover.

    Declaration

    Swift

    var sourceRect: CGRect

    Objective-C

    @property(nonatomic, assign) CGRect sourceRect

    Discussion

    Use this property in conjunction with the sourceView property to specify the anchor location for the popover. Alternatively, you may specify the anchor location for the popover using the barButtonItem property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • delegate delegate Property

    The delegate that handles popover-related messages.

    Declaration

    Swift

    unowned(unsafe) var delegate: UIPopoverPresentationControllerDelegate?

    Objective-C

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

    Discussion

    At various points during the presentation process, the popover presentation controller calls methods of its delegate to give that object a chance to respond. You might use a delegate to further configure the popover presentation controller or to respond to user-initiated actions relating to the popover. For example, immediately prior to displaying the popover, the presentation controller calls the prepareForPopoverPresentation: method of the delegate object.

    For more information about the methods that you can implement in your delegate object, see UIPopoverPresentationControllerDelegate Protocol Reference.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The arrow directions that you prefer for the popover.

    Declaration

    Swift

    var permittedArrowDirections: UIPopoverArrowDirection

    Objective-C

    @property(nonatomic, assign) UIPopoverArrowDirection permittedArrowDirections

    Discussion

    Prior to displaying the popover, set this property to the arrow directions that you prefer for your popover. During presentation, the popover presentation controller tries to respect your preferences but may use a different arrow direction if it cannot otherwise lay out the popover. The actual arrow direction in use by the popover is stored in the arrowDirection property.

    The default value of this property is UIPopoverArrowDirectionAny.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The arrow direction in use by the popover. (read-only)

    Declaration

    Swift

    var arrowDirection: UIPopoverArrowDirection { get }

    Objective-C

    @property(nonatomic, readonly) UIPopoverArrowDirection arrowDirection

    Discussion

    When the popover is onscreen, this property reflects the actual arrow direction. Before and after presentation, the value of this property is UIPopoverArrowDirectionUnknown.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.