UIPopoverBackgroundView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 5.0 and later.
Companion guide
Declared in
UIPopoverBackgroundView.h

Overview

The UIPopoverBackgroundView class provides the background appearance for a popover. This class is abstract and must be subclassed before it can be used. The implementation of your subclass is responsible for providing the border decoration and arrow for the popover. Subclasses must also override all declared properties and methods to provide information about where to lay out the corresponding popover content and arrow.

Subclassing Notes

Your subclass implementation is responsible for providing the background contents for the popover, which includes the arrow and appropriately styled border. The popover controller places the actual popover content on top of your background view to finish the popover’s presentation.

The background contents of your view should be based on stretchable images. Because the popover is animated into place (and may require animated transitions), using images is the only way to ensure that the animations are smooth and not jittery. By creating images that can be stretched at appropriate places, your popover can still be resized and adjusted as needed. You can then incorporate those images using UIImageView subviews or Core Animation layers. When the size of the popover changes (perhaps to accommodate the keyboard), all you have to do is adjust the frame rectangles of your embedded image views.

In addition to providing the background content, your subclass must implement all of the UIPopoverBackgroundView class methods and properties. The popover controller uses these methods and properties to get and set information related to your background view. The class methods are called once and the values you return should never change. However, the values in the arrowOffset and arrowDirection properties can change while your popover is on the screen, so your setter methods should call setNeedsLayout when that happens to update the background image views or layers.

To create a stretchable image, use the resizableImageWithCapInsets: method of UIImage.

Tasks

Returning the Content View Insets

Accessing the Arrow Metrics

Controlling the Popover Appearance

Properties

arrowDirection

The direction in which the popover arrow is pointing.

@property (nonatomic, readwrite) UIPopoverArrowDirection arrowDirection
Discussion

The default implementation of this method raises an exception. You must override it to store the current arrow direction. Your methods must not call super.

You should use this value during layout to configure the images to use for your view’s content. In your setter method, you should update to your view’s content and potentially update the layout as well.

Use this value to determine which stretchable images to use for your view. Normally, you would have different sets of images depending on whether the arrow was pointing up, down, left, or right. (You could also use the same image for up and down, or left and right, and use a transform to flip the images so that they point in the appropriate direction.) The popover controller sets this value prior to displaying the popover initially, and it may change the value after your popover is displayed on screen.

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

arrowOffset

The distance (measured in points) from the center of the view to the center line of the arrow.

@property (nonatomic, readwrite) CGFloat arrowOffset
Discussion

The default methods associated with this property raise exceptions. You must implement the appropriate setter and getter methods yourself. Your methods must not call super.

You should use this value during layout to position the arrow. In your setter method, you should similarly initiate an update to your view’s layout so that you can reposition your stretchable images accordingly.

Offsets are always specified relative to the center of your view object. Adding the offset value to the center value of the given axis yields the required location for the arrow. Thus, for an arrow pointing up or down, a negative offset moves the arrow toward the left edge of the view. For an arrow pointing left or right, a negative offset moves the arrow toward the top of the view.

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

Class Methods

arrowBase

The width of the arrow triangle at its base.

+ (CGFloat)arrowBase
Discussion

The default implementation of this method raises an exception. You must override it and return the width of your popover’s arrow at its base. Your method must not call super.

The arrow width must be the same for all possible directions and that width must not change.

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

arrowHeight

The height of the arrow (measured in points) from its base to its tip.

+ (CGFloat)arrowHeight
Discussion

The default implementation of this method raises an exception. You must override it and return the height of the arrow used by your popover background content. Your method must not call super.

The arrow height must be the same for all possible directions and that height must not change.

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

contentViewInsets

The insets for the content portion of the popover.

+ (UIEdgeInsets)contentViewInsets
Discussion

The default implementation of this method raises an exception. You must override it and return an appropriate set of inset values. Your methods must not call super.

Consider your popover background without the arrow, and these insets are the distance from a given edge of your background content to the corresponding edge of the popover’s content view. (This edges of the background content should be flush with the frame rectangle of your view, except on the side containing the arrow, of course.) The popover controller uses these values (in combination with the value returned by the arrowHeight method) to determine where to position the popover content view. Because the arrow height is accounted for separately, your implementation of this method should return a set of constant values.

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

wantsDefaultContentAppearance

Determines whether the default content appearance should be used for the popover.

+ (BOOL)wantsDefaultContentAppearance
Discussion

This method may be overriden to prevent the drawing of the content inset and drop shadow inside the popover. The default implementation of this method returns YES, which means that the content inset and drop shadow will be drawn. Overriding this method simply means implementing it to return NO, which would mean that the content inset and drop shadow will not be drawn.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIPopoverBackgroundView.h