Class

UIScreen

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

Declaration

@interface UIScreen : NSObject

Overview

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

Topics

Getting the Available Screens

mainScreen

Returns the screen object representing the device’s screen.

screens

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

mirroredScreen

The screen being mirrored by an external display.

Getting the Screen Coordinate Spaces

coordinateSpace

The current coordinate space of the screen.

fixedCoordinateSpace

The fixed coordinate space of the screen.

Getting the Bounds Information

bounds

The bounding rectangle of the screen, measured in points.

applicationFrame

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

Deprecated
nativeBounds

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

nativeScale

The native scale factor for the physical screen.

scale

The natural scale factor associated with the screen.

Accessing the Screen Modes

currentMode

The current screen mode associated with the screen.

preferredMode

The preferred display mode for the screen.

availableModes

The display modes that can be associated with the screen.

Getting a Display Link

- displayLinkWithTarget:selector:

Returns a display link object for the current screen.

maximumFramesPerSecond

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

Setting a Display’s Brightness

brightness

The brightness level of the screen.

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.

Setting a Display’s Overscan Compensation

overscanCompensationInsets

The edge inset values needed to avoid clipping the rectangle.

overscanCompensation

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

UIScreenOverscanCompensation

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

Capturing a Screen Snapshot

- snapshotViewAfterScreenUpdates:

Returns a snapshot view based on the current screen contents.

Detecting Screen Recordings

captured

A Boolean value that indicates whether the contents of the screen are being cloned to another destination.

Handling Focus Change on the Screen

focusedItem

The item that is currently focused.

focusedView

The view that is currently focused.

supportsFocus

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

Getting the Screen's Latency

calibratedLatency

The user-calibrated latency for the current screen.

Notifications

UIScreenDidConnectNotification

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

UIScreenDidDisconnectNotification

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

UIScreenModeDidChangeNotification

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

UIScreenBrightnessDidChangeNotification

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

UIScreenCapturedDidChangeNotification

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

Relationships

Inherits From

See Also

Screens

Displaying Content on a Connected Screen

Fill connected displays with additional content from your app.

UIScreenMode

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