UIDevice 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
UIDevice.h
Related sample code

Overview

The UIDevice class provides a singleton instance representing the current device. From this instance you can obtain information about the device such as assigned name, device model, and operating-system name and version.

You also use the UIDevice instance to detect changes in the device’s characteristics, such as physical orientation. You get the current orientation using the orientation property or receive change notifications by registering for the UIDeviceOrientationDidChangeNotification notification. Before using either of these techniques to get orientation data, you must enable data delivery using the beginGeneratingDeviceOrientationNotifications method. When you no longer need to track the device orientation, call the endGeneratingDeviceOrientationNotifications method to disable the delivery of notifications.

Similarly, you can use the UIDevice instance to obtain information and notifications about changes to the battery’s charge state (described by the batteryState property) and charge level (described by the batteryLevel property). The UIDevice instance also provides access to the proximity sensor state (described by the proximityState property). The proximity sensor detects whether the user is holding the device close to their face. Enable battery monitoring or proximity sensing only when you need it.

Starting in iOS 4.2, you can use the playInputClick instance method to play keyboard input clicks in custom input and keyboard accessory views.

Tasks

Getting the Shared Device Instance

Determining the Available Features

Identifying the Device and Operating System

Getting the Device Orientation

Getting the Device Battery State

Using the Proximity Sensor

Playing Input Clicks

Properties

batteryLevel

The battery charge level for the device. (read-only)

@property(nonatomic, readonly) float batteryLevel
Discussion

Battery level ranges from 0.0 (fully discharged) to 1.0 (100% charged). Before accessing this property, ensure that battery monitoring is enabled.

If battery monitoring is not enabled, battery state is UIDeviceBatteryStateUnknown and the value of this property is –1.0.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIDevice.h

batteryMonitoringEnabled

A Boolean value indicating whether battery monitoring is enabled (YES) or not (NO).

@property(nonatomic, getter=isBatteryMonitoringEnabled) BOOL batteryMonitoringEnabled
Discussion

Enable battery monitoring if your app needs to be notified of changes to the battery state, or if you want to check the battery charge level.

The default value of this property is NO, which:

  • Disables the posting of battery-related notifications

  • Disables the ability to read battery charge level and battery state

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIDevice.h

batteryState

The battery state for the device. (read-only)

@property(nonatomic, readonly) UIDeviceBatteryState batteryState
Discussion

The value for batteryState is one of the constants in “UIDeviceBatteryState.”

If battery monitoring is not enabled, the value of this property is UIDeviceBatteryStateUnknown.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIDevice.h

generatesDeviceOrientationNotifications

A Boolean value that indicates whether the receiver generates orientation notifications (YES) or not (NO). (read-only)

@property(nonatomic, readonly, getter=isGeneratingDeviceOrientationNotifications) BOOL generatesDeviceOrientationNotifications
Discussion

If the value of this property is YES, the shared UIDevice object posts a UIDeviceOrientationDidChangeNotification notification when the device changes orientation. If the value is NO, it generates no orientation notifications. Device orientation notifications can only be generated between calls to the beginGeneratingDeviceOrientationNotifications and endGeneratingDeviceOrientationNotifications methods.

Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDevice.h

identifierForVendor

An alphanumeric string that uniquely identifies a device to the app’s vendor. (read-only)

@property(nonatomic, readonly, retain) NSUUID *identifierForVendor
Discussion

The value of this property is the same for apps that come from the same vendor running on the same device. A different value is returned for apps on the same device that come from different vendors, and for apps on different devices regardless of vendor.

The value of this property may be nil if the app is running in the background, before the user has unlocked the device the first time after the device has been restarted. If the value is nil, wait and get the value again later.

The value in this property remains the same while the app (or another app from the same vendor) is installed on the iOS device. The value changes when the user deletes all of that vendor’s apps from the device and subsequently reinstalls one or more of them. Therefore, if your app stores the value of this property anywhere, you should gracefully handle situations where the identifier changes.

Availability
  • Available in iOS 6.0 and later.
Declared In
UIDevice.h

localizedModel

The model of the device as a localized string. (read-only)

@property(nonatomic, readonly, retain) NSString *localizedModel
Discussion

This string would be a localized version of the string returned from model.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDevice.h

model

The model of the device. (read-only)

@property(nonatomic, readonly, retain) NSString *model
Discussion

Possible examples of model strings are @”iPhone” and @”iPod touch”.

