UIScreen Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UIScreen.h
Related sample code

Overview

A UIScreen object contains the bounding rectangle of the device’s entire screen. When setting up your application’s user interface, you should use the properties of this object to get the recommended frame rectangles for your application’s window.

Tasks

Getting the Available Screens

Getting the Bounds Information

Accessing the Screen Modes

Getting a Display Link

Setting a Display’s Brightness

Setting a Display’s Overscan Compensation.

Capturing a Screen Snapshot

Properties

applicationFrame

The frame rectangle for the app window. (read-only)

@property(nonatomic, readonly) CGRect applicationFrame
Discussion

This property contains the bounds used by the app window, which in some versions of iOS may be different than the screen bounds themselves.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIScreen.h

availableModes

The display modes that can be associated with the receiver. (read-only)

@property(nonatomic, readonly, copy) NSArray *availableModes
Discussion

The array contains one or more UIScreenMode objects, each of which represents a display mode supported by the screen.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIScreen.h

bounds

Contains the bounding rectangle of the screen, measured in points. (read-only)

@property(nonatomic, readonly) CGRect bounds
Availability
  • Available in iOS 2.0 and later.
Declared In
UIScreen.h

brightness

The brightness level of the screen.

@property(nonatomic) CGFloat brightness
Discussion

This property is only supported on the main screen. The value of this property should be a number between 0.0 and 1.0, inclusive.

Brightness changes made by an app remain in effect only while the app is active. The system restores the user-supplied brightness setting at appropriate times when your app is not in the foreground. So if you change the value of this property, you do not need to record the previous value and restore it when your app moves to the background.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIScreen.h

currentMode

The current screen mode associated with the receiver.

@property(nonatomic, retain) UIScreenMode *currentMode
Discussion

The default value of this property is the mode containing the highest resolution supported by the screen. You can change the value of this property to support different resolutions as needed. For example, you might want to lower the default resolution to one that your application supports more readily.

Availability
  • Available in iOS 3.2 and later.
Related Sample Code
Declared In
UIScreen.h

mirroredScreen

The screen being mirrored by an external display. (read-only)

@property(nonatomic, readonly, retain) UIScreen *mirroredScreen
Discussion

If mirroring is supported and currently active, this property contains the screen object associated with the device’s main screen. This represents the screen being mirrored by the attached display. The value of this property is nil when mirroring is disabled, not supported, or no screen is connected to the device.

To disable mirroring and use the external display for presenting unique content, create a window and associate it with the corresponding screen object. To re-enable mirroring, remove the window from the corresponding screen object.

Availability
  • Available in iOS 4.3 and later.
See Also
Declared In
UIScreen.h

overscanCompensation

For an external screen, this property sets the desired technique to compensate for overscan.

@property(nonatomic) UIScreenOverscanCompensation overscanCompensation
Discussion

Some external displays may be unable to reliably display all of the pixels to the user. To compensate, choose one of the techniques described in “UIScreenOverscanCompensation”.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIScreen.h

preferredMode

The preferred display mode for the receiver. (read-only)

@property(nonatomic, readonly, retain) UIScreenMode *preferredMode
Availability
  • Available in iOS 4.3 and later.
Declared In
UIScreen.h

scale

The natural scale factor associated with the screen. (read-only)

@property(nonatomic, readonly) CGFloat scale
Discussion

This value reflects the scale factor needed to convert from the default logical coordinate space into the device coordinate space of this screen. The default logical coordinate space is measured using points. For standard-resolution displays, the scale factor is 1.0 and one point equals one pixel. For Retina displays, the scale factor is 2.0 and one point is represented by four pixels.

Availability
  • Available in iOS 4.0 and later.
Declared In
UIScreen.h

wantsSoftwareDimming

A Boolean value that indicates whether the screen may be dimmed lower than the hardware is normally capable of by emulating it in software.

@property(nonatomic) BOOL wantsSoftwareDimming
Discussion

The default value is NO. Enabling it may cause a loss in performance.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIScreen.h

Class Methods

mainScreen

Returns the screen object representing the device’s screen.

+ (UIScreen *)mainScreen
Return Value

The screen object for the device

Availability
  • Available in iOS 2.0 and later.
Declared In
UIScreen.h

screens

Returns an array containing all of the screens attached to the device.

