UIApplication Class Reference

Inherits from	UIResponder : NSObject
Conforms to	UIActionSheetDelegate NSObject (NSObject)
Framework	/System/Library/Frameworks/UIKit.framework
Availability	Available in iOS 2.0 and later.
Declared in	UIApplication.h
Related sample code	Audio Mixer (MixerHost) Regions RosyWriter Sampler Unit Presets (LoadPresetDemo) UICatalog

Overview

The UIApplication class provides a centralized point of control and coordination for applications running on iOS.

Every application must have exactly one instance of UIApplication (or a subclass of UIApplication). When an application is launched, the UIApplicationMain function is called; among its other tasks, this function creates a singleton UIApplication object. Thereafter you can access this object by invoking the sharedApplication class method.

A major role of a UIApplication object is to handle the initial routing of incoming user events. It also dispatches action messages forwarded to it by control objects (UIControl) to the appropriate target objects. In addition, the UIApplication object maintains a list of all the windows (UIWindow objects) currently open in the application, so through those it can retrieve any of the application’s UIView objects. The application object is typically assigned a delegate, an object that the application informs of significant runtime events—for example, application launch, low-memory warnings, and application termination—giving it an opportunity to respond appropriately.

Applications can cooperatively handle a resource such as an email or an image file through the openURL: method. For example, an application opening an email URL with this method may cause the mail client to launch and display the message.

The programmatic interfaces of UIApplication and UIApplicationDelegate also allow you to manage behavior that is specific to the device. You can control application response to changes in interface orientation, temporarily suspend incoming touch events, and turn proximity sensing (of the user’s face) off and on again.

For iOS 3.0, UIApplication has added methods for remote-notification registration, for triggering of the undo-redo UI (applicationSupportsShakeToEdit), and for determining whether any installed application can open a URL (canOpenURL:).

In iOS 4.0, UIApplication has added methods and constants for managing background execution, for scheduling and canceling local notifications, and for controlling the reception of remote-control events.

UIApplication defines a delegate that must adopt the UIApplicationDelegate protocol and implement some of the protocol methods.

Subclassing Notes

