UIPopoverController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.2 and later.
Companion guide
Declared in
UIPopoverController.h
Related sample code

Overview

The UIPopoverController class is used to manage the presentation of content in a popover. You use popovers to present information temporarily. The popover content is layered on top of your existing content and the background is dimmed automatically. The popover remains visible until the user taps outside of the popover window or you explicitly dismiss it. Popover controllers are for use exclusively on iPad devices. Attempting to create one on other devices results in an exception.

To display a popover, create an instance of this class and present it using one of the appropriate methods. When initializing an instance of this class, you must specify the view controller that provides the content for the popover. Popovers normally derive their size from the view controller they present. However, you can change the size of the popover by modifying the value in the popoverContentSize property or by calling the setPopoverContentSize:animated: method. The latter approach is particularly effective if you need to animate changes to the popover’s size. The size you specify is just the preferred size for the popover’s view. The actual size may be altered to ensure that the popover fits on the screen and does not collide with the keyboard.

When displayed, taps outside of the popover window cause the popover to be dismissed automatically. To allow the user to interact with the specified views and not dismiss the popover, you can assign one or more views to the passthroughViews property. Taps inside the popover window do not automatically cause the popover to be dismissed. Your view and view controller code must handle actions and events inside the popover explicitly and call the dismissPopoverAnimated: method as needed.

If the user rotates the device while a popover is visible, the popover controller hides the popover and then shows it again at the end of the rotation. The popover controller attempts to position the popover appropriately for you but you can also implement the popoverController:willRepositionPopoverToRect:inView: method in the popover delegate to specify a new position.

You can assign a delegate to the popover to manage interactions with the popover and receive notifications about its dismissal. For information about the methods of the delegate object, see UIPopoverControllerDelegate Protocol Reference.

Tasks

Initializing the Popover

Presenting and Dismissing the Popover

Configuring the Popover Content

Getting the Popover Attributes

Accessing the Delegate

Customizing the Popover Appearance

Properties

backgroundColor

The color of the popover’s backdrop view.

@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 changeover to the new color. The default value of this property is nil, which corresponds to the default background color.

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

contentViewController

The view controller responsible for the content portion of the popover.

@property (nonatomic, retain) UIViewController *contentViewController
Discussion

This property is initially set to the view controller passed to the initWithContentViewController: method. You can change the value of this property later to reflect a new set of content. Changing the value of this property swaps the new view controller in for the old one immediately and does not trigger an animation. If you want to animate the change, use the setContentViewController:animated: method instead.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

delegate

The delegate you want to receive popover controller messages.

@property (nonatomic, assign) id <UIPopoverControllerDelegate> delegate
Discussion

The popover controller uses its delegate to determine whether it should dismiss the popover and provides a notification when such an event occurs. For more information about the methods you can implement in your delegate, see UIPopoverControllerDelegate Protocol Reference.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

passthroughViews

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

@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 views to this property allows taps outside of the popover to be handled by the corresponding views.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

popoverArrowDirection

The direction of the popover’s arrow. (read-only)

@property (nonatomic, readonly) UIPopoverArrowDirection popoverArrowDirection
Discussion

The default value of this property is UIPopoverArrowDirectionUnknown. When you present the popover, the value changes to reflect the actual direction of the arrow being used by the popover. When the popover is subsequently dismissed, the value of this property returns to UIPopoverArrowDirectionUnknown.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

popoverBackgroundViewClass

The class to use for displaying the popover background content.

@property (nonatomic, readwrite, retain) Class popoverBackgroundViewClass
Discussion

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

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPopoverController.h

popoverContentSize

The size of the popover’s content view.

@property (nonatomic) CGSize popoverContentSize
Discussion

This property represents the size of the content view that is managed by the view controller in the contentViewController property. The initial value of this property is set to value in the view controller’s contentSizeForViewInPopover property. Changing the value of this property overrides the default value of the current view controller. The overridden value persists until you assign a new content view controller to the receiver. Thus, if you want to keep your overridden value, you must reassign it after changing the content view controller.

When changing the value of this property, the width value you specify must be at least 320 points and no more than 600 points. There are no restrictions on the height value. However, both the width and height values you specify may be adjusted to ensure the popup fits on screen and is not covered by the keyboard. If you change the value of this property while the popover is visible, the size change is animated.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIPopoverController.h

popoverLayoutMargins

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

@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 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.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIPopoverController.h

popoverVisible

A Boolean value indicating whether the popover is currently visible. (read-only)

@property (nonatomic, readonly, getter=isPopoverVisible) BOOL popoverVisible
Discussion

You must present the popover to make it visible.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

Instance Methods

dismissPopoverAnimated:

Dismisses the popover programmatically.

