iOS Developer Library — Prerelease

Developer

UIKit Framework Reference UIScreen Class Reference

Options
Deployment Target:

On This Page
Language:

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

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.

Handling connect and disconnect notifications 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 1Handling connect and disconnect notifications
  1. - (void)handleScreenConnectNotification:(NSNotification*)aNotification {
  2. UIScreen* newScreen = [aNotification object];
  3. CGRect screenBounds = newScreen.bounds;
  4. if (!_secondWindow) {
  5. _secondWindow = [[UIWindow alloc] initWithFrame:screenBounds];
  6. _secondWindow.screen = newScreen;
  7. // Set the initial UI for the window and show it.
  8. [self.viewController displaySelectionInSecondaryWindow:_secondWindow];
  9. [_secondWindow makeKeyAndVisible];
  10. }
  11. }
  12. - (void)handleScreenDisconnectNotification:(NSNotification*)aNotification {
  13. if (_secondWindow) {
  14. // Hide and then delete the window.
  15. _secondWindow.hidden = YES;
  16. [_secondWindow release];
  17. _secondWindow = nil;
  18. // Update the main screen based on what is showing here.
  19. [self.viewController displaySelectionOnMainScreen];
  20. }
  21. }

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

  • Returns the screen object representing the device’s screen.

    Declaration

    Swift

    class func mainScreen() -> UIScreen

    Objective-C

    + (UIScreen * nonnull)mainScreen

    Return Value

    The screen object for the device

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    class func screens() -> [UIScreen]

    Objective-C

    + (NSArray<UIScreen *> * nonnull)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.

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

    Declaration

    Swift

    var mirroredScreen: UIScreen? { get }

    Objective-C

    @property(nonatomic, readonly, strong) 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

    + mainScreen

  • The current coordinate space of the screen. (read-only)

    Declaration

    Swift

    var coordinateSpace: UICoordinateSpace { get }

    Objective-C

    @property(readonly) id< UICoordinateSpace > coordinateSpace

    Discussion

    The screen’s current coordinate space always reflects any interface orientations applied to the device. Therefore, the bounds of this coordinate space match the bounds property of the screen itself.

    Availability

    Available in iOS 8.0 and later.

  • The fixed coordinate space of the screen. (read-only)

    Declaration

    Swift

    var fixedCoordinateSpace: UICoordinateSpace { get }

    Objective-C

    @property(readonly) id< UICoordinateSpace > fixedCoordinateSpace

    Discussion

    The bounds of this coordinate space always reflect the screen dimensions of the device in a portrait-up orientation. You can use this coordinate space in places where you need a fixed frame of reference. For example, if your app saves screen coordinate values to disk, convert those values to the fixed coordinate space before doing so. Saving them in the fixed coordinate space ensures that when your app reads the values later, it can convert them to the current coordinate space correctly.

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var bounds: CGRect { get }

    Objective-C

    @property(nonatomic, readonly) CGRect bounds

    Discussion

    This rectangle is specified in the current coordinate space, which takes into account any interface rotations in effect for the device. Therefore, the value of this property may change when the device rotates between portrait and landscape orientations.

    Availability

    Available in iOS 2.0 and later.

  • The frame rectangle for the app window, measured in points. (read-only)

    Declaration

    Swift

    var applicationFrame: CGRect { get }

    Objective-C

    @property(nonatomic, readonly) CGRect applicationFrame

    Discussion

    This property contains the bounds rectangle used by the app window, which in some versions of iOS may be different than the screen bounds themselves. This rectangle is specified in the current coordinate space, which takes into account any interface rotations in effect for the device. Therefore, the value of this property may change when the device rotates between portrait and landscape orientations.

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 9.0.

  • The bounding rectangle of the physical screen, measured in pixels. (read-only)

    Declaration

    Swift

    var nativeBounds: CGRect { get }

    Objective-C

    @property(nonatomic, readonly) CGRect nativeBounds

    Discussion

    This rectangle is based on the device in a portrait-up orientation. This value does not change as the device rotates.

    Availability

    Available in iOS 8.0 and later.

  • The native scale factor for the physical screen. (read-only)

    Declaration

    Swift

    var nativeScale: CGFloat { get }

    Objective-C

    @property(nonatomic, readonly) CGFloat nativeScale

    Availability

    Available in iOS 8.0 and later.

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

    Declaration

    Swift

    var scale: CGFloat { get }

    Objective-C

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

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

    Declaration

    Swift

    var preferredMode: UIScreenMode? { get }

    Objective-C

    @property(nonatomic, readonly, strong) UIScreenMode *preferredMode

    Availability

    Available in iOS 4.3 and later.

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

    Declaration

    Swift

    var availableModes: [UIScreenMode] { get }

    Objective-C

    @property(nonatomic, readonly, copy) NSArray <UIScreenMode *> *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.

  • The current screen mode associated with the screen.

    Declaration

    Swift

    var currentMode: UIScreenMode?

    Objective-C

    @property(nonatomic, strong) 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.

  • Returns a display link object for the current screen.

    Declaration

    Swift

    func displayLinkWithTarget(_ target: AnyObject, selector sel: Selector) -> CADisplayLink?

    Objective-C

    - (CADisplayLink * nullable)displayLinkWithTarget:(id nonnull)target selector:(SEL nonnull)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:

    Objective-C

    1. - (void)selector:(CADisplayLink *)sender;

    Swift

    1. func selector(sender: CADisplayLink) { }

    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.

  • The brightness level of the screen.

    Declaration

    Swift

    var brightness: CGFloat

    Objective-C

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

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

    Declaration

    Swift

    var wantsSoftwareDimming: Bool

    Objective-C

    @property(nonatomic) BOOL wantsSoftwareDimming

    Discussion

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

    Availability

    Available in iOS 5.0 and later.

  • Returns a snapshot view based on the current screen contents.

    Declaration

    Swift

    func snapshotViewAfterScreenUpdates(_ afterUpdates: Bool) -> UIView

    Objective-C

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

    Parameters

    afterUpdates

    A Boolean that indicates whether the snapshot should be taken after recent changes have been incorporated. Specify the value NOfalse 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.

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

    Declaration

    Swift

    enum UIScreenOverscanCompensation : Int { case Scale case InsetBounds case None static var InsetApplicationFrame: UIScreenOverscanCompensation { get } }

    Objective-C

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

    Constants

    • Scale

      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.

    • InsetBounds

      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.

    • InsetApplicationFrame

      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.

      Deprecated in iOS 9.0.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

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

    Declaration

    Swift

    let UIScreenDidConnectNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    let UIScreenDidDisconnectNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    let UIScreenModeDidChangeNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    let UIScreenBrightnessDidChangeNotification: String

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.