UIPopoverController Class Reference

Inherits from	NSObject
Conforms to	UIAppearanceContainer NSObject (NSObject)
Framework	/System/Library/Frameworks/UIKit.framework
Availability	Available in iOS 3.2 and later.
Companion guide	View Controller Catalog for iOS
Declared in	UIPopoverController.h
Related sample code	CoreTextPageViewer ExternalDisplay Popovers PrintPhoto ToolbarSearch

Overview

The UIPopoverController class is used to manage the presentation of content in a popover. You use popovers to present information temporarily but in a way that does not take over the entire screen like a modal view does. The popover content is layered on top of your existing content in a special type of window. 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 provide 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 may have to present it again or hide it altogether in some cases. For example, when displayed from a bar button item, the popover controller automatically adjusts the position (and potentially the size) of the popover to account for changes to the position of the bar button item. However, if you remove the bar button item during the rotation, or if you presented the popover from a target rectangle in a view, the popover controller does not attempt to reposition the popover. In those cases, you must manually hide the popover or present it again from an appropriate new position. You can do this in the didRotateFromInterfaceOrientation: method of the view controller that you used to present the popover.

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

Configuring the Popover Attributes

Getting the Popover Attributes

Presenting and Dismissing the Popover

Customizing the Popover Appearance

Properties

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.

Related Sample Code

ToolbarSearch

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.

Related Sample Code

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.

Related Sample Code

ToolbarSearch

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.

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.

Related Sample Code

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.

Related Sample Code

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;