Availability
  • Available in iOS 2.0 and later.
Declared In
UIDevice.h

multitaskingSupported

A Boolean value indicating whether multitasking is supported on the current device. (read-only)

@property(nonatomic, readonly, getter=isMultitaskingSupported) BOOL multitaskingSupported
Availability
  • Available in iOS 4.0 and later.
Declared In
UIDevice.h

name

The name identifying the device. (read-only)

@property(nonatomic, readonly, retain) NSString *name
Discussion

The value of this property is an arbitrary alphanumeric string that is associated with the device as an identifier. For example, you can find the name of an iOS device in the General > About settings.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDevice.h

orientation

Returns the physical orientation of the device. (read-only)

@property(nonatomic, readonly) UIDeviceOrientation orientation
Discussion

The value of the property is a constant that indicates the current orientation of the device. This value represents the physical orientation of the device and may be different from the current orientation of your application’s user interface. See “UIDeviceOrientation” for descriptions of the possible values.

The value of this property always returns 0 unless orientation notifications have been enabled by calling beginGeneratingDeviceOrientationNotifications.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDevice.h

proximityMonitoringEnabled

A Boolean value indicating whether proximity monitoring is enabled (YES) or not (NO).

@property(nonatomic, getter=isProximityMonitoringEnabled) BOOL proximityMonitoringEnabled
Discussion

Enable proximity monitoring only when your application needs to be notified of changes to the proximity state. Otherwise, disable proximity monitoring. The default value is NO.

Not all iOS devices have proximity sensors. To determine if proximity monitoring is available, attempt to enable it. If the value of the proximityMonitoringEnabled property remains NO, proximity monitoring is not available.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIDevice.h

proximityState

A Boolean value indicating whether the proximity sensor is close to the user (YES) or not (NO). (read-only)

@property(nonatomic, readonly) BOOL proximityState
Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
UIDevice.h

systemName

The name of the operating system running on the device represented by the receiver. (read-only)

@property(nonatomic, readonly, retain) NSString *systemName
Availability
  • Available in iOS 2.0 and later.
See Also
Declared In
UIDevice.h

systemVersion

The current version of the operating system. (read-only)

@property(nonatomic, readonly, retain) NSString *systemVersion
Discussion

An example of the system version is @”1.2”.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDevice.h

userInterfaceIdiom

The style of interface to use on the current device. (read-only)

@property(nonatomic, readonly) UIUserInterfaceIdiom userInterfaceIdiom
Discussion

For universal applications, you can use this property to tailor the behavior of your application for a specific type of device. For example, iPhone and iPad devices have different screen sizes, so you might want to create different views and controls based on the type of the current device.

Availability
  • Available in iOS 3.2 and later.
Declared In
UIDevice.h

Class Methods

currentDevice

Returns an object representing the current device.

+ (UIDevice *)currentDevice
Return Value

A singleton object that represents the current device.

Discussion

You access the properties of the returned UIDevice instance to obtain information about the device. You must instantiate the UIDevice instance before registering to receive device notifications.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UIDevice.h

Instance Methods

beginGeneratingDeviceOrientationNotifications

Begins the generation of notifications of device orientation changes.

- (void)beginGeneratingDeviceOrientationNotifications
Discussion

You must call this method before attempting to get orientation data from the receiver. This method enables the device’s accelerometer hardware and begins the delivery of acceleration events to the receiver. The receiver subsequently uses these events to post UIDeviceOrientationDidChangeNotification notifications when the device orientation changes and to update the orientation property.

You may nest calls to this method safely, but you should always match each call with a corresponding call to the endGeneratingDeviceOrientationNotifications method.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDevice.h

endGeneratingDeviceOrientationNotifications

Ends the generation of notifications of device orientation changes.

- (void)endGeneratingDeviceOrientationNotifications
Discussion

This method stops the posting of UIDeviceOrientationDidChangeNotification notifications and notifies the system that it can power down the accelerometer hardware if it is not in use elsewhere. You call this method after a previous call to the beginGeneratingDeviceOrientationNotifications method.

Availability
  • Available in iOS 2.0 and later.
See Also
Related Sample Code
Declared In
UIDevice.h

playInputClick

Plays an input click in an enabled input view.

- (void)playInputClick
Discussion

Use this method to play the standard system keyboard click in response to a user tapping in a custom input or keyboard accessory view. A click plays only if the user has enabled keyboard clicks in Settings > Sounds, and only if the input view is itself enabled and visible.