+ (NSArray *)screens
Return Value

An array of UIScreen objects.

Discussion

The returned array includes the main screen plus any additional screens connected to the device. The main screen is always at index 0.

Not all devices support external displays. Currently, external displays are supported by iPhone and iPod touch devices with Retina displays and iPad. Older devices, such as the iPhone 3GS do not support external displays. Connecting to an external display requires an appropriate cable between the device and display.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIScreen.h

Instance Methods

displayLinkWithTarget:selector:

Returns a display link object for the current screen.

- (CADisplayLink *)displayLinkWithTarget:(id)target selector:(SEL)sel
Parameters
target

An object to be notified when the screen should be updated.

sel

The method of target to call. This selector must have the following signature:

- (void)selector:(CADisplayLink *)sender;
Return Value

A newly constructed display link object.

Discussion

You use display link objects to synchronize your drawing code to the screen’s refresh rate. The newly constructed display link retains the target.

Availability
  • Available in iOS 4.0 and later.
Declared In
UIScreen.h

snapshotViewAfterScreenUpdates:

Returns a snapshot view based on the current screen contents.

- (UIView *)snapshotViewAfterScreenUpdates:(BOOL)afterUpdates
Parameters
afterUpdates

A Boolean that indicates whether the snapshot should be taken after recent changes have been incorporated. Specify the value NO if you want to capture the screen in its current state, which might not include recent changes.

Return Value

A new view object containing a snapshot of the screen’s rendered contents.

Discussion

This method captures the current visual contents of the screen from the render server and uses them to build a new snapshot view. You can use the returned snapshot view as a visual stand-in for the screen’s contents in your app. For example, you might use a snapshot view to facilitate a full screen animation. Because the content is captured from the already rendered content, this method reflects the current visual appearance of the screen and is not updated to reflect animations that are scheduled or in progress. However, this method is faster than trying to render the contents of the screen into a bitmap image yourself.

Because the returned snapshot view is still a view object, you may modify it and its layer object as needed. However, you cannot change the contents property of the snapshot view’s layer and attempts to do so will fail silently. If any onscreen views have not yet been committed to the render server, that portion of the snapshot will have no content.

Availability
  • Available in iOS 7.0 and later.
Declared In
UIScreen.h

Constants

UIScreenOverscanCompensation

Describes different techniques for compensating for pixel loss at the edge of the screen.

typedef enum {
   UIScreenOverscanCompensationScale,
   UIScreenOverscanCompensationInsetBounds,
   UIScreenOverscanCompensationInsetApplicationFrame,
} UIScreenOverscanCompensation;
Constants
UIScreenOverscanCompensationScale

The final composited framebuffer for the screen is scaled so that all pixels lie in the area visible on the screen.

Available in iOS 5.0 and later.

Declared in UIScreen.h.

UIScreenOverscanCompensationInsetBounds

The screen bounds are reduced in size so that all pixels in the framebuffer are visible on the screen.

Available in iOS 5.0 and later.

Declared in UIScreen.h.

UIScreenOverscanCompensationInsetApplicationFrame

The application frame is reduced in size to compensate for overscan. Content drawn outside the application frame may be clipped.

Available in iOS 5.0 and later.

Declared in UIScreen.h.

Notifications

UIScreenDidConnectNotification

This notification is posted when a new screen is connected to the device. The object of the notification is the UIScreen object representing the new screen. There is no userInfo dictionary.

Connection notifications are not sent for screens that are already present when the application is launched. The application can instead use the screens method to get the current set of screens at launch time.

Availability
Declared In
UIScreen.h

UIScreenDidDisconnectNotification

This notification is posted when a screen is disconnected from the device. The object of the notification is the UIScreen object that represented the now disconnected screen. There is no userInfo dictionary.
Availability
Declared In
UIScreen.h

UIScreenModeDidChangeNotification

This notification is posted when the current mode of a screen changes. The object of the notification is the UIScreen object whose currentMode property changed. There is no userInfo dictionary.

Clients can use this notification to detect changes in the screen resolution.

Availability
Declared In
UIScreen.h

UIScreenBrightnessDidChangeNotification

This notification is posted when the brightness of a screen changes. The object of the notification is the UIScreen object whose brightness property changed. There is no userInfo dictionary.
Availability
Declared In
UIScreen.h