UIApplicationDelegate Protocol

UIApplicationDelegate Protocol Reference
Contents
UIApplicationDelegate Protocol Reference 4

Overview 4 Tasks 5 Monitoring App State Changes 5 Managing App State Restoration 6 Providing a Window for Storyboarding 6 Managing the Default Interface Orientations 6 Opening a URL Resource 6 Managing Status Bar Changes 7 Responding to System Notifications 7 Handling Remote Notifications 7 Handling Local Notifications 8 Responding to Content Protection Changes 8 Properties 8 window 8 Instance Methods 9 application:didChangeStatusBarFrame: 9 application:didChangeStatusBarOrientation: 9 application:didDecodeRestorableStateWithCoder: 10 application:didFailToRegisterForRemoteNotificationsWithError: 11 application:didFinishLaunchingWithOptions: 11 application:didReceiveLocalNotification: 13 application:didReceiveRemoteNotification: 14 application:didRegisterForRemoteNotificationsWithDeviceToken: 15 application:handleOpenURL: 16 application:openURL:sourceApplication:annotation: 17 application:shouldRestoreApplicationState: 19 application:shouldSaveApplicationState: 19 application:supportedInterfaceOrientationsForWindow: 20 application:viewControllerWithRestorationIdentifierPath:coder: 21 application:willChangeStatusBarFrame: 22 application:willChangeStatusBarOrientation:duration: 23 application:willEncodeRestorableStateWithCoder: 24 application:willFinishLaunchingWithOptions: 25
2012-09-19 | 2012 Apple Inc. All Rights Reserved.
Contents
applicationDidBecomeActive: 26 applicationDidEnterBackground: 27 applicationDidFinishLaunching: 28 applicationDidReceiveMemoryWarning: 29 applicationProtectedDataDidBecomeAvailable: 30 applicationProtectedDataWillBecomeUnavailable: 30 applicationSignificantTimeChange: 31 applicationWillEnterForeground: 31 applicationWillResignActive: 32 applicationWillTerminate: 33 Constants 34 Launch Options Keys 34 App-Specific State Restoration Keys 36
Document Revision History 37
UIApplicationDelegate Protocol Reference
Conforms to Framework Availability Declared in
NSObject /System/Library/Frameworks/UIKit.framework Available in iOS 2.0 and later. UIApplication.h UIStateRestoration.h
Companion guides
iOS App Programming Guide Local and Push Notification Programming Guide
Related sample code
iAdSuite ScrollViewSuite SquareCam TableViewSuite Touches
Overview
The UIApplicationDelegate protocol declares methods that are implemented by the delegate of the singleton UIApplication object. These methods provide you with information about key events in an applications execution such as when it finished launching, when it is about to be terminated, when memory is low, and when important changes occur. Implementing these methods gives you a chance to respond to these system events and respond appropriately. One of the main jobs of the application delegate is to track the state transitions the application goes through while it is running. Prior to iOS 4.0, applications were either active, inactive, or not running. In iOS 4.0 and later, applications can also be running in the background or suspended. All of these transitions require a response from your application to ensure that it is doing the right thing. For example, a background application would need to stop updating its user interface. You provide the response to these transitions using the methods of the application delegate.
UIApplicationDelegate Protocol Reference Tasks
Launch time is also a particularly important point in an applications life cycle. In addition to the user launching an application by tapping its icon, an application can be launched in order to respond to a specific type of event. For example, it could be launched in response to an incoming push notification, it could be asked to open a file, or it could be launched to handle some background event that it had requested. In all of these cases, the options dictionary passed to the application:didFinishLaunchingWithOptions: (page 11) method provides information about the reason for the launch. In situations where the application is already running, the methods of the application delegate are called in response to key changes. Although the methods of this protocol are optional, most or all of them should be implemented. In iOS 6 and later, the app delegate also plays an important role in restoring and preserving the state of your application. The delegate tells UIKit whether state restoration and preservation should proceed at all. It may also provide view controller objects in some cases, acting as the last chance for your app to provide a view controller object during restoration. For more information about the launch cycle of an application and how you manage state transitions using the methods of the application delegate, see iOS App Programming Guide . For more information about the UIApplication singleton class, see UIApplication Class Reference .
Tasks
Monitoring App State Changes
application:willFinishLaunchingWithOptions:
(page 25) Tells the delegate that the launch process has begun but that state restoration has not yet occurred. (page 11) Tells the delegate that the launch process is almost done and the app is almost ready to run. (page 26) Tells the delegate that the application has become active. (page 32) Tells the delegate that the application is about to become inactive. (page 27) Tells the delegate that the application is now in the background. (page 31) Tells the delegate that the application is about to enter the foreground.
application:didFinishLaunchingWithOptions:
applicationDidBecomeActive:
applicationWillResignActive:
applicationDidEnterBackground:
applicationWillEnterForeground:
applicationWillTerminate:
(page 33) Tells the delegate when the application is about to terminate. (page 28) Tells the delegate when the application has finished launching.
applicationDidFinishLaunching:
Managing App State Restoration

application:shouldSaveApplicationState:
(page 19) Asks the delegate whether the apps state should be preserved. (page 19) Asks the delegate whether the apps saved state information should be restored. (page 21) Asks the delegate to provide the specified view controller.
application:shouldRestoreApplicationState:
application:viewControllerWithRestorationIdentifierPath:coder:
application:willEncodeRestorableStateWithCoder:
(page 24) Tells your delegate to save any high-level state information at the beginning of the state preservation process. (page 10) Tells your delegate to restore any high-level state information as part of the state restoration process.
application:didDecodeRestorableStateWithCoder:
Providing a Window for Storyboarding

