An object that defines the properties associated with a hardware-based display.


class UIScreen : NSObject


iOS devices have a main screen and zero or more attached screens. A tvOS device has a main screen for the television connected to the device. Use this class to obtain screen objects for each display attached to the device. Each screen object defines the bounds rectangle for the associated display and other interesting properties such as its brightness.In iOS 8 and later, a screen’s bounds property takes the interface orientation of the screen into account. This behavior means that the bounds for a device in a portrait orientation may not be the same as the bounds for the device in a landscape orientation. Apps that rely on the screen dimensions can use the object in the fixedCoordinateSpace property as a fixed point of reference for any calculations they must make. (Prior to iOS 8, a screen’s bounds rectangle always reflected the screen dimensions relative to a portrait-up orientation. Rotating the device to a landscape or upside-down orientation did not change the bounds.)

Handling Screen Connection and Disconnection Notifications

When the user connects or disconnects a display to an iOS device, the system sends appropriate notifications to your app. Always observe the notifications from a long-lived object of your app, such as your app delegate. Connection and disconnection notifications can come at any time, even when your app is suspended in the background. If your app is suspended when a notification arrives, the notification is queued until your app starts running again in the foreground or background, at which point it is delivered to your observer object.

When you get a notification that a new external display is connected, use the extra screen space whenever you can. To use the space, create a window object, assign the new screen to its screen property, and show the window. Doing so causes the window’s contents to be displayed on the display when your app is in the foreground. If you do not create a window for the extra screen, or if you create a window but do not show it, a black field is displayed on the external display.

UIScreen shows two sampler handler methods for the connection and disconnection notifications. The connection handler creates a secondary window, associates it with the newly connected screen, asks one of the app’s view controllers (represented by the custom viewController property) to add some content to the window, and shows it. The disconnection handler releases the window and notifies the main view controller so that it can adjust its presentation accordingly.

Listing 1

Handling connect and disconnect notifications

- (void)handleScreenConnectNotification:(NSNotification*)aNotification {
    UIScreen*    newScreen = [aNotification object];
    CGRect        screenBounds = newScreen.bounds;
    if (!_secondWindow) {
        _secondWindow = [[UIWindow alloc] initWithFrame:screenBounds];
        _secondWindow.screen = newScreen;
        // Set the initial UI for the window and show it.
        [self.viewController displaySelectionInSecondaryWindow:_secondWindow];
        [_secondWindow makeKeyAndVisible];
- (void)handleScreenDisconnectNotification:(NSNotification*)aNotification {
    if (_secondWindow) {
        // Hide and then delete the window.
        _secondWindow.hidden = YES;
        [_secondWindow release];
        _secondWindow = nil;
        // Update the main screen based on what is showing here.
        [self.viewController displaySelectionOnMainScreen];

Configuring the Screen Mode of an External Display

Many screens support multiple resolutions, some of which use different pixel aspect ratios. Screen objects use the most common screen mode by default, but you can change that mode to one that is more suitable for your content. For example, if you are implementing a game using OpenGL ES and your textures are designed for a 640 x 480 pixel screen, you might change the screen mode for screens with higher default resolutions.

If you plan to use a screen mode other than the default one, apply that mode to the UIScreen object before associating the screen with a window. The UIScreenMode class defines the attributes of a single screen mode. You can get a list of the modes supported by a screen from its availableModes property and iterate through the list for one that matches your needs.

For more information about screen modes, see UIScreenMode.


Getting the Available Screens

class var main: UIScreen

Returns the screen object representing the device’s screen.

class var screens: [UIScreen]

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

var mirrored: UIScreen?

The screen being mirrored by an external display.

Getting the Screen Coordinate Spaces

var coordinateSpace: UICoordinateSpace

The current coordinate space of the screen.

var fixedCoordinateSpace: UICoordinateSpace

The fixed coordinate space of the screen.

Getting the Bounds Information

var bounds: CGRect

The bounding rectangle of the screen, measured in points.

var applicationFrame: CGRect

The frame rectangle for the app window, measured in points.

var nativeBounds: CGRect

The bounding rectangle of the physical screen, measured in pixels.

var nativeScale: CGFloat

The native scale factor for the physical screen.

var scale: CGFloat

The natural scale factor associated with the screen.

Accessing the Screen Modes

var currentMode: UIScreenMode?

The current screen mode associated with the screen.

var preferredMode: UIScreenMode?

The preferred display mode for the screen.

var availableModes: [UIScreenMode]

The display modes that can be associated with the screen.

Getting a Display Link

func displayLink(withTarget: Any, selector: Selector) -> CADisplayLink?

Returns a display link object for the current screen.

var maximumFramesPerSecond: Int

The maximum number of frames per second of which the screen is capable.

Setting a Display’s Brightness

var brightness: CGFloat

The brightness level of the screen.

var wantsSoftwareDimming: Bool

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

Setting a Display’s Overscan Compensation

var overscanCompensationInsets: UIEdgeInsets

The edge inset values needed to avoid clipping the rectangle.

var overscanCompensation: UIScreen.OverscanCompensation

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

enum UIScreen.OverscanCompensation

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

Capturing a Screen Snapshot

func snapshotView(afterScreenUpdates: Bool) -> UIView

Returns a snapshot view based on the current screen contents.

Detecting Screen Recordings

var isCaptured: Bool

A Boolean value that indicates whether the system is actively cloning the screen to another destination.

Handling Focus Change on the Screen

var focusedItem: UIFocusItem?

The item that is currently focused.

var focusedView: UIView?

The view that is currently focused.

var supportsFocus: Bool

A Boolean value that indicates whether the screen supports focus-based inputs.

Getting the Screen's Latency

var calibratedLatency: CFTimeInterval

The user-calibrated latency for the current screen.


class let didConnectNotification: NSNotification.Name

This notification is posted when a new screen is connected to the device.

class let didDisconnectNotification: NSNotification.Name

This notification is posted when a screen is disconnected from the device.

class let modeDidChangeNotification: NSNotification.Name

This notification is posted when the current mode of a screen changes.

class let brightnessDidChangeNotification: NSNotification.Name

This notification is posted when the brightness of a screen changes.

class let capturedDidChangeNotification: NSNotification.Name

A notification sent when the captured status of the screen changes.


Inherits From

See Also


Displaying Content on a Connected Screen

Fill connected displays with additional content from your app.

class UIScreenMode

A possible set of attributes that can be applied to a screen object.