Mac Developer Library

Developer

AppKit Framework Reference NSPopover Class Reference

Options
Deployment Target:

On This Page
Language:

NSPopover

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.7 and later.

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.

  • The view controller that manages the content of the popover.

    Declaration

    Swift

    @IBOutlet var contentViewController: NSViewController?

    Objective-C

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

    The default value is nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • behavior behavior Property

    Specifies the behavior of the popover.

    Declaration

    Swift

    var behavior: NSPopoverBehavior

    Objective-C

    @property NSPopoverBehavior behavior

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Shows the popover anchored to the specified view.

    Declaration

    Swift

    func showRelativeToRect(_ positioningRect: NSRect, ofView positioningView: NSView, preferredEdge preferredEdge: NSRectEdge)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The content size of the popover.

    Declaration

    Swift

    var positioningRect: NSRect

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Specifies the appearance of the popover.

    Declaration

    Swift

    var appearance: NSAppearance?

    Objective-C

    @property(strong) NSAppearance *appearance

    Discussion

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • animates animates Property

    Specifies if the popover is to be animated.

    Declaration

    Swift

    var animates: Bool

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The content size of the popover.

    Declaration

    Swift

    var contentSize: NSSize

    Objective-C

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

    This property is exposed as a read-only binding.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • shown shown Property

    The display state of the popover.

    Declaration

    Swift

    var shown: Bool { get }

    Objective-C

    @property(readonly, getter=isShown) BOOL shown

    Discussion

    The value is YEStrue if the popover is being shown, NOfalse 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:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Attempts to close the popover.

    Declaration

    Swift

    @IBAction func performClose(_ sender: AnyObject?)

    Objective-C

    - (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 NOfalse, or if a subclass of the NSPopover class implements popoverShouldClose: and returns NOfalse).

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    – close

  • Forces the popover to close without consulting its delegate.

    Declaration

    Swift

    func close()

    Objective-C

    - (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 NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • delegate delegate Property

    The delegate of the popover.

    Declaration

    Swift

    @IBOutlet unowned(unsafe) var delegate: NSPopoverDelegate?

    Objective-C

    @property(assign) IBOutlet id<NSPopoverDelegate> delegate

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

Data Types

  • The set of predefined appearances for a popover.

    Declaration

    Swift

    enum NSPopoverAppearance : Int { case Minimal case HUD }

    Objective-C

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

    Constants

    • Minimal

      NSPopoverAppearanceMinimal

      The popover draws with a minimal appearance.

      Available in OS X v10.7 and later.

      Deprecated in OS X v10.10.

    • HUD

      NSPopoverAppearanceHUD

      The popover draws with a HUD appearance.

      Available in OS X v10.7 and later.

      Deprecated in OS X v10.10.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • The appearance and disappearance behavior of a popover.

    Declaration

    Swift

    enum NSPopoverBehavior : Int { case ApplicationDefined case Transient case Semitransient }

    Objective-C

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

    Constants

    • ApplicationDefined

      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.

    • Transient

      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.

    • Semitransient

      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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    let NSPopoverCloseReasonKey: String let NSPopoverCloseReasonStandard: String let NSPopoverCloseReasonDetachToWindow: String

    Objective-C

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

    Constants

    • NSPopoverCloseReasonKey

      NSPopoverCloseReasonKey

      The userInfo key containing the reason for the NSPopoverWillCloseNotification.

      Available in OS X v10.7 and later.

    • NSPopoverCloseReasonStandard

      NSPopoverCloseReasonStandard

      Specifies that the popover has been closed in a standard way.

      Available in OS X v10.7 and later.

    • NSPopoverCloseReasonDetachToWindow

      NSPopoverCloseReasonDetachToWindow

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

      Available in OS X v10.7 and later.