window (page 8)
property
The window to use when presenting a storyboard.
Managing the Default Interface Orientations

application:supportedInterfaceOrientationsForWindow:
(page 20) Asks the delegate for the interface orientations to use for the view controllers in the specified window.
Opening a URL Resource

application:openURL:sourceApplication:annotation:
(page 17)
Asks the delegate to open a resource identified by URL.
application:handleOpenURL:
(page 16) Asks the delegate to open a resource identified by URL. (Deprecated. Use application:openURL:sourceApplication:annotation: (page 17) instead of this method to open URL resources.)
Managing Status Bar Changes

application:willChangeStatusBarOrientation:duration:
(page 23) Tells the delegate when the interface orientation of the status bar is about to change. (page 9) Tells the delegate when the interface orientation of the status bar has changed. (page 22) Tells the delegate when the frame of the status bar is about to change. (page 9) Tells the delegate when the frame of the status bar has changed.
application:didChangeStatusBarOrientation:
application:willChangeStatusBarFrame:
application:didChangeStatusBarFrame:
Responding to System Notifications

applicationDidReceiveMemoryWarning:
(page 29) Tells the delegate when the application receives a memory warning from the system. (page 31) Tells the delegate when there is a significant change in the time.
applicationSignificantTimeChange:
Handling Remote Notifications

application:didReceiveRemoteNotification:
(page 14) Tells the delegate that the running application received a remote notification. (page 15) Tells the delegate that the application successfully registered with Apple Push Service (APS). (page 11) Sent to the delegate when Apple Push Service cannot successfully complete the registration process.
application:didRegisterForRemoteNotificationsWithDeviceToken:
application:didFailToRegisterForRemoteNotificationsWithError:
UIApplicationDelegate Protocol Reference Properties
Handling Local Notifications

application:didReceiveLocalNotification:
(page 13) Sent to the delegate when a running application receives a local notification.
Responding to Content Protection Changes

applicationProtectedDataWillBecomeUnavailable:
(page 30) Tells the delegate that the protected files are about to become unavailable. (page 30) Tells the delegate that protected files are available now.
applicationProtectedDataDidBecomeAvailable:
Properties
window
The window to use when presenting a storyboard.
@property(nonatomic, retain) UIWindow *window
Discussion This property contains the window used to present the apps visual content on the devices main screen. Implementation of this property is required if your apps Info.plist file contains the UIMainStoryboardFile key. Fortunately, the Xcode project templates usually include a synthesized declaration of the property automatically for the app delegate. The default value of this synthesized property is nil, which causes the app to create a generic UIWindow object and assign it to the property. If you want to provide a custom window for your app, you must implement the getter method of this property and use it to create and return your custom window. For more information about the UIMainStoryboardFile in Information Property List Key Reference key, see Information Property List Key Reference . Availability Available in iOS 5.0 and later.
Related Sample Code CollectionView-Simple
UIApplicationDelegate Protocol Reference Instance Methods
Declared in
UIApplication.h
Instance Methods
Tells the delegate when the frame of the status bar has changed.
- (void)application:(UIApplication *)application
didChangeStatusBarFrame:(CGRect)oldStatusBarFrame
Parameters
application
The delegating application object.

oldStatusBarFrame
The previous frame of the status bar, in screen coordinates. Discussion After calling this method, the application also posts a
UIApplicationDidChangeStatusBarFrameNotification notification to give interested objects a chance
to respond to the change. Availability Available in iOS 2.0 and later. See Also
(page 22)
Declared in
UIApplication.h
application:didChangeStatusBarOrientation:
Tells the delegate when the interface orientation of the status bar has changed.
didChangeStatusBarOrientation:(UIInterfaceOrientation)oldStatusBarOrientation
Parameters
application

oldStatusBarOrientation
A constant that indicates the previous orientation of the applications user interface; see Monitoring App State Changes (page 5) for details. Discussion The delegate can get the current device orientation from the shared UIDevice object. After calling this method, the application also posts a
UIApplicationDidChangeStatusBarOrientationNotification notification to give interested objects
a chance to respond to the change. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
Tells your delegate to restore any high-level state information as part of the state restoration process.
didDecodeRestorableStateWithCoder:(NSCoder *)coder
Parameters
application

coder
The keyed archiver containing the apps previously saved state information. Discussion The state restoration system calls this method as the final step in the state restoration process. By the time this method is called, all other restorable objects will have been restored and put back into their previous state. You can use this method to read any high-level app data you saved in the application:willEncodeRestorableStateWithCoder: method and apply it to your app. Availability Available in iOS 6.0 and later.
10
See Also
(page 24)
Declared in
UIApplication.h
Sent to the delegate when Apple Push Service cannot successfully complete the registration process.
didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
Parameters
application
The application that initiated the remote-notification registration process.

error
An NSError object that encapsulates information why registration did not succeed. The application can choose to display this information to the user. Discussion The delegate receives this message after the registerForRemoteNotificationTypes: method of UIApplication is invoked and there is an error in the registration process. For more information about how to implement push notifications in your application, see Local and Push Notification Programming Guide . Availability Available in iOS 3.0 and later. See Also
(page 14) (page 15)
Declared in
UIApplication.h
Tells the delegate that the launch process is almost done and the app is almost ready to run.
11
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
Parameters
application