You might decide to subclass UIApplication to override sendEvent: or sendAction:to:from:forEvent: to implement custom event and action dispatching. However, there is rarely a valid need to extend this class; the application delegate (UIApplicationDelegate is sufficient for most occasions. If you do subclass UIApplication, be very sure of what you are trying to accomplish with the subclass.

Tasks

Getting the Application Instance

Setting and Getting the Delegate

Getting Application Windows

Managing the Default Interface Orientations

Controlling and Handling Events

Opening a URL Resource

Registering for Remote Notifications

Managing Application Activity

Managing Background Execution

Performing State Restoration Asynchronously

Registering for Local Notifications

Determining the Availability of Protected Content

Registering for Remote Control Events

Managing Status Bar Orientation

Controlling Application Appearance

Setting the Icon of a Newsstand Application

Properties

applicationIconBadgeNumber

The number currently set as the badge of the application icon in Springboard.

@property(nonatomic) NSInteger applicationIconBadgeNumber

Discussion

Set to 0 (zero) to hide the badge number. The default is 0.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

applicationState

The runtime state of the application. (read-only)

@property(nonatomic, readonly) UIApplicationState applicationState

Discussion

An application may be active, inactive, or running in the background. You can use the value in this property to determine which of these states the application is currently in.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

applicationSupportsShakeToEdit

A Boolean value that determines whether shaking the device displays the undo-redo user interface.

@property(nonatomic) BOOL applicationSupportsShakeToEdit

Discussion

The default value is YES. Set the property to NO if you don’t want your application to display the Undo and Redo buttons when users shake the device.

Availability

Available in iOS 3.0 and later.

Related Sample Code

SimpleUndo

Declared In

UIApplication.h

backgroundTimeRemaining

The amount of time the application has to run in the background. (read-only)

@property(nonatomic, readonly) NSTimeInterval backgroundTimeRemaining

Discussion

This property contains the amount of time the application has to run in the background before it may be forcibly killed by the system. While the application is running in the foreground, the value in this property remains suitably large. If the application starts one or more long-running tasks using the beginBackgroundTaskWithExpirationHandler: method and then transitions to the background, the value of this property is adjusted to reflect the amount of time the application has left to run.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

delegate

The delegate of the application object.

@property(nonatomic, assign) id<UIApplicationDelegate> delegate

Discussion

The delegate must adopt the UIApplicationDelegate formal protocol. UIApplication assigns and does not retain the delegate.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

UIApplication.h

idleTimerDisabled

A Boolean value that controls whether the idle timer is disabled for the application.

@property(nonatomic, getter=isIdleTimerDisabled) BOOL idleTimerDisabled

Discussion

The default value of this property is NO. When most applications have no touches as user input for a short period, the system puts the device into a "sleep” state where the screen dims. This is done for the purposes of conserving power. However, applications that don't have user input except for the accelerometer—games, for instance—can, by setting this property to YES, disable the “idle timer” to avert system sleep.

Availability

Available in iOS 2.0 and later.

Related Sample Code

aurioTouch2

Declared In

UIApplication.h

keyWindow

The application's key window. (read-only)

@property(nonatomic, readonly) UIWindow *keyWindow

Discussion

This property holds the UIWindow object in the windows array that is most recently sent the makeKeyAndVisible message.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

networkActivityIndicatorVisible

A Boolean value that turns an indicator of network activity on or off.

@property(nonatomic, getter=isNetworkActivityIndicatorVisible) BOOL networkActivityIndicatorVisible

Discussion

Specify YES if the application should show network activity and NO if it should not. The default value is NO. A spinning indicator in the status bar shows network activity. The application may explicitly hide or show this indicator.

Availability

Available in iOS 2.0 and later.

Related Sample Code

URLCache

Declared In

UIApplication.h

protectedDataAvailable

A Boolean value indicating whether content protection is active. (read-only)

@property(nonatomic, readonly, getter=isProtectedDataAvailable) BOOL protectedDataAvailable

Discussion

The value of this property is NO if content protection is enabled and the device is currently locked. The value of this property is set to YES if the device is unlocked or if content protection is not enabled.

When the value of this property is NO, files that were assigned the NSFileProtectionComplete protection key cannot be read or written by your application. The user must unlock the device before your application can access them.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

scheduledLocalNotifications

All currently scheduled local notifications.

@property(nonatomic, copy) NSArray *scheduledLocalNotifications

Discussion

This property holds an array of UILocalNotification instances representing the current scheduled local notifications. You can set or reset the local notifications in the array as well as access them.

This method may be faster than using scheduleLocalNotification: when scheduling a large number of notifications.

Availability

Available in iOS 4.2 and later.

Declared In

UIApplication.h

statusBarFrame

The frame rectangle defining the area of the status bar. (read-only)

@property(nonatomic, readonly) CGRect statusBarFrame

Discussion

The value of this property is CGRectZero if the status bar is hidden.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

statusBarHidden

A Boolean value that determines whether the status bar is hidden.

@property(nonatomic, getter=isStatusBarHidden) BOOL statusBarHidden

Return Value

YES means the status bar is hidden; NO means it's visible.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

statusBarOrientation

The current orientation of the application's status bar.

@property(nonatomic) UIInterfaceOrientation statusBarOrientation

Discussion

The value of this property is a constant that indicates an orientation of the receiver's status bar. See UIInterfaceOrientation for details. Setting this property rotates the status bar to the specified orientation without animating the transition. If your application has rotatable window content, however, you should not arbitrarily set status-bar orientation using this method. The status-bar orientation set by this method does not change if the device changes orientation. For more on rotatable window views, see View Controller Programming Guide for iOS.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

statusBarOrientationAnimationDuration

The animation duration in seconds for the status bar during a 90 degree orientation change. (read-only)

@property(nonatomic, readonly) NSTimeInterval statusBarOrientationAnimationDuration

Discussion

You should double the value of this property for a 180 degree orientation change in the status bar.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

statusBarStyle

The current style of the status bar.

@property(nonatomic) UIStatusBarStyle statusBarStyle

Discussion

The value of the property is a UIStatusBarStyle constant that indicates the style of status. The default style is UIStatusBarStyleDefault. The animation slides the status bar out for the old orientation and slides it in for the new orientation.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

UIApplication.h

userInterfaceLayoutDirection

Returns the layout direction of the user interface. (read-only)

@property(nonatomic, readonly) UIUserInterfaceLayoutDirection userInterfaceLayoutDirection

Discussion

This method specifies the general user interface layout flow direction. See “UIUserInterfaceLayoutDirection” for a description of the constants returned by this property.

Availability

Available in iOS 5.0 and later.

Declared In

UIApplication.h

windows

The application's visible and hidden windows. (read-only)

@property(nonatomic, readonly) NSArray *windows

Discussion

This property returns an array of the application's visible and hidden windows. The windows are ordered back to front.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

Class Methods

sharedApplication

Returns the singleton application instance.

+ (UIApplication *)sharedApplication

Return Value

The application instance is created in the UIApplicationMain function.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

UIApplication.h

Instance Methods

beginBackgroundTaskWithExpirationHandler:

Marks the beginning of a new long-running background task.

- (UIBackgroundTaskIdentifier)beginBackgroundTaskWithExpirationHandler:(void (^)(void))handler

Parameters

handler: A handler to be called shortly before the application’s remaining background time reaches 0. You should use this handler to clean up and mark the end of the background task. Failure to end the task explicitly will result in the termination of the application. The handler is called synchronously on the main thread, thus blocking the application’s suspension momentarily while the application is notified.

Return Value

A unique identifier for the new background task. You must pass this value to the endBackgroundTask: method to mark the end of this task. This method returns UIBackgroundTaskInvalid if running in the background is not possible.

Discussion

This method lets your application continue to run for a period of time after it transitions to the background. You should call this method at times where leaving a task unfinished might be detrimental to your application’s user experience. For example, your application could call this method to ensure that had enough time to transfer an important file to a remote server or at least attempt to make the transfer and note any errors. You should not use this method simply to keep your application running after it moves to the background.

Each call to this method must be balanced by a matching call to the endBackgroundTask: method. Applications running background tasks have a finite amount of time in which to run them. (You can find out how much time is available using the backgroundTimeRemaining property.) If you do not call endBackgroundTask: for each task before time expires, the system kills the application. If you provide a block object in the handler parameter, the system calls your handler before time expires to give you a chance to end the task.

You can call this method at any point in your application’s execution. You may also call this method multiple times to mark the beginning of several background tasks that run in parallel. However, each task must be ended separately. You identify a given task using the value returned by this method.

This method can be safely called on a non-main thread.

Availability

Available in iOS 4.0 and later.

Related Sample Code

AVCam

Declared In

UIApplication.h

beginIgnoringInteractionEvents

Tells the receiver to suspend the handling of touch-related events.

- (void)beginIgnoringInteractionEvents

Discussion

You typically call this method before starting an animation or transition. Calls are nested with the endIgnoringInteractionEvents method.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

beginReceivingRemoteControlEvents

Tells the application to begin receiving remote-control events.

- (void)beginReceivingRemoteControlEvents

Discussion

Remote-control events originate as commands issued by headsets and external accessories that are intended to control multimedia presented by an application. To stop the reception of remote-control events, you must call endReceivingRemoteControlEvents.

Availability

Available in iOS 4.0 and later.

Related Sample Code

Audio Mixer (MixerHost)

Declared In

UIApplication.h

cancelAllLocalNotifications

Cancels the delivery of all scheduled local notifications.

- (void)cancelAllLocalNotifications

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

cancelLocalNotification:

Cancels the delivery of the specified scheduled local notification.

- (void)cancelLocalNotification:(UILocalNotification *)notification

Parameters

notification: The local notification to cancel.

Discussion

Calling this method also programmatically dismisses the notification if it is currently displaying an alert.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

canOpenURL:

Returns whether an application can open a given URL resource.

- (BOOL)canOpenURL:(NSURL *)url

Parameters

url: A URL object that identifies a given resource. The URL’s scheme—possibly a custom scheme—identifies which application can handle the URL.

Return Value

NO if no application is available that will accept the URL; otherwise, returns YES.

Discussion

This method guarantees that that if openURL: is called, another application will be launched to handle it. It does not guarantee that the full URL is valid.

Availability

Available in iOS 3.0 and later.

Declared In

UIApplication.h

clearKeepAliveTimeout

Removes a previously installed periodic handler block.

- (void)clearKeepAliveTimeout

Discussion

If your VoIP application no longer needs to be woken up at periodic intervals, you can use this method to remove any previously installed handler.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

completeStateRestoration

Tells the app that your code has finished any asynchronous state restoration.

- (void)completeStateRestoration

Discussion

UIKit restores your application’s state synchronously on the main thread. If you choose to perform additional state restoration on a secondary thread, call the extendStateRestoration method to inform UIKit of that fact. Call this method after you finish with your background work to let the system know that state restoration is complete.

Availability

Available in iOS 6.0 and later.

Related Sample Code

State Restoration

Declared In

UIApplication.h

enabledRemoteNotificationTypes

Returns the types of notifications the application accepts.

- (UIRemoteNotificationType)enabledRemoteNotificationTypes

Return Value

A bit mask whose values indicate the types of notifications the user has requested for the application. See UIRemoteNotificationType for valid bit-mask values.

Discussion

The values in the returned bit mask indicate the types of notifications currently enabled for the application. These types are first set when the application calls the registerForRemoteNotificationTypes: method to register itself with Apple Push Notification Service. Thereafter, the user may modify these accepted notification types in the Notifications preference of the Settings application. This method returns those initial or modified values. iOS does not display or play notification types specified in the notification payload that are not one of the enabled types. For example, the application might accept icon-badging as a form of notification, but might reject sounds and alert messages, even if they are specified in the notification payload.

Availability

Available in iOS 3.0 and later.

Declared In

UIApplication.h

endBackgroundTask:

Marks the end of a specific long-running background task.

- (void)endBackgroundTask:(UIBackgroundTaskIdentifier)identifier

Parameters

identifier: An identifier returned by the beginBackgroundTaskWithExpirationHandler: method.

Discussion

You must call this method to end a task that was started using the beginBackgroundTaskWithExpirationHandler: method. If you do not, the system may kill your application.

This method can be safely called on a non-main thread.

Availability

Available in iOS 4.0 and later.

Related Sample Code

Declared In

UIApplication.h

endIgnoringInteractionEvents

Tells the receiver to resume the handling of touch-related events.

- (void)endIgnoringInteractionEvents

Discussion

You typically call this method when, after calling the beginIgnoringInteractionEvents method, the animation or transition concludes. Nested calls of this method should match nested calls of the beginIgnoringInteractionEvents method.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

endReceivingRemoteControlEvents

Tells the application to stop receiving remote-control events.

- (void)endReceivingRemoteControlEvents

Discussion

Remote-control events originate as commands issued by headsets and external accessories that are intended to control multimedia presented by an application.

Availability

Available in iOS 4.0 and later.

Related Sample Code

Audio Mixer (MixerHost)

Declared In

UIApplication.h

extendStateRestoration

Tells the app that your code is restoring state asynchronously.

- (void)extendStateRestoration

Discussion

UIKit restores your application’s state synchronously on the main thread. If you choose to perform additional state restoration on a secondary thread, call this method to inform UIKit of that fact. You must balance each call to this method with a matching call to the completeStateRestoration method.

Calling this method is a safety precaution in the event that your app crashes at launch time due to problems restoring its state. If you call this method but do not call the matching completeStateRestoration method before a crash occurs, the system throws away any saved state information. Doing so prevents your app from crashing during subsequent launches because of issues caused by trying to restore your app’s state.

Availability

Available in iOS 6.0 and later.

Related Sample Code

State Restoration

Declared In

UIApplication.h

isIgnoringInteractionEvents

Returns whether the receiver is ignoring events initiated by touches on the screen.

- (BOOL)isIgnoringInteractionEvents

Return Value

YES if the receiver is ignoring interaction events; otherwise NO. The method returns YES if the nested beginIgnoringInteractionEvents and endIgnoringInteractionEvents calls are at least one level deep.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

openURL:

Opens the resource at the specified URL.

- (BOOL)openURL:(NSURL *)url

Parameters

url: An object representing a URL (Universal Resource Locator). UIKit supports the http:, https:, tel:, and mailto: schemes.

Return Value

YES if the resource located by the URL was successfully opened; otherwise NO.

Discussion

The URL can locate a resource in the same or other application. If the resource is another application, invoking this method may cause the calling application to quit so the other one can be launched.

You may call canOpenURL: before calling this one to verify that there is an application that can handle it.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

UIApplication.h

presentLocalNotificationNow:

Presents a local notification immediately.

- (void)presentLocalNotificationNow:(UILocalNotification *)notification

Parameters

notification: A local notification that the operating system presents for the application immediately, regardless of the value of the notification’s fireDate property. Applications running in the background state can immediately present local notifications when there are incoming chats, messages, or updates. Because the operating system copies notification, you may release it once you have scheduled it.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

registerForRemoteNotificationTypes:

- (void)registerForRemoteNotificationTypes:(UIRemoteNotificationType)types

Parameters

types: A bit mask specifying the types of notifications the application accepts. See UIRemoteNotificationType for valid bit-mask values.

Discussion

When you send this message, the device initiates the registration process with Apple Push Service. If it succeeds, the application delegate receives a device token in the application:didRegisterForRemoteNotificationsWithDeviceToken: method; if registration doesn’t succeed, the delegate is informed via the application:didFailToRegisterForRemoteNotificationsWithError: method. If the application delegate receives a device token, it should connect with its provider and pass it the token.

iOS does not display or play notification types specified in the notification payload that are not one of the requested ones. For example, if alert messages are not one of the accepted notification types, iOS does not display an alert even if one is specified in the notification payload. To find out what the application’s current notification types are, call the enabledRemoteNotificationTypes method.

Availability

Available in iOS 3.0 and later.

Declared In

UIApplication.h

scheduleLocalNotification:

Schedules a local notification for delivery at its encapsulated date and time.

- (void)scheduleLocalNotification:(UILocalNotification *)notification

Parameters

notification: A local notification that the operating system delivers for the application at the date and time specified in the fireDate property of notification. Because the operating system copies notification, you may release it once you have scheduled it.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

sendAction:to:from:forEvent:

Sends an action message identified by selector to a specified target.

- (BOOL)sendAction:(SEL)action to:(id)target from:(id)sender forEvent:(UIEvent *)event

Parameters

action: A selector identifying an action method. See the discussion for information on the permitted selector forms.
target: The object to receive the action message. If target is nil, the application sends the message to the first responder, from whence it progresses up the responder chain until it is handled.
sender: The object that is sending the action message. The default sender is the UIControl object that invokes this method.
event: A UIEvent object that encapsulates information about the event originating the action message.

Return Value

YES if a responder object handled the action message, NO if no object in the responder chain handled the message.

Discussion

Normally, this method is invoked by a UIControl object that the user has touched. The default implementation dispatches the action method to the given target object or, if no target is specified, to the first responder. Subclasses may override this method to perform special dispatching of action messages.

By default, this method pushes two parameters when calling the target. These last two parameters are optional for the receiver because it is up to the caller (usually a UIControl object) to remove any parameters it added. This design enables the action selector to be one of the following:

- (void)action
- (void)action:(id)sender
- (void)action:(id)sender forEvent:(UIEvent *)event

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

sendEvent:

Dispatches an event to the appropriate responder objects in the application.

- (void)sendEvent:(UIEvent *)event

Parameters

event: A UIEvent object encapsulating the information about an event, including the touches involved.

Discussion

Subclasses may override this method to intercept incoming events. Any intercepted events should be dispatched by calling [super sendEvent:event] after examining the intercepted event.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

setKeepAliveTimeout:handler:

Configures a periodic handler for VoIP applications.

- (BOOL)setKeepAliveTimeout:(NSTimeInterval)timeout handler:(void (^)(void))keepAliveHandler

Parameters

timeout: The maximum interval (measured in seconds) at which your application should be woken up to check its VoIP connection. The minimum acceptable timeout value is 600 seconds.
keepAliveHandler: A block that performs the tasks needed to maintain your VoIP network connection. Setting this parameter to nil releases the current handler block and prevents UIKit from scheduling the next wake.

Return Value

YES if the handler was installed or NO if it was not.

Discussion

A voice-over-IP (VoIP) application can use this method to install a handler whose job is to maintain the application’s network connection with a VoIP server. This handler is guaranteed to be called before the specified timeout value but may be called at a slightly different time interval in order to better align execution of your handler with other system tasks, and thereby save power. Your handler has a maximum of 10 seconds to perform any needed tasks and exit. If it does not exit before time expires, the application is suspended.

Timeout values and handlers are not persisted between application launches. Therefore, if your application is terminated for any reason, you must reinstall the handler during the next launch cycle.

For calls to this method to succeed, the application must have the voip value in the array associated with the UIBackgroundModes key in its Info.plist file. Calling this method replaces the previously installed handler and timeout values, if any.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

setNewsstandIconImage:

Sets the icon of a Newsstand application to an image depicting the current issue of a publication.

- (void)setNewsstandIconImage:(UIImage *)image

Parameters

image: An image to use as the icon of a Newsstand application. Pass nil to clear the currently set image and revert to the icon stored in the application bundle.

Discussion

The Newsstand application icon is typically downloaded from the application’s server for each issue.

Availability

Available in iOS 5.0 and later.

Declared In

UIApplication.h

setStatusBarHidden:withAnimation:

Hides or shows the status bar, optionally animating the transition.

- (void)setStatusBarHidden:(BOOL)hidden withAnimation:(UIStatusBarAnimation)animation

Parameters

hidden: YES to hide the status bar, NO to show the status bar.
animation: A constant that indicates whether there should be an animation and, if one is requested, whether it should fade the status bar in or out or whether it should slide the status bar in or out.

Discussion

See the descriptions of the constants of the UIStatusBarAnimation type for more information.

Availability

Available in iOS 3.2 and later.

Related Sample Code

Declared In

UIApplication.h

setStatusBarOrientation:animated:

Sets the application's status bar to the specified orientation, optionally animating the transition.

- (void)setStatusBarOrientation:(UIInterfaceOrientation)interfaceOrientation animated:(BOOL)animated

Parameters

interfaceOrientation: A specific orientation of the status bar. See UIInterfaceOrientation for details. The default value is UIInterfaceOrientationPortrait.
animated: YES if the transition to the new orientation should be animated; NO if it should be immediate, without animation.

Discussion

Calling this method changes the value of the statusBarOrientation property and rotates the status bar, animating the transition if animated is YES . If your application has rotatable window content, however, you should not arbitrarily set status-bar orientation using this method. The status-bar orientation set by this method does not change if the device changes orientation.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

setStatusBarStyle:animated:

Sets the style of the status bar, optionally animating the transition to the new style.

- (void)setStatusBarStyle:(UIStatusBarStyle)statusBarStyle animated:(BOOL)animated

Parameters

statusBarStyle: A constant that specifies a style for the status bar. See the descriptions of the constants in UIStatusBarStyle for details.
animated: YES if the transition to the new style should be animated; otherwise NO .

Discussion

The animation slides the status bar out toward the top of the interface.

Availability

Available in iOS 2.0 and later.

Related Sample Code

Declared In

UIApplication.h

supportedInterfaceOrientationsForWindow:

Returns the default set of interface orientations to use for the view controllers in the specified window.

- (NSUInteger)supportedInterfaceOrientationsForWindow:(UIWindow *)window

Parameters

window: The window whose default interface orientations you want to retrieve.

Return Value

A bit mask specifying which orientations are supported. See “UIInterfaceOrientationMask” for valid bit-mask values. The value returned by this method must not be 0.

Discussion

This method returns the default interface orientations for the app. These orientations are used only for view controllers that do not specify their own. If your app delegate implements the application:supportedInterfaceOrientationsForWindow: method, the system does not call this method.

The default implementation of this method returns the app’s default set of supported interface orientations, as defined in the UISupportedInterfaceOrientations key of the Info.plist file. If the file does not contain that key, this method returns all interface orientations for the iPad idiom and returns all interface orientations except the portrait upside-down orientation for the iPhone idiom.

Availability

Available in iOS 6.0 and later.

Declared In

UIApplication.h

unregisterForRemoteNotifications

Unregister for notifications received from Apple Push Service.

- (void)unregisterForRemoteNotifications

Discussion

You should call this method in rare circumstances only, such as when a new version of the application drops support for remote notifications. Users can temporarily prevent applications from receiving remote notifications through the Notifications section of the Settings application. Applications unregistered through this method can always re-register.

Availability

Available in iOS 3.0 and later.

Declared In

UIApplication.h

Constants

UIInterfaceOrientation

The orientation of the application's user interface.

typedef enum {
   UIInterfaceOrientationPortrait           = UIDeviceOrientationPortrait,
   UIInterfaceOrientationPortraitUpsideDown = UIDeviceOrientationPortraitUpsideDown,
   UIInterfaceOrientationLandscapeLeft      = UIDeviceOrientationLandscapeRight,
   UIInterfaceOrientationLandscapeRight     = UIDeviceOrientationLandscapeLeft
} UIInterfaceOrientation;

Constants

UIInterfaceOrientationPortrait

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

Available in iOS 2.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationPortraitUpsideDown

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

UIInterfaceOrientationLandscapeLeft

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

UIInterfaceOrientationLandscapeRight

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

Discussion

You use these constants in the statusBarOrientation property and the setStatusBarOrientation:animated: method. Notice that UIDeviceOrientationLandscapeRightis assigned to UIInterfaceOrientationLandscapeLeft and UIDeviceOrientationLandscapeLeft is assigned to UIInterfaceOrientationLandscapeRight; the reason for this is that rotating the device requires rotating the content in the opposite direction.

Declared In

UIApplication.h

UIInterfaceOrientationMask

These constants are mask bits for specifying a view controller’s supported interface orientations.

typedef enum {
   UIInterfaceOrientationMaskPortrait = (1 << UIInterfaceOrientationPortrait),
   UIInterfaceOrientationMaskLandscapeLeft = (1 << UIInterfaceOrientationLandscapeLeft),
   UIInterfaceOrientationMaskLandscapeRight = (1 << UIInterfaceOrientationLandscapeRight),
   UIInterfaceOrientationMaskPortraitUpsideDown = (1 << UIInterfaceOrientationPortraitUpsideDown),
   UIInterfaceOrientationMaskLandscape =
   (UIInterfaceOrientationMaskLandscapeLeft | UIInterfaceOrientationMaskLandscapeRight),
   UIInterfaceOrientationMaskAll =
   (UIInterfaceOrientationMaskPortrait | UIInterfaceOrientationMaskLandscapeLeft |
   UIInterfaceOrientationMaskLandscapeRight | UIInterfaceOrientationMaskPortraitUpsideDown),
   UIInterfaceOrientationMaskAllButUpsideDown =
   (UIInterfaceOrientationMaskPortrait | UIInterfaceOrientationMaskLandscapeLeft |
   UIInterfaceOrientationMaskLandscapeRight),
} UIInterfaceOrientationMask;

Constants

UIInterfaceOrientationMaskPortrait

The view controller supports a portrait interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskLandscapeLeft

The view controller supports a landscape-left interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskLandscapeRight

The view controller supports a landscape-right interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskPortraitUpsideDown

The view controller supports an upside-down portrait interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskLandscape

The view controller supports both landscape-left and landscape-right interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskAll

The view controller supports all interface orientations.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

UIInterfaceOrientationMaskAllButUpsideDown

The view controller supports all but the upside-down portrait interface orientation.

Available in iOS 6.0 and later.

Declared in UIApplication.h.

Discussion

You return these constants from the supportedInterfaceOrientationsForWindow: method or when determining which orientations to support in your app’s view controllers.

UIUserInterfaceLayoutDirection

Specifies the directional flow of the user interface.

typedef enum {
   UIUserInterfaceLayoutDirectionLeftToRight,
   UIUserInterfaceLayoutDirectionRightToLeft,
} UIUserInterfaceLayoutDirection;

Constants

UIUserInterfaceLayoutDirectionLeftToRight

The layout direction is left to right.

Available in iOS 5.0 and later.

Declared in UIApplication.h.

UIUserInterfaceLayoutDirectionRightToLeft

The layout direction right to left. This value is appropriate when running with localizations such as Arabic or Hebrew that should have the user interface layout origin on the right edge of the coordinate system.

Available in iOS 5.0 and later.

Declared in UIApplication.h.

Discussion

One of these constants is returned by the userInterfaceLayoutDirection property. It indicates the directionality of the language in the user interface of the application.

Declared In

UIApplication.h

UIStatusBarStyle

The style of the device’s status bar.

typedef enum {
   UIStatusBarStyleDefault,
   UIStatusBarStyleBlackTranslucent,
   UIStatusBarStyleBlackOpaque
} UIStatusBarStyle;

Constants

UIStatusBarStyleDefault

A gray style (the default).

Available in iOS 2.0 and later.

Declared in UIApplication.h.

UIStatusBarStyleBlackTranslucent

A transparent black style (specifically, black with an alpha of 0.5).

Available in iOS 2.0 and later.

Declared in UIApplication.h.

UIStatusBarStyleBlackOpaque

An opaque black style.

Available in iOS 2.0 and later.

Declared in UIApplication.h.

Special Considerations

On iPad devices, the UIStatusBarStyleDefault and UIStatusBarStyleBlackTranslucent styles default to the UIStatusBarStyleBlackOpaque appearance.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

UIStatusBarAnimation

The animation applied to the status bar as it is hidden or made visible.

typedef enum {
   UIStatusBarAnimationNone,
   UIStatusBarAnimationFade,
   UIStatusBarAnimationSlide,
} UIStatusBarAnimation;

Constants

UIStatusBarAnimationNone

No animation is applied to the status bar as it is shown or hidden.

Available in iOS 3.2 and later.

Declared in UIApplication.h.

UIStatusBarAnimationFade

The status bar fades in and out as it is shown or hidden, respectively.

Available in iOS 3.2 and later.

Declared in UIApplication.h.

UIStatusBarAnimationSlide

The status bar slides in or out as it is shown or hidden, respectively.

Available in iOS 3.2 and later.

Declared in UIApplication.h.

Discussion

Constants of the UIStatusBarAnimation type are arguments of the setStatusBarHidden:withAnimation: method.

Availability

Available in iOS 3.2 and later.

Declared In

UIApplication.h

Run Loop Mode for Tracking

Mode while tracking in controls is taking place.

UIKIT_EXTERN NSString *UITrackingRunLoopMode;

Constants

UITrackingRunLoopMode

The mode set while tracking in controls takes place. You can use this mode to add timers that fire during tracking.

Available in iOS 2.0 and later.

Declared in UIApplication.h.

Declared In

UIApplication.h

UserInfo Dictionary Keys

Keys used to access values in the userInfo dictionary of some UIApplication-posted notifications.

NSString *const UIApplicationStatusBarOrientationUserInfoKey;
NSString *const UIApplicationStatusBarFrameUserInfoKey;

Constants

UIApplicationStatusBarOrientationUserInfoKey

Accesses an NSNumber object that encapsulates a UIInterfaceOrientation value indicating the current orientation (see UIInterfaceOrientation). This key is used with UIApplicationDidChangeStatusBarOrientationNotification and UIApplicationWillChangeStatusBarOrientationNotification notifications.

Available in iOS 2.0 and later.

Declared in UIApplication.h.

UIApplicationStatusBarFrameUserInfoKey

Accesses an NSValue object that encapsulates a CGRect structure expressing the location and size of the new status bar frame. This key is used with UIApplicationDidChangeStatusBarFrameNotification and UIApplicationWillChangeStatusBarFrameNotification notifications.

Available in iOS 2.0 and later.

Declared in UIApplication.h.

Declared In

UIApplication.h

UIRemoteNotificationType

Constants indicating the types of notifications the application accepts.

typedef enum {
   UIRemoteNotificationTypeNone    = 0,
   UIRemoteNotificationTypeBadge   = 1 << 0,
   UIRemoteNotificationTypeSound   = 1 << 1,
   UIRemoteNotificationTypeAlert   = 1 << 2,
   UIRemoteNotificationTypeNewsstandContentAvailability = 1 << 3
} UIRemoteNotificationType;

Constants

UIRemoteNotificationTypeNone

The application accepts no notifications.

Available in iOS 3.0 and later.

Declared in UIApplication.h.

UIRemoteNotificationTypeBadge

The application accepts notifications that badge the application icon.

Available in iOS 3.0 and later.

Declared in UIApplication.h.

UIRemoteNotificationTypeSound

The application accepts alert sounds as notifications.

Available in iOS 3.0 and later.

Declared in UIApplication.h.

UIRemoteNotificationTypeAlert

The application accepts alert messages as notifications.

Available in iOS 3.0 and later.

Declared in UIApplication.h.

UIRemoteNotificationTypeNewsstandContentAvailability

The application accepts notifications that start the downloading of issue assets for Newsstand applications.

Available in iOS 5.0 and later.

Declared in UIApplication.h.

Discussion

One or more of the values in the UIRemoteNotificationType bit mask are passed to iOS as the argument of the registerForRemoteNotificationTypes: method. Thereafter, iOS filters notifications for the application based on these values. You can always get the current notification types by calling the enabledRemoteNotificationTypes method.

Availability

Available in iOS 3.0 and later.

Declared In

UIApplication.h

UIBackgroundTaskIdentifier

A unique token that identifies a request to run in the background.

typedef NSUInteger UIBackgroundTaskIdentifier;

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

Background Task Constants

Constants used when running in the background.

const UIBackgroundTaskIdentifier UIBackgroundTaskInvalid;
const NSTimeInterval UIMinimumKeepAliveTimeout;

Constants

UIBackgroundTaskInvalid

An token indicating an invalid task request. This constant should be used to initialize variables or to check for errors.

Available in iOS 4.0 and later.

Declared in UIApplication.h.

UIMinimumKeepAliveTimeout

The minimum amount of time (measured in seconds) an application may run a critical background task in the background.

Available in iOS 4.0 and later.

Declared in UIApplication.h.

UIApplicationState

The running states of an application

typedef enum {
   UIApplicationStateActive,
   UIApplicationStateInactive,
   UIApplicationStateBackground
} UIApplicationState;

Constants

UIApplicationStateActive

The application is running in the foreground and currently receiving events.

Available in iOS 4.0 and later.

Declared in UIApplication.h.

UIApplicationStateInactive

The application is running in the foreground but is not receiving events. This might happen as a result of an interruption or because the application is transitioning to or from the background.

Available in iOS 4.0 and later.

Declared in UIApplication.h.

UIApplicationStateBackground

The application is running in the background.

Available in iOS 4.0 and later.

Declared in UIApplication.h.

Exceptions

The following constant defines an exception that can be thrown by the application.

NSString *const UIApplicationInvalidInterfaceOrientationException;

Constants

UIApplicationInvalidInterfaceOrientationException

This exception is thrown if a view controller or the app returns 0 instead of a valid set of supported interface orientation values. It is also thrown if the orientation returned by a view controller’s preferredInterfaceOrientationForPresentation method does not match one of the view controller’s supported orientations.

Available in iOS 6.0 and later.

Available in iOS 2.0 and later.

Declared In

UIApplication.h

UIApplicationWillChangeStatusBarFrameNotification

Posted when the application is about to change the frame of the status bar.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

UIApplicationWillEnterForegroundNotification

Posted shortly before an application leaves the background state on its way to becoming the active application.

The object of the notification is the UIApplication object. There is no userInfo dictionary.

Availability

Available in iOS 4.0 and later.

Declared In

UIApplication.h

UIApplicationWillResignActiveNotification

Posted when the application is no longer active and loses focus.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

UIApplicationWillTerminateNotification

Posted when the application is about to terminate.

This notification is associated with the delegate applicationWillTerminate: method. This notification does not contain a userInfo dictionary.

Availability

Available in iOS 2.0 and later.

Declared In

UIApplication.h

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

UIApplication Class Reference

Overview

Subclassing Notes

Tasks

Getting the Application Instance

Setting and Getting the Delegate

Getting Application Windows

Managing the Default Interface Orientations

Controlling and Handling Events

Opening a URL Resource

Registering for Remote Notifications

Managing Application Activity

Managing Background Execution

Performing State Restoration Asynchronously

Registering for Local Notifications

Determining the Availability of Protected Content

Registering for Remote Control Events

Managing Status Bar Orientation

Controlling Application Appearance

Setting the Icon of a Newsstand Application

Properties

applicationIconBadgeNumber

Discussion

Availability

Declared In

applicationState

Discussion

Availability

Declared In

applicationSupportsShakeToEdit

Discussion

Availability

Related Sample Code

Declared In

backgroundTimeRemaining

Discussion

Availability

Declared In

delegate

Discussion

Availability

Related Sample Code

Declared In

idleTimerDisabled

Discussion

Availability

Related Sample Code

Declared In

keyWindow

Discussion

Availability

See Also

Declared In

networkActivityIndicatorVisible

Discussion

Availability

Related Sample Code

Declared In

protectedDataAvailable

Discussion

Availability

Declared In

scheduledLocalNotifications

Discussion

Availability

Declared In

statusBarFrame

Discussion

Availability

See Also

Declared In

statusBarHidden

Return Value

Availability

See Also

Declared In

statusBarOrientation

Discussion

Availability

See Also