Mac Developer Library

Developer

AppKit Framework Reference NSScreen Class Reference

Options
Deployment Target:

On This Page
Language:

NSScreen

An NSScreen object describes the attributes of a computer’s monitor, or screen. An application may use an NSScreen object to retrieve information about a screen and use this information to decide what to display upon that screen. For example, an application may use the deepestScreen method to find out which of the available screens can best represent color and then may choose to display all of its windows on that screen.

The application object should be created before you use the methods in this class, so that the application object can make the necessary connection to the window system. You can make sure the application object exists by invoking the sharedApplication method of NSApplication. If you created your application with Xcode, the application object is automatically created for you during initialization.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns the NSScreen object containing the window with the keyboard focus.

    Declaration

    Swift

    class func mainScreen() -> NSScreen?

    Objective-C

    + (NSScreen *)mainScreen

    Return Value

    The main screen object.

    Discussion

    The main screen is not necessarily the same screen that contains the menu bar or has its origin at (0, 0). The main screen refers to the screen containing the window that is currently receiving keyboard events. It is the main screen because it is the one with which the user is most likely interacting.

    The screen containing the menu bar is always the first object (index 0) in the array returned by the screens method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    + screens

  • Returns an NSScreen object representing the screen that can best represent color.

    Declaration

    Swift

    class func deepestScreen() -> NSScreen?

    Objective-C

    + (NSScreen *)deepestScreen

    Return Value

    The screen with the highest bit depth.

    Discussion

    This method always returns an object, even if there is only one screen and it is not a color screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an array of NSScreen objects representing all of the screens available on the system.

    Declaration

    Swift

    class func screens() -> [AnyObject]?

    Objective-C

    + (NSArray *)screens

    Return Value

    An array of the NSScreen objects available on the current system or nil if the screen information could not be obtained from the window system.

    Discussion

    The screen at index 0 in the returned array corresponds to the primary screen of the user’s system. This is the screen that contains the menu bar and whose origin is at the point (0, 0). In the case of mirroring, the first screen is the largest drawable display; if all screens are the same size, it is the screen with the highest pixel depth. This primary screen may not be the same as the one returned by the mainScreen method, which returns the screen with the active window.

    The array should not be cached. Screens can be added, removed, or dynamically reconfigured at any time. When the display configuration is changed, the default notification center sends a NSApplicationDidChangeScreenParametersNotification notification.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s current bit depth and colorspace information.

    Declaration

    Swift

    var depth: NSWindowDepth { get }

    Objective-C

    @property(readonly) NSWindowDepth depth

    Return Value

    The window depth information. This value cannot be used directly. You must pass it to a function such as NSBitsPerPixelFromDepth or NSColorSpaceFromDepth to obtain a concrete value for the desired information.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the dimensions and location of the receiver.

    Declaration

    Swift

    var frame: NSRect { get }

    Objective-C

    @property(readonly) NSRect frame

    Return Value

    The full screen rectangle at the current resolution. This rectangle includes any space currently occupied by the menu bar and dock.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a zero-terminated array of the window depths supported by the receiver.

    Declaration

    Swift

    var supportedWindowDepths: UnsafePointer<NSWindowDepth> { get }

    Objective-C

    @property(readonly) const NSWindowDepth *supportedWindowDepths

    Return Value

    A C-style array of window depths. The returned values cannot be used directly. You must pass each one to a function such as NSBitsPerPixelFromDepth or NSColorSpaceFromDepth to obtain a concrete value for the desired screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the device dictionary for the screen.

    Declaration

    Swift

    var deviceDescription: [NSObject : AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSDictionary *deviceDescription

    Return Value

    A dictionary containing the attributes of the receiver's screen. For the list of keys you can use to retrieve values from the returned dictionary, see Display Device—Descriptions.

    Discussion

    In addition to the display device constants described in NSWindow Class Reference, you can also retrieve the CGDirectDisplayID value associated with the screen from this dictionary. To access this value, specify the Objective-C string @"NSScreenNumber" as the key when requesting the item from the dictionary. The value associated with this key is an NSNumber object containing the display ID value. This string is only valid when used as a key for the dictionary returned by this method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the scaling factor from user space to device space on the screen represented by the receiver.

    Declaration

    Objective-C

    - (CGFloat)userSpaceScaleFactor

    Return Value

    The scaling factor, measured in pixels per point, where a point is always equal to 1/72 of an inch. For example, a scaling factor of 2.0 indicates the display has a resolution 2 pixels per point or 144 pixels-per-inch.

    Import Statement

    Objective-C

    @import AppKit;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.7.

  • Returns the current location and dimensions of the visible screen.

    Declaration

    Swift

    var visibleFrame: NSRect { get }

    Objective-C

    @property(readonly) NSRect visibleFrame

    Return Value

    The rectangle defining the portion of the screen in which it is currently safe to draw your application content.

    Discussion

    The returned rectangle is always based on the current user-interface settings and does not include the area currently occupied by the dock and menu bar. Because it is based on the current user -interface settings, the returned rectangle can change between calls and should not be cached.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – frame

  • Returns the colorSpace of the screen

    Declaration

    Swift

    var colorSpace: NSColorSpace? { get }

    Objective-C

    @property(readonly, strong) NSColorSpace *colorSpace

    Return Value

    The colorSpace of the screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns a Boolean value that indicates whether each screen can have its own set of spaces.

    Declaration

    Swift

    class func screensHaveSeparateSpaces() -> Bool

    Objective-C

    + (BOOL)screensHaveSeparateSpaces

    Discussion

    This method reflects whether the “Displays have separate Spaces” option is enabled in Mission Control system preference. You might use the return value to determine how to present your app when in fullscreen mode.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.9 and later.

  • Converts a rectangle in global screen coordinates to a pixel aligned rectangle.

    Declaration

    Swift

    func backingAlignedRect(_ aRect: NSRect, options options: NSAlignmentOptions) -> NSRect

    Objective-C

    - (NSRect)backingAlignedRect:(NSRect)aRect options:(NSAlignmentOptions)options

    Parameters

    aRect

    The input rectangle in global screen coordinates.

    options

    Specifies the alignment options. See NSAlignmentOptions for possible values.

    Return Value

    Returns a a pixel aligned rectangle on the target screen from the given input rectangle in global screen coordinates.

    Discussion

    This method uses NSIntegralRectWithOptions() to produce the pixel aligned rectangle.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Returns the backing store pixel scale factor for the screen.

    Declaration

    Swift

    var backingScaleFactor: CGFloat { get }

    Objective-C

    @property(readonly) CGFloat backingScaleFactor

    Return Value

    Returns the scale factor representing the number of backing store pixels corresponding to each linear unit in screen space on this NSScreen.

    Discussion

    This method is provided for rare cases when the explicit scale factor is needed. Please use the NSView class’s convert backing methods whenever possible.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts the rectangle from the device pixel aligned coordinates system of a screen.

    Declaration

    Swift

    func convertRectFromBacking(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectFromBacking:(NSRect)aRect

    Parameters

    aRect

    The rectangle.

    Return Value

    The rectangle converted from the device pixel aligned coordinates system of the screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Converts the rectangle to the device pixel aligned coordinates system of a screen.

    Declaration

    Swift

    func convertRectToBacking(_ aRect: NSRect) -> NSRect

    Objective-C

    - (NSRect)convertRectToBacking:(NSRect)aRect

    Parameters

    aRect

    The rectangle.

    Return Value

    The rectangle converted to the device pixel aligned coordinates system of the screen.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.