launchOptions
A dictionary indicating the reason the application was launched (if any). The contents of this dictionary may be empty in situations where the user launched the application directly. For information about the possible keys in this dictionary and how to handle them, see Launch Options Keys (page 34). Return Value NO if the application cannot handle the URL resource, otherwise return YES. The return value is ignored if the application is launched as a result of a remote notification. Discussion You should use this method (and the corresponding application:willFinishLaunchingWithOptions: (page 25) method) to complete your apps initialization and make any final tweaks. This method is called after state restoration has occurred but before your apps window and other UI have been presented. At some point after this method returns, the system calls another of your app delegates methods to move the app to the active (foreground) state or the background state. This method represents your last chance to process any keys in the launchOptions dictionary. If you did not evaluate the keys in your application:willFinishLaunchingWithOptions: method, you should look at them in this method and provide an appropriate response. Objects that are not the application delegate can access the same launchOptions dictionary values by observing the notification named UIApplicationDidFinishLaunchingNotification and accessing the notifications userInfo dictionary. That notification is sent shortly after this method returns. Important: For app initialization, it is highly recommended that you use this method and the application:willFinishLaunchingWithOptions: method and do not use the applicationDidFinishLaunching: method, which is intended only for apps that run on older versions of iOS. The return result from this method is combined with the return result from the application:willFinishLaunchingWithOptions: method to determine if a URL should be handled. If either method returns NO, the URL is not handled. If you do not implement one of the methods, only the return value of the implemented method is considered.
12
Availability Available in iOS 3.0 and later. See Also

(page 25)
(page 26) applicationDidEnterBackground: (page 27)

Declared in
UIApplication.h
application:didReceiveLocalNotification:
Sent to the delegate when a running application receives a local notification.
didReceiveLocalNotification:(UILocalNotification *)notification
Parameters
application
The application that received the local notification.

notification
A local notification that encapsulates details about the notification, potentially including custom data. Discussion Local notifications are similar to remote push notifications, but differ in that they are scheduled, displayed, and received entirely on the same device. An application can create and schedule a local notification, and the operating system then delivers it at the schedule date and time. If it delivers it when the application is not active in the foreground, it displays an alert, badges the application icon, or plays a soundwhatever is specified in the UILocalNotification object. If the application is running in the foreground, there is no alert, badging, or sound; instead, the application:didReceiveLocalNotification: method is called if the delegate implements it. The delegate can implement this method if it wants to be notified that a local notification occurred. For example, if the application is a calendar application, it can enumerate its list of calendar events to determine which ones have due dates that have transpired or are about to transpire soon. It can also reset the application icon badge number, and it can access any custom data in the local-notification objects userInfo dictionary. This method is called after the application:didFinishLaunchingWithOptions: (page 11) method (if that method is implemented).
13
Availability Available in iOS 4.0 and later. See Also

(page 14)
Declared in
UIApplication.h
Tells the delegate that the running application received a remote notification.
didReceiveRemoteNotification:(NSDictionary *)userInfo
Parameters
application
The application that received the remote notification.

userInfo
A dictionary that contains information related to the remote notification, potentially including a badge number for the application icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull. Discussion If the app is running and receives a remote notification, the app calls this method to process the notification. Your implementation of this method should use the notification to take an appropriate course of action. For example, you could use it as a signal to connect to a server and download the data waiting that is waiting for the app. The userInfo dictionary contains the aps key whose value is another dictionary. Although you should not need the information in the aps dictionary, you can retrieve its contents using the following keys:
alertThe value is either a string for the alert message or a dictionary with two keys: body and show-view. The value of the body key is a string containing the alert message and the value of the show-view key is a Boolean. If the value of the show-view key is false, the alerts View button is not
shown. The default is to show the View button which, if the user taps it, launches the application.
badgeA number indicating the quantity of data items to download from the provider. This number is
to be displayed on the application icon. The absence of a badge property indicates that any number currently badging the icon should be removed.
14
soundThe name of a sound file in the application bundle to play as an alert sound. If default is specified,
the default sound should be played. The userInfo dictionary may also have custom data defined by the provider according to the JSON schema. The properties for custom data should be specified at the same level as the aps dictionary. However, custom-defined properties should not be used for mass data transport because there is a strict size limit per notification (256 bytes) and delivery is not guaranteed. If the app is not running when a push notification arrives, the method launches the app and provides the appropriate information in the launch options dictionary. The app does not call this method to handle that push notification. Instead, your implementation of the application:willFinishLaunchingWithOptions: (page 25) or application:didFinishLaunchingWithOptions: (page 11) method needs to get the push notification payload data and respond appropriately. For more information about how to implement push notifications in your application, see Local and Push Notification Programming Guide . Availability Available in iOS 3.0 and later. See Also
application:didRegisterForRemoteNotificationsWithDeviceToken: application:didFailToRegisterForRemoteNotificationsWithError:
(page 15) (page 11)
Declared in
UIApplication.h
Tells the delegate that the application successfully registered with Apple Push Service (APS).
didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
Parameters
application
The application that initiated the remote-notification registration process.
15
deviceToken
A token that identifies the device to APS. The token is an opaque data type because that is the form that the provider needs to submit to the APS servers when it sends a notification to a device. The APS servers require a binary format for performance reasons. Note that the device token is different from the uniqueIdentifier property of UIDevice because, for security and privacy reasons, it must change when the device is wiped. Discussion The delegate receives this message after the registerForRemoteNotificationTypes: method of UIApplication is invoked and there is no error in the registration process. After receiving the device token, the application should connect with its provider and give the token to it. APS only pushes notifications to the applications device that are accompanied with this token. This method could be called in other rare circumstances, such as when the user launches an application after having restored a device from data that is not the devices backup data. In this exceptional case, the application wont know the new devices token until the user launches it. For more information about how to implement push notifications in your application, see Local and Push Notification Programming Guide . Availability Available in iOS 3.0 and later. See Also
(page 14) (page 11)
Declared in
UIApplication.h
application:handleOpenURL:
Asks the delegate to open a resource identified by URL. (Deprecated. Use application:openURL:sourceApplication:annotation: (page 17) instead of this method to open URL resources.)
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
Parameters
application
The application object.
16
url
A object representing a URL (Universal Resource Locator). See the appendix of iOS App Programming Guide for Apple-registered schemes for URLs. Return Value YES if the delegate successfully handled the request; NO if the attempt to handle the URL failed. Discussion If the delegate also implements the application:openURL:sourceApplication:annotation: (page 17) method, that method is called instead of this one. This method is not called if the delegate returns NO from both the application:willFinishLaunchingWithOptions: (page 25) and application:didFinishLaunchingWithOptions: (page 11) methods. (If only one of the two methods is implemented, its return value determines whether this method is called.) If your application implements the applicationDidFinishLaunching: (page 28) method instead of application:didFinishLaunchingWithOptions:, this method is called to open the specified URL after the application has been initialized. If a URL arrives while your application is suspended or running in the background, the system moves your application to the foreground prior to calling this method. There is no equivalent notification for this delegation method. Availability Available in iOS 2.0 and later. See Also
openURL: (UIApplication)
(page 25) application:didFinishLaunchingWithOptions: (page 11)