To enable a custom input or accessory view for input clicks, perform the following two steps:

  1. Adopt the UIInputViewAudioFeedback protocol in your input view class.

  2. Implement the enableInputClicksWhenVisible delegate method to return YES.

For more information, see Text, Web, and Editing Programming Guide for iOS.

Availability
  • Available in iOS 4.2 and later.
Declared In
UIDevice.h

Constants

UIDeviceBatteryState

The battery power state of the device.

typedef enum {
   UIDeviceBatteryStateUnknown,
   UIDeviceBatteryStateUnplugged,
   UIDeviceBatteryStateCharging,
   UIDeviceBatteryStateFull,
} UIDeviceBatteryState;
Constants
UIDeviceBatteryStateUnknown

The battery state for the device cannot be determined.

Available in iOS 3.0 and later.

Declared in UIDevice.h.

UIDeviceBatteryStateUnplugged

The device is not plugged into power; the battery is discharging.

Available in iOS 3.0 and later.

Declared in UIDevice.h.

UIDeviceBatteryStateCharging

The device is plugged into power and the battery is less than 100% charged.

Available in iOS 3.0 and later.

Declared in UIDevice.h.

UIDeviceBatteryStateFull

The device is plugged into power and the battery is 100% charged.

Available in iOS 3.0 and later.

Declared in UIDevice.h.

Discussion

These constants are used by the batteryState property.

UIDeviceOrientation

The physical orientation of the device. 

typedef enum {
   UIDeviceOrientationUnknown,
   UIDeviceOrientationPortrait,
   UIDeviceOrientationPortraitUpsideDown,
   UIDeviceOrientationLandscapeLeft,
   UIDeviceOrientationLandscapeRight,
   UIDeviceOrientationFaceUp,
   UIDeviceOrientationFaceDown
} UIDeviceOrientation;
Constants
UIDeviceOrientationUnknown

The orientation of the device cannot be determined.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationPortrait

The device is in portrait mode, with the device held upright and the home button at the bottom.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationPortraitUpsideDown

The device is in portrait mode but upside down, with the device held upright and the home button at the top.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationLandscapeLeft

The device is in landscape mode, with the device held upright and the home button on the right side.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationLandscapeRight

The device is in landscape mode, with the device held upright and the home button on the left side.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationFaceUp

The device is held parallel to the ground with the screen facing upwards.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

UIDeviceOrientationFaceDown

The device is held parallel to the ground with the screen facing downwards.

Available in iOS 2.0 and later.

Declared in UIDevice.h.

Discussion

The orientation property uses these constants to identify the device orientation. These constants identify the physical orientation of the device and are not tied to the orientation of your application’s user interface.

UIUserInterfaceIdiom

The type of interface that should be used on the current device

typedef enum {
   UIUserInterfaceIdiomPhone,
   UIUserInterfaceIdiomPad,
} UIUserInterfaceIdiom;
Constants
UIUserInterfaceIdiomPhone

The user interface should be designed for iPhone and iPod touch.

Available in iOS 3.2 and later.

Declared in UIDevice.h.

UIUserInterfaceIdiomPad

The user interface should be designed for iPad.

Available in iOS 3.2 and later.

Declared in UIDevice.h.

Notifications

All UIDevice notifications are posted by the singleton device instance returned by currentDevice.

UIDeviceBatteryLevelDidChangeNotification

Posted when the battery level changes.

For this notification to be sent, you must set the batteryMonitoringEnabled property to YES.

Notifications for battery level change are sent no more frequently than once per minute. Do not attempt to calculate battery drainage rate or battery time remaining; drainage rate can change frequently depending on built-in applications as well as your application.

You can obtain the battery level by getting the value of the batteryLevel property.

Availability
Declared In
UIDevice.h

UIDeviceBatteryStateDidChangeNotification

Posted when battery state changes.

For this notification to be sent, you must set the batteryMonitoringEnabled property to YES.

You can obtain the battery state by getting the value of the batteryState property.

Availability
Declared In
UIDevice.h

UIDeviceOrientationDidChangeNotification

Posted when the orientation of the device changes.

You can obtain the new orientation by getting the value of the orientation property.

Availability
Declared In
UIDevice.h

UIDeviceProximityStateDidChangeNotification

Posted when the state of the proximity sensor changes.

You can obtain the proximity state by getting the value of the proximityState property.

Availability
Declared In
UIDevice.h


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

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