Mac Developer Library

Developer

AppKit Framework Reference NSPanel Class Reference

Options
Deployment Target:

On This Page
Language:

NSPanel

The NSPanel class implements a special kind of window (known as a panel), typically performing an auxiliary function.

For details about how panels work (especially to find out how their behavior differs from window behavior), see How Panels Work.

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • isFloatingPanel - isFloatingPanel Available in OS X v10.0 through OS X v10.9

    Indicates whether the receiver is a floating panel.

    Declaration

    Objective-C

    - (BOOL)isFloatingPanel

    Return Value

    YEStrue when the receiver is a floating panel, NOfalse otherwise.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.0 through OS X v10.9.

    See Also

    – setFloatingPanel:
    level (NSWindow)

  • Controls whether the receiver floats above normal windows.

    Declaration

    Swift

    var floatingPanel: Bool

    Objective-C

    @property(getter=isFloatingPanel) BOOL floatingPanel

    Parameters

    floatingPanel

    YEStrue to make the receiver a floating panel (NSFloatingWindowLevel). NOfalse to make the receiver behave like a normal window (NSNormalWindowLevel).

    Discussion

    By default, panels do not float above other windows. It’s appropriate for an panel to float above other windows only if all of the following conditions are true:

    • It’s small enough not to obscure whatever is behind it.

    • It’s oriented more to the mouse than to the keyboard—that is, if it doesn’t become the key window or becomes so only when needed.

    • It needs to remain visible while the user works in the application’s normal windows—for example, if the user must frequently move the cursor back and forth between a normal window and the panel (such as a tool palette), or if the panel gives information relevant to the user’s actions in a normal window.

    • It hides when the application is deactivated (the default behavior for panels).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isFloatingPanel
    setLevel: (NSWindow)

  • Indicates whether the receiver becomes the key window only when needed.

    Declaration

    Swift

    var becomesKeyOnlyIfNeeded: Bool

    Objective-C

    @property BOOL becomesKeyOnlyIfNeeded

    Return Value

    YEStrue when the panel becomes the key window only when needed, NOfalse otherwise.

    Discussion

    By default, this attribute is set to NOfalse, indicating that the panel becomes key as other windows do.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Specifies whether the receiver becomes the key window only when needed.

    Declaration

    Swift

    var becomesKeyOnlyIfNeeded: Bool

    Objective-C

    @property BOOL becomesKeyOnlyIfNeeded

    Parameters

    becomesKeyOnlyIfNeeded

    YEStrue makes the panel become the key window only when keyboard input is required. NOfalse makes the panel become key when it’s clicked.

    Discussion

    This behavior is not set by default. You should consider setting it only if most user interface elements in the panel aren’t text fields, and if the choices that can be made by entering text can also be made in another way (such as by clicking an item in a list).

    If the receiver is a non-activating panel, then it becomes key only if the hit view returns YEStrue from needsPanelToBecomeKey. This way, a non-activating panel can control whether it takes keyboard focus.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Indicates whether the receiver receives keyboard and mouse events even when some other window is being run modally.

    Declaration

    Swift

    var worksWhenModal: Bool

    Objective-C

    @property BOOL worksWhenModal

    Return Value

    YEStrue when the receiver receives keyboard and mouse events even when some other window is being run modally, NOfalse otherwise.

    Discussion

    By default, this attribute is set to NOfalse, indicating a panel’s ineligibility for events during a modal loop or session. See How Modal Windows Work for more information on modal windows and panels.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – setWorksWhenModal:
    runModalForWindow: (NSApplication)
    runModalSession: (NSApplication)

  • Specifies whether the receiver receives keyboard and mouse events even when some other window is being run modally.

    Declaration

    Swift

    var worksWhenModal: Bool

    Objective-C

    @property BOOL worksWhenModal

    Parameters

    worksWhenModal

    YEStrue to make the panel receive events even during a modal loop or session. NOfalse to prevent the panel from receiving events while a modal loop or session is running.

    Discussion

    See How Modal Windows Work for more information on modal windows and panels.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – worksWhenModal
    runModalForWindow: (NSApplication)
    runModalSession: (NSApplication)

  • These constants define values returned by the NSRunAlertPanel function and by the NSApplication method runModalSession: when the modal session is run with an NSPanel provided by the NSGetAlertPanel function.

    NSRunAlertPanel and NSGetAlertPanel are deprecated; use NSAlert APIs instead.

    Declaration

    Swift

    var NSAlertDefaultReturn: Int { get } var NSAlertAlternateReturn: Int { get } var NSAlertOtherReturn: Int { get } var NSAlertErrorReturn: Int { get }

    Objective-C

    enum { NSAlertDefaultReturn = 1, NSAlertAlternateReturn = 0, NSAlertOtherReturn = -1, NSAlertErrorReturn = -2 };

    Constants

    • NSAlertDefaultReturn

      NSAlertDefaultReturn

      The user pressed the default button.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

    • NSAlertAlternateReturn

      NSAlertAlternateReturn

      The user pressed the alternate button.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

    • NSAlertOtherReturn

      NSAlertOtherReturn

      The user pressed a second alternate button.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

    • NSAlertErrorReturn

      NSAlertErrorReturn

      The alert cannot identify the reason it was closed; it may have been closed by an external source or by a button other than those listed above.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

  • These constants define the possible return values for such methods as the runModal... methods of the NSOpenPanel class, which tell which button (OK or Cancel) the user has clicked on an open panel.

    In an NSWindow object, use the NSModalResponse constants instead.

    Declaration

    Swift

    var NSCancelButton: Int { get } var NSOKButton: Int { get }

    Objective-C

    enum { NSOKButton = 1, NSCancelButton = 0 };

    Constants

    • NSCancelButton

      NSCancelButton

      The Cancel button

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

    • NSOKButton

      NSOKButton

      The OK button

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.10.

  • The NSPanel class defines the following constants for panel styles:

    Declaration

    Swift

    var NSDocModalWindowMask: Int { get } var NSUtilityWindowMask: Int { get } var NSNonactivatingPanelMask: Int { get } var NSHUDWindowMask: Int { get }

    Objective-C

    enum { NSUtilityWindowMask = 1 << 4, NSDocModalWindowMask = 1 << 6, NSNonactivatingPanelMask = 1 << 7 NSHUDWindowMask = 1 << 13 };

    Constants

    • NSDocModalWindowMask

      NSDocModalWindowMask

      The panel is created as a modal sheet.

      Available in OS X v10.0 and later.

    • NSUtilityWindowMask

      NSUtilityWindowMask

      The panel is created as a floating window.

      Available in OS X v10.0 and later.

    • NSNonactivatingPanelMask

      NSNonactivatingPanelMask

      The panel can receive keyboard input without activating the owning application.

      Valid only for an instance of NSPanel or its subclasses; not valid for a window.

      Available in OS X v10.2 and later.

    • NSHUDWindowMask

      NSHUDWindowMask

      The panel is created as a transparent panel (sometimes called a “heads-up display”).

      Valid only for an instance of NSPanel or its subclasses; not valid for a window.

      Using the C bitwise OR operator, NSHUDWindowMask can be combined with other style masks (some of which are documented in Window Style Masks) with the following results:

      NSBorderlessWindowMask

      Borderless window with transparent panel transparency and window level.

      A panel that uses NSBorderlessWindowMask can’t become key unless you implement canBecomeKeyWindow to return YEStrue. Note that you can also set a panel’s style mask to NSBorderlessWindowMask in Interface Builder by deselecting Title Bar in the Appearance section of the Attributes inspector.

      NSTitledWindowMask

      Titled window with transparent panel transparency and window level. This combination can be additionally combined with any of the following:

      NSClosableWindowMask

      Titled window with transparent panel close box, transparency, and window level.

      NSResizableWindowMask

      Titled window with transparent panel resize corner, transparency, and window level.

      NSNonactivatingPanelMask

      No effect on appearance, but owning application is not necessarily active when this window is the key window.

      The following constants cannot be combined with NSHUDWindowMask: NSMiniaturizableWindowMask, NSTexturedBackgroundWindowMask, NSDocModalWindowMask, and NSUnifiedTitleAndToolbarWindowMask.

      Available in OS X v10.6 and later.