Declared in
UIApplication.h
application:openURL:sourceApplication:annotation:
Asks the delegate to open a resource identified by URL.
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
17
Parameters
application
The application object.

url
A object representing a URL (Universal Resource Locator). See Apple URL Scheme Reference for Apple-registered schemes for URLs.
sourceApplication
The bundle ID of the application that is requesting your application to open the URL (url).
annotation
A property-list object supplied by the source application to communicate information to the receiving application. Return Value YES if the delegate successfully handled the request; NO if the attempt to open the URL resource failed. Discussion Your implementation of this method should open the specified URL and update its user interface accordingly. The URL resource can be a network resource or a file to open. If your app had to be launched to open the URL, the app calls the application:willFinishLaunchingWithOptions: (page 25) and application:didFinishLaunchingWithOptions: (page 11) methods first, followed by this method. The return values of those methods can be used to prevent this method from being called. (If the application is already running, only this method is called.) If the URL refers to a file that was opened through a document interaction controller, the annotation parameter may contain additional data that the source application wanted to send along with the URL. The format of this data is defined by the application that sent it but the data must consist of objects that can be put into a property list. The app prefers calling this method over the application:handleOpenURL: (page 16) method. You should implement the application:handleOpenURL: method only if you need to support older versions of iOS. There is no matching notification for this method. Availability Available in iOS 4.2 and later. See Also
openURL: (UIApplication)
(page 11)
18
Declared in
UIApplication.h
Asks the delegate whether the apps saved state information should be restored.
shouldRestoreApplicationState:(NSCoder *)coder
Parameters
application

coder
The keyed archiver containing the apps previously saved state information. Return Value YES if the apps state should be restored or NO if it should not. Discussion Apps must implement this method and the application:shouldSaveApplicationState: (page 19) method for state preservation to occur. In addition, your implementation of this method must return YES each time UIKit tries to restore the state of your app. You can use the information in the provided coder object to decide whether or not to proceed with state restoration. For example, you might return NO if the data in the coder is from a different version of your app and cannot be effectively restored to the current version. Availability Available in iOS 6.0 and later. See Also
(page 19)
Declared in
UIApplication.h
Asks the delegate whether the apps state should be preserved.
- (BOOL)application:(UIApplication *)application shouldSaveApplicationState:(NSCoder
*)coder
19
Parameters
application

coder
The keyed archiver into which you can put high-level state information. Return Value YES if the apps state should be preserved or NO if it should not. Discussion Apps must implement this method and the application:shouldRestoreApplicationState: (page 19) method for state preservation to occur. In addition, your implementation of this method must return YES each time UIKit tries to preserve the state of your app. You can return NO to disable state preservation temporarily. For example, during testing, you could disable state preservation to test specific code paths. You can add version information or any other contextual data to the provided coder object as needed. During restoration, you can use that information to help decide whether or not to proceed with restoring your app to its previous state. Availability Available in iOS 6.0 and later. See Also
(page 19)
Declared in
UIApplication.h
application:supportedInterfaceOrientationsForWindow:
Asks the delegate for the interface orientations to use for the view controllers in the specified window.
- (NSUInteger)application:(UIApplication *)application
supportedInterfaceOrientationsForWindow:(UIWindow *)window
Parameters
application

window
The window whose interface orientations you want to retrieve.
20
Return Value A bit mask of the UIInterfaceOrientationMask constants that indicate the orientations to use for the view controllers. Discussion This method returns the interface orientations to use for any view controllers that do not specify their own explicitly. The orientations returned by this method are used if the view controller does not override the supportedInterfaceOrientations or shouldAutorotateToInterfaceOrientation: method. If you do not implement this method, the application uses the values in the UIInterfaceOrientation key of the apps Info.plist as the default interface orientations. Availability Available in iOS 6.0 and later. Declared in
UIApplication.h
application:viewControllerWithRestorationIdentifierPath:coder:
Asks the delegate to provide the specified view controller.
- (UIViewController *)application:(UIApplication *)application
viewControllerWithRestorationIdentifierPath:(NSArray *)identifierComponents coder:(NSCoder *)coder
Parameters
application

