Class

UIScreen

A UIScreen object defines the properties associated with a hardware-based display. 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.

Overview

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

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.

Symbols

Getting the Available Screens

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.

Deprecated
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)

Returns a display link object for the current screen.

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 overscanCompensation: UIScreenOverscanCompensation

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

var overscanCompensationInsets: UIEdgeInsets

The edge inset values needed to avoid clipping the rectangle.

Capturing a Screen Snapshot

func snapshotView(afterScreenUpdates: Bool)

Returns a snapshot view based on the current screen contents.

Handling Focus Change on the Screen

var focusedView: UIView?

The view that is currently focused.

var supportsFocus: Bool

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

Constants

UIScreenOverscanCompensation

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

Notifications

static let UIScreenDidConnect: NSNotification.Name

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.

static let UIScreenDidDisconnect: NSNotification.Name

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.

static let UIScreenModeDidChange: NSNotification.Name

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.

static let UIScreenBrightnessDidChange: NSNotification.Name

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.

Relationships

Inherits From