---

NSScreen Class Reference

Overview

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.

Tasks

Getting NSScreen Objects

• + mainScreen
• + deepestScreen
• + screens

Getting Screen Information

• – depth
• – frame
• – supportedWindowDepths
• – deviceDescription
• – userSpaceScaleFactor
• – visibleFrame

Class Methods

deepestScreen

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

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

mainScreen

Returns an NSScreen object representing the main screen.

+ (NSScreen *)mainScreen

Return Value

The main screen object.

Discussion

The main screen is the screen with the key window. To obtain the screen containing the menu bar use [[NSScreen screens] objectAtIndex:0] (after checking that the screens array is not empty).

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

screens

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

+ (NSArray *)screens

Return Value

An array of the NSScreen objects available on the current system.

Discussion

Raises an NSWindowServerCommunicationException if the screen’s information can’t be obtained from the window system. When the display configuration is changed, the default notification center sends a NSApplicationDidChangeScreenParametersNotification notification.

The first screen in the screens array is always the “zero” screen. To obtain the menu bar screen use [[NSScreen screens] objectAtIndex:0] (after checking that the screens array is not empty).

The array should not be cached. Screens can be added, removed, or dynamically reconfigured at any time.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

Instance Methods

depth

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

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

deviceDescription

Returns the device dictionary for the screen.

- (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 “Constants.”

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

frame

Returns the dimensions and location of the receiver.

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – visibleFrame

Declared In

NSScreen.h

supportedWindowDepths

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

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSScreen.h

userSpaceScaleFactor

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

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSScreen.h

visibleFrame

Returns the current location and dimensions of the visible screen.

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – frame

Declared In

NSScreen.h

Constants

The following constants are used as keys to retrieve attributes from the display device dictionary.

---