identifierComponents
An array of NSString objects corresponding to the restoration identifiers of the desired view controller and all of its ancestors in the view controller hierarchy. The last value in the array is the restoration identifier of the desired view controller. Earlier entries represent the restoration identifiers of its ancestors.
coder
The keyed archiver containing the apps saved state information. Return Value The view controller object to use or nil if you do not want to restore this view controller or its children. For view controllers that are children of a common parent, returning nil for one child may prevent others from being restored too. For example, in a navigation controller, returning nil for a view controller in the middle of the navigation stack prevents the restoration of view controllers higher up on the stack.
21
Discussion During state restoration, when UIKit encounters a view controller without a restoration class, it calls this method to ask for the corresponding view controller object. Your implementation of this method should create (or find) the corresponding view controller object and return it. If you determine that it does not make sense to display this view controller now, you may return nil to prevent that view controller from being added to your interface as part of the restoration process. You use the strings in the identifierComponents parameter to identify the view controller being requested. The view controllers in your app form a hierarchy. At the root of this hierarchy is the windows root view controller, which itself may present or embed other view controllers. Those presented or embedded view controllers may themselves present and embed other view controllers. The result is a hierarchy of view controller relationships, with each presented or embedded view controller becoming a child of the view controller that presented or embedded it. The strings in the identifierComponents array identify the path through this hierarchy from the root view controller to the desired view controller. It is not always necessary to create a new view controller object in your implementation of this method. You can also return an existing view controller object that was created by another means. For example, you would always return the existing view controllers loaded from your apps main storyboard file rather than create new objects. Your implementation of this method may use any data in the provided coder to assist in the restoration process. However, you usually do not need to restore the entire state of the view controller at this point. During a later pass, view controllers that define a decodeRestorableStateWithCoder: method are normally given a chance to restore their state form the same coder object. Similarly, the app delegate itself has a application:didDecodeRestorableStateWithCoder: (page 10) method that you can use to restore app-level state information. Note: If you return an object whose class does not match the class of the originally preserved object, or whose class is not a direct subclass of the original, the restoration system does not call the decodeRestorableStateWithCoder: method of the view controller.
Availability Available in iOS 6.0 and later. Declared in

UIApplication.h
Tells the delegate when the frame of the status bar is about to change.
22
willChangeStatusBarFrame:(CGRect)newStatusBarFrame
Parameters
application

newStatusBarFrame
The changed frame of the status bar, in screen coordinates. Discussion The application calls this method when it receives a setStatusBarOrientation:animated: message and is about to change the interface orientation. After calling this method, the application also posts a
UIApplicationWillChangeStatusBarFrameNotification notification to give interested objects a
chance to respond to the change. Availability Available in iOS 2.0 and later. See Also
(page 9)
Declared in
UIApplication.h
application:willChangeStatusBarOrientation:duration:
Tells the delegate when the interface orientation of the status bar is about to change.
willChangeStatusBarOrientation:(UIInterfaceOrientation)newStatusBarOrientation duration:(NSTimeInterval)duration
Parameters
application

newStatusBarOrientation
A constant that indicates the new orientation of the applications user interface; see Monitoring App State Changes (page 5) for details.
duration
The duration of the animation to the new orientation, in seconds.
23
Discussion The delegate typically implements this method to prepare its windows and views for the new orientation. The delegate can get the current device orientation from the shared UIDevice object. After calling this method, the application also posts a
UIApplicationWillChangeStatusBarOrientationNotification notification to give interested objects
a chance to respond to the change. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
Tells your delegate to save any high-level state information at the beginning of the state preservation process.
willEncodeRestorableStateWithCoder:(NSCoder *)coder
Parameters
application

coder
The keyed archiver in which to write any state information. Discussion The state preservation system calls this method at the beginning of the preservation process. This is your opportunity to add any app-level information to state information. For example, you might use this method to write version information or the high-level configuration of your app.
24
Important: This method is not a substitute for saving your apps data structures persistently to disk. You should continue to save your apps actual data to iCloud or the local file system using existing techniques. This method is intended only for saving configuration state or other information related to your apps user interface. You should consider the data in the coder as purgeable and be prepared for it to be unavailable during subsequent launches. Your implementation of this method can encode restorable view and view controller objects that it needs to reference. Encoding a restorable view or view controller writes that objects restoration identifier to the coder. (That identifier is used during the decode process to locate the new version of the object.) If the view or view controller defines a encodeRestorableStateWithCoder: method, that method is also called at some point so that the object can encode its own state. Apart from views and view controllers, other objects follow the normal serialization process and must adopt the NSCoding protocol before they can be encoded. Encoding such objects embeds the objects contents in the archive directly. During the decode process, a new object is created and initialized with the data from the archive. Availability Available in iOS 6.0 and later. See Also
(page 10)
Declared in
UIApplication.h
Tells the delegate that the launch process has begun but that state restoration has not yet occurred.
willFinishLaunchingWithOptions:(NSDictionary *)launchOptions
Parameters
application

