NSPopover Class Reference

Inherits from
NSResponder : NSObject
Conforms to
NSCoding (NSResponder)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.7 and later.
Declared in
NSPopover.h
Related sample code

Overview

The NSPopover class provides a means to display additional content related to existing content on the screen. The popover is positioned relative to the existing content.

An anchor is used to express the relation between these two units of content. A popover has an appearance that specifies its visual characteristics, as well as a behavior that determines which user interactions will cause the popover to close. A transient popover is closed in response to most user interactions, whereas a semi-transient popovers is closed when the user interacts with the window containing the popover's positioning view. Popovers with application-defined behavior are not usually closed on the developer's behalf.

The system automatically positions each popover relative to its positioning view and moves the popover whenever its positioning view moves. A positioning rectangle within the positioning view can be specified for additional granularity.

Popovers can be detached to become a separate window when they are dragged by implementing the appropriate delegate method.

Tasks

Popover’s Content View Control

Popover Position and Size

Popover Appearance

Closing a Popover

Getting and Setting the Delegate

Properties

animates

Specifies if the popover is to be animated.

@property BOOL animates
Discussion

A popover may be animated when it shows, closes, moves, or appears to transition to a detachable window. This property also controls whether the popover animates when the content view or content size changes.

The system does not guarantee which behaviors will be animated or that this property will be respected; it is regarded as a hint.

The default value is YES.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

appearance

Specifies the appearance of the popover.

@property  appearance
Discussion

The default value is NSPopoverAppearanceMinimal which causes the popover to be displayed using the standard system appearance. See NSPopoverAppearance for possible value.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSPopover.h

behavior

Specifies the behavior of the popover.

@property  behavior
Discussion

The default value is NSPopoverBehaviorApplicationDefined. See NSPopoverBehavior for possible value.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSPopover.h

contentSize

The content size of the popover.

@property NSSize contentSize
Discussion

The popover's content size is set to match the size of the content view when the content view controller is set.

Changes to the content size of the popover will cause the popover to animate while it is shown if the animates property is YES.

This property is exposed as a read-only binding.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

contentViewController

The view controller that manages the content of the popover.

@property (retain) IBOutlet NSViewController *contentViewController
Discussion

You must set the content view controller of the popover before the popover is shown. Changes to the popover's content view controller while the popover is shown will cause the popover to animate if the animates property is YES.

The default value is nil.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSPopover.h

delegate

The delegate of the popover.

@property (assign) IBOutlet id <NSPopoverDelegate> delegate
Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSPopover.h

positioningRect

The content size of the popover.

@property NSRect positioningRect
Discussion

Popovers are positioned relative to a positioning view and are automatically moved when the location or size of the positioning view changes.

Sometimes it is desirable to position popovers relative to a rectangle within the positioning view. In this case, you must update the positioningRect property whenever this rectangle changes.

This property is exposed as a read-only binding.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

shown

The display state of the popover.

@property (readonly, getter=isShown) BOOL shown
Discussion

The value is YES if the popover is being shown, NO otherwise.

The popover is considered to be shown from the point when showRelativeToRect:ofView:preferredEdge: is invoked. A popover is considered closed in response to an invocation of either close or performClose:.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

Instance Methods

close

Forces the popover to close without consulting its delegate.

- (void)close
Discussion

Any popovers nested within the popovers will also receive a close message. When a window is closed in response to the close message being sent, all of its popovers are closed. The popover animates out when closed unless the animates property is set to NO.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSPopover.h

performClose:

Attempts to close the popover.

- (IBAction)performClose:(id)sender
Parameters
sender

The sender of the action message.

Discussion

The popover will not be closed if it has a delegate and the delegate implements the returns popoverShouldClose: method returning NO, or if a subclass of the NSPopover class implements popoverShouldClose: and returns NO).

The operation will fail if the popover is displaying a nested popover or if it has a child window. A window will attempt to close its popovers when it receives a performClose: message.

The popover animates out when closed unless the animates property is set to NO.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSPopover.h

showRelativeToRect:ofView:preferredEdge:

Shows the popover anchored to the specified view.

- (void)showRelativeToRect:(NSRect)positioningRect ofView:(NSView *)positioningView preferredEdge:(NSRectEdge)preferredEdge
Parameters
positioningRect