- (void)dismissPopoverAnimated:(BOOL)animated
Parameters
animated

Specify YES to animate the dismissal of the popover or NO to dismiss it immediately.

Discussion

You can use this method to dismiss the popover programmatically in response to taps inside the popover window. Taps outside of the popover’s contents automatically dismiss the popover.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

initWithContentViewController:

Returns an initialized popover controller object.

- (id)initWithContentViewController:(UIViewController *)viewController
Parameters
viewController

The view controller for managing the popover’s content. This parameter must not be nil.

Return Value

An initialized popover controller object.

Discussion

When initializing a popover controller, you must specify the view controller object whose content is to be displayed in the popover. You can change this view controller later by modifying the contentViewController property.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

presentPopoverFromBarButtonItem:permittedArrowDirections:animated:

Displays the popover and anchors it to the specified bar button item.

- (void)presentPopoverFromBarButtonItem:(UIBarButtonItem *)item permittedArrowDirections:(UIPopoverArrowDirection)arrowDirections animated:(BOOL)animated
Parameters
item

The bar button item on which to anchor the popover.

arrowDirections

The arrow directions the popover is permitted to use. You can use this value to force the popover to be positioned on a specific side of the bar button item. However, it is generally better to specify UIPopoverArrowDirectionAny and let the popover decide the best placement. You must not specify UIPopoverArrowDirectionUnknown for this parameter.

animated

Specify YES to animate the presentation of the popover or NO to display it immediately.

Discussion

When presenting the popover, this method adds the toolbar that owns the button to the popover’s list of passthrough views. Thus, taps in the toolbar result in the action methods of the corresponding toolbar items being called. If you want the popover to be dismissed when a different toolbar item is tapped, you must implement that behavior in your action handler methods.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIPopoverController.h

presentPopoverFromRect:inView:permittedArrowDirections:animated:

Displays the popover and anchors it to the specified location in the view.

- (void)presentPopoverFromRect:(CGRect)rect inView:(UIView *)view permittedArrowDirections:(UIPopoverArrowDirection)arrowDirections animated:(BOOL)animated
Parameters
rect

The rectangle in view at which to anchor the popover window.

view

The view containing the anchor rectangle for the popover.

arrowDirections

The arrow directions the popover is permitted to use. You can use this value to force the popover to be positioned on a specific side of the rectangle. However, it is generally better to specify UIPopoverArrowDirectionAny and let the popover decide the best placement. You must not specify UIPopoverArrowDirectionUnknown for this parameter.

animated

Specify YES to animate the presentation of the popover or NO to display it immediately.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

setContentViewController:animated:

Sets the view controller responsible for the content portion of the popover.

- (void)setContentViewController:(UIViewController *)viewController animated:(BOOL)animated
Parameters
viewController

The new view controller whose content should be displayed by the popover.

animated

Specify YES if the change of view controllers should be animated or NO if the change should occur immediately.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

setPopoverContentSize:animated:

Changes the size of the popover’s content view.

- (void)setPopoverContentSize:(CGSize)size animated:(BOOL)animated
Parameters
size

The new size to apply to the content view.

animated

Specify YES if you want the change in size to be animated or NO if you want the change to appear immediately.

Discussion

When changing the size of the popover’s content, the width value you specify must be at least 320 points and no more than 600 points. There are no restrictions on the height value. However, both the width and height values you specify may be adjusted to ensure the popup fits on screen and is not covered by the keyboard.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIPopoverController.h

Constants

UIPopoverArrowDirection

Constants for specifying the direction of the popover arrow.

enum {
   UIPopoverArrowDirectionUp = 1UL << 0,
   UIPopoverArrowDirectionDown = 1UL << 1,
   UIPopoverArrowDirectionLeft = 1UL << 2,
   UIPopoverArrowDirectionRight = 1UL << 3,
   UIPopoverArrowDirectionAny = UIPopoverArrowDirectionUp | UIPopoverArrowDirectionDown |
   UIPopoverArrowDirectionLeft | UIPopoverArrowDirectionRight,
   UIPopoverArrowDirectionUnknown = NSUIntegerMax
};
typedef NSUInteger UIPopoverArrowDirection;
Constants
UIPopoverArrowDirectionUp

An arrow that points upward.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.

UIPopoverArrowDirectionDown

An arrow that points downward.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.

UIPopoverArrowDirectionLeft

An arrow that points toward the left.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.

UIPopoverArrowDirectionRight

An arrow that points toward the right.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.

UIPopoverArrowDirectionAny

An arrow that points in any direction.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.

UIPopoverArrowDirectionUnknown

The status of the arrow is currently unknown.

Available in iOS 3.2 and later.

Declared in UIPopoverController.h.