launchOptions
A dictionary indicating the reason the application was launched (if any). The contents of this dictionary may be empty in situations where the user launched the application directly. For information about the possible keys in this dictionary and how to handle them, see Launch Options Keys (page 34).
25
Return Value NO if the application cannot handle the URL resource, otherwise return YES. The return value is ignored if the application is launched as a result of a remote notification. Discussion You should use this method (and the corresponding application:didFinishLaunchingWithOptions: (page 11) method) to initialize your application and prepare it to run. This method is called after your application has been launched and its main storyboard or nib file has been loaded, but before your apps state has been restored. At the time this method is called, your application is in the inactive state. If your application was launched by the system for a specific reason, the launchOptions dictionary contains data indicating the reason for the launch. Your app should look in this dictionary for any keys that correspond to features your app supports. If the given key is present, you should provide an appropriate response. If your app was launched to open a URL, you should examine the value of the UIApplicationLaunchOptionsURLKey (page 34) key and return a Boolean value indicating whether your app can actually open the URL. You should not try to open the URL in this method. Instead, implement the application:openURL:sourceApplication:annotation: (page 17) method in your app delegate and use that method to open the URL. The return result from this method is combined with the return result from the application:didFinishLaunchingWithOptions: method to determine if a URL should be handled. If either method returns NO, the URL is not handled. If you do not implement one of the methods, only the return value of the implemented method is considered. Availability Available in iOS 6.0 and later. See Also
(page 11)
Declared in
UIApplication.h
Tells the delegate that the application has become active.
- (void)applicationDidBecomeActive:(UIApplication *)application
26
Parameters
application
The singleton application instance. Discussion This method is called to let your application know that it moved from the inactive to active state. This can occur because your application was launched by the user or the system. Applications can also return to the active state if the user chooses to ignore an interruption (such as an incoming phone call or SMS message) that sent the application temporarily to the inactive state. You should use this method to restart any tasks that were paused (or not yet started) while the application was inactive. For example, you could use it to restart timers or throttle up OpenGL ES frame rates. If your application was previously in the background, you could also use it to refresh your applications user interface. After calling this method, the application also posts a UIApplicationDidBecomeActiveNotification notification to give interested objects a chance to respond to the transition. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
Tells the delegate that the application is now in the background.
- (void)applicationDidEnterBackground:(UIApplication *)application
Parameters
application
The singleton application instance. Discussion In iOS 4.0 and later, this method is called instead of the applicationWillTerminate: method when the user quits an application that supports background execution. You should use this method to release shared resources, save user data, invalidate timers, and store enough application state information to restore your application to its current state in case it is terminated later. You should also disable updates to your applications user interface and avoid using some types of shared system resources (such as the users contacts database). It is also imperative that you avoid using OpenGL ES in the background.
27
Your implementation of this method has approximately five seconds to perform any tasks and return. If you need additional time to perform any final tasks, you can request additional execution time from the system by calling beginBackgroundTaskWithExpirationHandler:. In practice, you should return from applicationDidEnterBackground: as quickly as possible. If the method does not return before time runs out your application is terminated and purged from memory. You should perform any tasks relating to adjusting your user interface before this method exits but other tasks (such as saving state) should be moved to a concurrent dispatch queue or secondary thread as needed. Because it's likely any background tasks you start in applicationDidEnterBackground: will not run until after that method exits, you should request additional background execution time before starting those tasks. In other words, first call beginBackgroundTaskWithExpirationHandler: and then run the task on a dispatch queue or secondary thread. The application also posts a UIApplicationDidEnterBackgroundNotification notification around the same time it calls this method to give interested objects a chance to respond to the transition. For more information about how to transition gracefully to the background, and for information about how to start background tasks at quit time, see iOS App Programming Guide . Availability Available in iOS 4.0 and later. Declared in
UIApplication.h
applicationDidFinishLaunching:
Tells the delegate when the application has finished launching.
- (void)applicationDidFinishLaunching:(UIApplication *)application
Parameters
application
The delegating application object. Discussion This method is used in earlier versions of iOS to initialize the app and prepare it to run. In iOS 3.0 and later, you should use the application:didFinishLaunchingWithOptions: (page 11) instead. In iOS 6.0 and later, you may also use the application:willFinishLaunchingWithOptions: (page 25) method to initialize your app.
28
Your implementation of this method should create your applications user interface and initialize the applications data structures. If your application persists its state between launches, you would also use this method to restore your application to its previous state. After calling this method, the application also posts a UIApplicationDidFinishLaunchingNotification notification to give interested objects a chance to respond to the initialization cycle. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
applicationDidReceiveMemoryWarning:
Tells the delegate when the application receives a memory warning from the system.
- (void)applicationDidReceiveMemoryWarning:(UIApplication *)application
Parameters
application
The delegating application object. Discussion Your implementation of this method should free up as much memory as possible by purging cached data objects that can be recreated (or reloaded from disk) later. You use this method in conjunction with the didReceiveMemoryWarning of the UIViewController class and the UIApplicationDidReceiveMemoryWarningNotification notification to release memory throughout your application. It is strongly recommended that you implement this method. If your application does not release enough memory during low-memory conditions, the system may terminate it outright. Availability Available in iOS 2.0 and later. See Also
didReceiveMemoryWarning (UIViewController) UIApplicationDidReceiveMemoryWarningNotification
Declared in
UIApplication.h
29
applicationProtectedDataDidBecomeAvailable:
Tells the delegate that protected files are available now.
- (void)applicationProtectedDataDidBecomeAvailable:(UIApplication *)application
Parameters
application
The delegating application object. Discussion On a device that uses content protection, protected files are stored in an encrypted form and made available only at certain times, usually when the device is unlocked. This notification lets your application know that the device is now unlocked and that you may access certain types of protected files again. Availability Available in iOS 4.0 and later. Declared in
UIApplication.h
applicationProtectedDataWillBecomeUnavailable:
Tells the delegate that the protected files are about to become unavailable.
- (void)applicationProtectedDataWillBecomeUnavailable:(UIApplication *)application
Parameters
application
The delegating application object. Discussion On a device that uses content protection, protected files are stored in an encrypted form and made available only at certain times, usually when the device is unlocked. This notification lets your application know that the device is about to be locked and that any protected files it is currently accessing might become unavailable shortly. If your application is currently accessing a protected file, you can use this method to release any references to that file. Although it is not an error to access the file while the device is locked, any attempts to do so will fail. Therefore, if your application depends on the file, you might want to take steps to avoid using that file while the device is locked.
30
Availability Available in iOS 4.0 and later. Declared in

