UIScreen Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
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.

Properties

applicationFrame

The frame rectangle to use for your application’s window. (read-only)

@property(nonatomic, readonly) CGRect applicationFrame
Discussion

This property contains the screen bounds minus the area occupied by the status bar, if it is visible. Using this property is the recommended way to retrieve your application’s initial window size. The rectangle is specified in points.

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.
Related Sample Code
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.

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, where one point is approximately equal to 1/160th of an inch. If a device’s screen has a reasonably similar pixel density, the scale factor is typically set to 1.0 so that one point maps to one pixel. However, a screen with a significantly different pixel density may set this property to a higher value.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
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.
Related Sample Code
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.
Related Sample Code
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

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


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-12-13)

Did this document help you? Yes It's good, but... Not helpful...