The rectangle within positioningView relative to which the popover should be positioned. Normally set to the bounds of positioningView. May be an empty rectangle, which will default to the bounds of positioningView.

positioningView

The view relative to which the popover should be positioned. Causes the method to raise NSInvalidArgumentException if nil.

preferredEdge

The edge of positioningView the popover should prefer to be anchored to.

Discussion

This method raises NSInternalInconsistencyException if contentViewController or the view controller’s view is nil. If the popover is already being shown, this method updates the anchored view, rectangle, and preferred edge. If the positioning view is not visible, this method does nothing.

Availability
  • Available in OS X v10.7 and later.
Related Sample Code
Declared In
NSPopover.h

Constants

NSPopoverAppearance

The set of predefined appearances for a popover.

enum {
   NSPopoverAppearanceMinimal = 0,
   NSPopoverAppearanceHUD = 1
};
typedef NSInteger NSPopoverAppearance;
Constants
NSPopoverAppearanceMinimal

The popover draws with a minimal appearance.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

NSPopoverAppearanceHUD

The popover draws with a HUD appearance.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

NSPopoverBehavior

The appearance and disappearance behavior of a popover.

enum {
   NSPopoverBehaviorApplicationDefined = 0,
   NSPopoverBehaviorTransient = 1,
   NSPopoverBehaviorSemitransient = 2
};
typedef NSInteger NSPopoverBehavior;
Constants
NSPopoverBehaviorApplicationDefined

Your application assumes responsibility for closing the popover.

The system will still close the popover in a limited number of circumstances. For instance, the system will attempt to close the popover when the window of its positioningView is closed. The exact interactions in which AppKit will close the popover are not guaranteed. You may consider implementing -cancel: to close the popover when the escape key is pressed.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

NSPopoverBehaviorTransient

The system will close the popover when the user interacts with a user interface element outside the popover.

Note that interacting with menus or panels that become key only when needed will not cause a transient popover to close. The exact interactions that will cause transient popovers to close are not specified.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

NSPopoverBehaviorSemitransient

The system will close the popover when the user interacts with user interface elements in the window containing the popover's positioning view.

Semi-transient popovers cannot be shown relative to views in other popovers, nor can they be shown relative to views in child windows. The exact interactions that cause semi-transient popovers to close are not specified.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSPopover.h

Notification User Info Keys

The following constants are used as keys in the userInfo dictionary for notifications pertaining to popovers.

NSString * const NSPopoverCloseReasonKey;
NSString * const NSPopoverCloseReasonStandard;
NSString * const NSPopoverCloseReasonDetachToWindow;
Constants
NSPopoverCloseReasonKey

The userInfo key containing the reason for the NSPopoverWillCloseNotification. It can currently be either NSPopoverCloseReasonStandard or NSPopoverCloseReasonDetachToWindow, although more reasons for closing may be added in the future.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

NSPopoverCloseReasonStandard

Specifies that the popover has been closed because it is being detached to a window.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

NSPopoverCloseReasonDetachToWindow

Specifies that the popover has been closed because it is being detached to a window.

Available in OS X v10.7 and later.

Declared in NSPopover.h.

Notifications

NSPopoverWillShowNotification

Sent before the popover is shown.
Availability
Declared In
NSPopover.h

NSPopoverDidShowNotification

Sent after the popover has finished animating onscreen.
Availability
Declared In
NSPopover.h

NSPopoverWillCloseNotification

Sent before the popover is closed.

The userInfo key NSPopoverCloseReasonKey specifies the reason for closing. It can currently be either NSPopoverCloseReasonStandard or NSPopoverCloseReasonDetachToWindow, although more reasons for closing may be added in the future.

Availability
Declared In
NSPopover.h

NSPopoverDidCloseNotification

Sent after the popover has finished animating offscreen.

The value of the userInfo key NSPopoverCloseReasonKey specifies the reason for closing. It can currently be either NSPopoverCloseReasonStandard or NSPopoverCloseReasonDetachToWindow, although more reasons for closing may be added in the future.

Availability
Declared In
NSPopover.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-07-26)

Did this document help you? Yes It's good, but... Not helpful...