UIApplication.h
applicationSignificantTimeChange:
Tells the delegate when there is a significant change in the time.
- (void)applicationSignificantTimeChange:(UIApplication *)application
Parameters
application
The delegating application object. Discussion Examples of significant time changes include the arrival of midnight, an update of the time by a carrier, and the change to daylight savings time. The delegate can implement this method to adjust any object of the application that displays time or is sensitive to time changes. Prior to calling this method, the application also posts a
UIApplicationSignificantTimeChangeNotification notification to give interested objects a chance
to respond to the change. If your application is currently suspended, this message is queued until your application returns to the foreground, at which point it is delivered. If multiple time changes occur, only the most recent one is delivered. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
applicationWillEnterForeground:
Tells the delegate that the application is about to enter the foreground.
- (void)applicationWillEnterForeground:(UIApplication *)application
Parameters
application
The singleton application instance.
31
Discussion In iOS 4.0 and later, this method is called as part of the transition from the background to the active state. You can use this method to undo many of the changes you made to your application upon entering the background. The call to this method is invariably followed by a call to the applicationDidBecomeActive: (page 26) method, which then moves the application from the inactive to the active state. The application also posts a UIApplicationWillEnterForegroundNotification notification shortly before calling this method to give interested objects a chance to respond to the transition. Availability Available in iOS 4.0 and later. Declared in
UIApplication.h
applicationWillResignActive:
Tells the delegate that the application is about to become inactive.
- (void)applicationWillResignActive:(UIApplication *)application
Parameters
application
The singleton application instance. Discussion This method is called to let your application know that it is about to move from the active to inactive state. This can occur for certain types of temporary interruptions (such as an incoming phone call or SMS message) or when the user quits the application and it begins the transition to the background state. An application in the inactive state continues to run but does not dispatch incoming events to responders. You should use this method to pause ongoing tasks, disable timers, and throttle down OpenGL ES frame rates. Games should use this method to pause the game. An application in the inactive state should do minimal work while it waits to transition to either the active or background state. After calling this method, the application also posts a UIApplicationWillResignActiveNotification notification to give interested objects a chance to respond to the transition. Availability Available in iOS 2.0 and later. Declared in
UIApplication.h
32
applicationWillTerminate:
Tells the delegate when the application is about to terminate.
- (void)applicationWillTerminate:(UIApplication *)application
Parameters
application
The delegating application object. Discussion This method lets your application know that it is about to be terminated and purged from memory entirely. You should use this method to perform any final clean-up tasks for your application, such as freeing shared resources, saving user data, and invalidating timers. Your implementation of this method has approximately five seconds to perform any tasks and return. If the method does not return before time expires, the system may kill the process altogether. For applications that do not support background execution or are linked against iOS 3.x or earlier, this method is always called when the user quits the application. For applications that support background execution, this method is generally not called when the user quits the application because the application simply moves to the background in that case. However, this method may be called in situations where the application is running in the background (not suspended) and the system needs to terminate it for some reason. After calling this method, the application also posts a UIApplicationWillTerminateNotification notification to give interested objects a chance to respond to the transition. Availability Available in iOS 2.0 and later. See Also
(page 27) (page 11)
Declared in
UIApplication.h
33
UIApplicationDelegate Protocol Reference Constants
Constants
Launch Options Keys
Keys used to access values in the launch options dictionary passed to the application:willFinishLaunchingWithOptions: (page 25) and application:didFinishLaunchingWithOptions: (page 11) methods of the application delegate.
NSString NSString NSString NSString NSString NSString NSString
*const *const *const *const *const *const *const
UIApplicationLaunchOptionsURLKey; UIApplicationLaunchOptionsSourceApplicationKey; UIApplicationLaunchOptionsRemoteNotificationKey; UIApplicationLaunchOptionsAnnotationKey; UIApplicationLaunchOptionsLocalNotificationKey; UIApplicationLaunchOptionsLocationKey; UIApplicationLaunchOptionsNewsstandDownloadsKey;
Constants
UIApplicationLaunchOptionsURLKey
The presence of this key indicates that the application was launched in order to open a URL. The value of this key is an NSURL object containing the URL to open. This key is also used to access the same value in the userInfo dictionary of the notification named UIApplicationDidFinishLaunchingNotification. Available in iOS 3.0 and later. Declared in UIApplication.h.
UIApplicationLaunchOptionsSourceApplicationKey
The presence of this key identifies the app that requested the launch of your app. The value of this key is an NSString object that represents the bundle ID of the app that made the request. This key is also used to access the same value in the userInfo dictionary of the notification named UIApplicationDidFinishLaunchingNotification. Available in iOS 3.0 and later. Declared in UIApplication.h.
34
UIApplicationLaunchOptionsRemoteNotificationKey
The presence of this key indicates that a remote notification is available for the app to process. The value of this key is an NSDictionary containing the payload of the remote notification. See the description of application:didReceiveRemoteNotification: (page 14) for further information about handling remote notifications. This key is also used to access the same value in the userInfo dictionary of the notification named UIApplicationDidFinishLaunchingNotification. Available in iOS 3.0 and later. Declared in UIApplication.h.
UIApplicationLaunchOptionsAnnotationKey
The presence of this key indicates that custom data was provided by the app that requested the opening of the URL. The value of this key is a property-list object containing the custom data. The same object is also passed to the annotation parameter of the application:openURL:sourceApplication:annotation: (page 17) method. The contents of this property-list object are specific to the app that made the request. Available in iOS 3.2 and later. Declared in UIApplication.h.
UIApplicationLaunchOptionsLocalNotificationKey
The presence of this key indicates that a local notification is available for the app to process. The value of this key is the UILocalNotification object that was triggered. For additional information about handling local notifications, see the application:didReceiveLocalNotification: (page 13) method. This key is also used to access the same value in the userInfo dictionary of the notification named UIApplicationDidFinishLaunchingNotification. Available in iOS 4.0 and later. Declared in UIApplication.h.
UIApplicationLaunchOptionsLocationKey
The presence of this key indicates that the application was launched in response to an incoming location event. The value of this key is an NSNumber object containing a Boolean value. You should use the presence of this key as a signal to create a CLLocationManager object and start location services again. Location data is delivered only to the location manager delegate and not using this key. Available in iOS 4.0 and later. Declared in UIApplication.h.
35
UIApplicationLaunchOptionsNewsstandDownloadsKey
The presence of this key indicates that newly downloaded Newsstand assets are available for your app. The value of this key is an array of string identifiers that identify the NKAssetDownload objects corresponding to the assets. Although you can use the identifiers for cross-checking purposes, you should obtain the definitive array of NKAssetDownload objects (representing asset downloads in progress or in error) through the downloadingAssets property of the NKLibrary object representing the Newsstand applications library. Available in iOS 5.0 and later. Declared in UIApplication.h.
App-Specific State Restoration Keys

The following keys are used when reading and writing state restoration data.
NSString *const UIApplicationStateRestorationUserInterfaceIdiomKey; NSString *const UIApplicationStateRestorationBundleVersionKey;
Constants
UIApplicationStateRestorationUserInterfaceIdiomKey
The value of this key is an NSNumber object containing one of the values for the UIUserInterfaceIdiom enum. This value reflects whether the interface that was saved was targeting the iPad or iPhone idiom. Available in iOS 6.0 and later. Declared in UIStateRestoration.h.
UIApplicationStateRestorationBundleVersionKey
The value of this key is an NSString object that identifies the version of your app (as obtained from the CFBundleVersion key of your apps Info.plist file) was was present when the state information was saved. You can use the value of this key to help make choices about how to proceed during state restoration. For example, if the key indicates that the state is associated with an older version of your app, you might want to avoid restoring the previous state altogether or modify the restoration process more significantly. Available in iOS 6.0 and later. Declared in UIStateRestoration.h.
36
Document Revision History
This table describes the changes to UIApplicationDelegate Protocol Reference .
Date 2012-09-19 2011-10-12 2010-11-15
Notes Added methods related to state preservation and restoration. Describes the window property added in iOS 5.0. Describes the application:openURL:sourceApplication:annotation: method, which was introduced in iOS 4.2. Improved description of launchOptions parameter of application:didFinishLaunchingWithOptions:. Updated for iOS 4.0 Marked all protocols as optional. Corrected API symbols that link to descriptions in reference. Added remote-notification methods. Added link to companion document and noted which notifications are related to each delegate method. New document that describes the protocol implemented by the delegate of a UIApplication object to respond to various system events.
2010-08-03
2010-05-11 2009-11-17 2009-05-19 2009-03-08 2008-09-09
2008-07-03
37
Apple Inc. 2012 Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apples copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, iPad, iPhone, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries. iAd and iCloud are service marks of Apple Inc., registered in the U.S. and other countries. OpenGL is a registered trademark of Silicon Graphics, Inc. iOS is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license.
Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.

UIApplicationDelegate Protocol

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

UIApplicationDelegate Protocol

Încărcat de

Drepturi de autor:

Formate disponibile

UIApplicationDelegate Protocol Reference

UIApplicationDelegate Protocol Reference 4

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

Document Revision History 37

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference

Conforms to Framework Availability Declared in

NSObject /System/Library/Frameworks/UIKit.framework Available in iOS 2.0 and later. UIApplication.h UIStateRestoration.h

Related sample code

iAdSuite ScrollViewSuite SquareCam TableViewSuite Touches

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Tasks

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Tasks

Managing App State Restoration

Providing a Window for Storyboarding

The window to use when presenting a storyboard.

Managing the Default Interface Orientations

Opening a URL Resource

Asks the delegate to open a resource identified by URL.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Tasks

Managing Status Bar Changes

Responding to System Notifications

Handling Remote Notifications

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Properties

Handling Local Notifications

Responding to Content Protection Changes

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

The delegating application object.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

The delegating application object.

The delegating application object.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

The application that initiated the remote-notification registration process.

(page 14) (page 15)

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

The delegating application object.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

Availability Available in iOS 3.0 and later. See Also

(page 26) applicationDidEnterBackground: (page 27)

The application that received the local notification.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

Availability Available in iOS 4.0 and later. See Also

The application that received the remote notification.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

(page 15) (page 11)

The application that initiated the remote-notification registration process.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

(page 14) (page 11)

The application object.

2012-09-19 | 2012 Apple Inc. All Rights Reserved.

UIApplicationDelegate Protocol Reference Instance Methods

(page 25) application:didFinishLaunchingWithOptions: (page 11)

sourceApplication:(NSString *)sourceApplication annotation:(id)annotation

viewControllerWithRestorationIdentifierPath:(NSArray )identifierComponents coder:(NSCoder )coder

const const const const const const *const

NSString const UIApplicationStateRestorationUserInterfaceIdiomKey; NSString const UIApplicationStateRestorationBundleVersionKey;