UIApplicationDelegate Protocol

UIApplicationDelegate Protocol Reference

Contents

UIApplicationDelegate Protocol Reference 4Overview 4Tasks 5

Monitoring App State Changes 5Managing App State Restoration 6Providing a Window for Storyboarding 6Managing the Default Interface Orientations 6Opening a URL Resource 6Managing Status Bar Changes 7Responding to System Notifications 7Handling Remote Notifications 7Handling Local Notifications 8Responding to Content Protection Changes 8

Properties 8window 8

Instance Methods 9application:didChangeStatusBarFrame: 9application:didChangeStatusBarOrientation: 9application:didDecodeRestorableStateWithCoder: 10application:didFailToRegisterForRemoteNotificationsWithError: 11application:didFinishLaunchingWithOptions: 11application:didReceiveLocalNotification: 13application:didReceiveRemoteNotification: 14application:didRegisterForRemoteNotificationsWithDeviceToken: 15application:handleOpenURL: 16application:openURL:sourceApplication:annotation: 17application:shouldRestoreApplicationState: 19application:shouldSaveApplicationState: 19application:supportedInterfaceOrientationsForWindow: 20application:viewControllerWithRestorationIdentifierPath:coder: 21application:willChangeStatusBarFrame: 22application:willChangeStatusBarOrientation:duration: 23application:willEncodeRestorableStateWithCoder: 24application:willFinishLaunchingWithOptions: 25

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

2

applicationDidBecomeActive: 26applicationDidEnterBackground: 27applicationDidFinishLaunching: 28applicationDidReceiveMemoryWarning: 29applicationProtectedDataDidBecomeAvailable: 30applicationProtectedDataWillBecomeUnavailable: 30applicationSignificantTimeChange: 31applicationWillEnterForeground: 31applicationWillResignActive: 32applicationWillTerminate: 33

Constants 34Launch Options Keys 34App-Specific State Restoration Keys 36

Document Revision History 37


3

Contents

Conforms to NSObject

Framework /System/Library/Frameworks/UIKit.framework

Availability Available in iOS 2.0 and later.

Declared in UIApplication.h

UIStateRestoration.h

Companion guides iOS App Programming Guide

Local and Push Notification Programming Guide

Related sample code iAdSuite

ScrollViewSuite

SquareCam

TableViewSuite

Touches

OverviewThe UIApplicationDelegate protocol declares methods that are implemented by the delegate of thesingleton UIApplication object. These methods provide you with information about key events in anapplication’s execution such as when it finished launching, when it is about to be terminated, when memoryis low, and when important changes occur. Implementing these methods gives you a chance to respond tothese system events and respond appropriately.

One of the main jobs of the application delegate is to track the state transitions the application goes throughwhile 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 responsefrom your application to ensure that it is doing the right thing. For example, a background application wouldneed to stop updating its user interface. You provide the response to these transitions using the methods ofthe application delegate.


4

UIApplicationDelegate Protocol Reference

Launch time is also a particularly important point in an application’s life cycle. In addition to the user launchingan application by tapping its icon, an application can be launched in order to respond to a specific type ofevent. For example, it could be launched in response to an incoming push notification, it could be asked toopen a file, or it could be launched to handle some background event that it had requested. In all of thesecases, the options dictionary passed to the application:didFinishLaunchingWithOptions: (page 11) methodprovides information about the reason for the launch.

In situations where the application is already running, the methods of the application delegate are called inresponse to key changes. Although the methods of this protocol are optional, most or all of them should beimplemented.

In iOS 6 and later, the app delegate also plays an important role in restoring and preserving the state of yourapplication. The delegate tells UIKit whether state restoration and preservation should proceed at all. It mayalso provide view controller objects in some cases, acting as the last chance for your app to provide a viewcontroller object during restoration.

For more information about the launch cycle of an application and how you manage state transitions usingthe methods of the application delegate, see iOS App Programming Guide . For more information about theUIApplication 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.

– application:didFinishLaunchingWithOptions: (page 11)Tells the delegate that the launch process is almost done and the app is almost ready to run.

– applicationDidBecomeActive: (page 26)Tells the delegate that the application has become active.

– applicationWillResignActive: (page 32)Tells the delegate that the application is about to become inactive.

– applicationDidEnterBackground: (page 27)Tells the delegate that the application is now in the background.

– applicationWillEnterForeground: (page 31)Tells the delegate that the application is about to enter the foreground.

UIApplicationDelegate Protocol ReferenceTasks


5

– applicationWillTerminate: (page 33)Tells the delegate when the application is about to terminate.

– applicationDidFinishLaunching: (page 28)Tells the delegate when the application has finished launching.

Managing App State Restoration

– application:shouldSaveApplicationState: (page 19)Asks the delegate whether the app’s state should be preserved.

– application:shouldRestoreApplicationState: (page 19)Asks the delegate whether the app’s saved state information should be restored.

– application:viewControllerWithRestorationIdentifierPath:coder: (page 21)Asks the delegate to provide the specified view controller.

– application:willEncodeRestorableStateWithCoder: (page 24)Tells your delegate to save any high-level state information at the beginning of the state preservationprocess.

– application:didDecodeRestorableStateWithCoder: (page 10)Tells your delegate to restore any high-level state information as part of the state restoration process.

Providing a Window for Storyboarding

window (page 8) propertyThe 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.



6

– application:handleOpenURL: (page 16)Asks the delegate to open a resource identified by URL. (Deprecated. Useapplication:openURL:sourceApplication:annotation: (page 17) instead of this method to open URLresources.)

Managing Status Bar Changes

– application:willChangeStatusBarOrientation:duration: (page 23)Tells the delegate when the interface orientation of the status bar is about to change.

– application:didChangeStatusBarOrientation: (page 9)Tells the delegate when the interface orientation of the status bar has changed.

– application:willChangeStatusBarFrame: (page 22)Tells the delegate when the frame of the status bar is about to change.

– application:didChangeStatusBarFrame: (page 9)Tells the delegate when the frame of the status bar has changed.

Responding to System Notifications

– applicationDidReceiveMemoryWarning: (page 29)Tells the delegate when the application receives a memory warning from the system.

– applicationSignificantTimeChange: (page 31)Tells the delegate when there is a significant change in the time.

Handling Remote Notifications

– application:didReceiveRemoteNotification: (page 14)Tells the delegate that the running application received a remote notification.

– application:didRegisterForRemoteNotificationsWithDeviceToken: (page 15)Tells the delegate that the application successfully registered with Apple Push Service (APS).

– application:didFailToRegisterForRemoteNotificationsWithError: (page 11)Sent to the delegate when Apple Push Service cannot successfully complete the registration process.



7

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.

– applicationProtectedDataDidBecomeAvailable: (page 30)Tells the delegate that protected files are available now.

Properties

window

The window to use when presenting a storyboard.

@property(nonatomic, retain) UIWindow *window

DiscussionThis property contains the window used to present the app’s visual content on the device’s main screen.

Implementation of this property is required if your app’sInfo.plist file contains theUIMainStoryboardFilekey. Fortunately, the Xcode project templates usually include a synthesized declaration of the propertyautomatically for the app delegate. The default value of this synthesized property is nil, which causes theapp to create a generic UIWindow object and assign it to the property. If you want to provide a custom windowfor your app, you must implement the getter method of this property and use it to create and return yourcustom window.

For more information about the “UIMainStoryboardFile” in Information Property List Key Reference key, seeInformation Property List Key Reference .

AvailabilityAvailable in iOS 5.0 and later.

Related Sample CodeCollectionView-Simple

UIApplicationDelegate Protocol ReferenceProperties


8

Declared inUIApplication.h

Instance Methods

application:didChangeStatusBarFrame:

Tells the delegate when the frame of the status bar has changed.

- (void)application:(UIApplication *)applicationdidChangeStatusBarFrame:(CGRect)oldStatusBarFrame

Parametersapplication

The delegating application object.

oldStatusBarFrameThe previous frame of the status bar, in screen coordinates.

DiscussionAfter calling this method, the application also posts aUIApplicationDidChangeStatusBarFrameNotification notification to give interested objects a chanceto respond to the change.


See Also– application:willChangeStatusBarFrame: (page 22)


application:didChangeStatusBarOrientation:

Tells the delegate when the interface orientation of the status bar has changed.

- (void)application:(UIApplication *)applicationdidChangeStatusBarOrientation:(UIInterfaceOrientation)oldStatusBarOrientation

UIApplicationDelegate Protocol ReferenceInstance Methods


9



oldStatusBarOrientationA constant that indicates the previous orientation of the application’s user interface; see “MonitoringApp State Changes” (page 5) for details.

DiscussionThe delegate can get the current device orientation from the shared UIDevice object.

After calling this method, the application also posts aUIApplicationDidChangeStatusBarOrientationNotification notification to give interested objectsa chance to respond to the change.



application:didDecodeRestorableStateWithCoder:

Tells your delegate to restore any high-level state information as part of the state restoration process.

- (void)application:(UIApplication *)applicationdidDecodeRestorableStateWithCoder:(NSCoder *)coder



coderThe keyed archiver containing the app’s previously saved state information.

DiscussionThe state restoration system calls this method as the final step in the state restoration process. By the time thismethod 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 theapplication:willEncodeRestorableStateWithCoder: method and apply it to your app.




10

See Also– application:willEncodeRestorableStateWithCoder: (page 24)


application:didFailToRegisterForRemoteNotificationsWithError:

Sent to the delegate when Apple Push Service cannot successfully complete the registration process.

- (void)application:(UIApplication *)applicationdidFailToRegisterForRemoteNotificationsWithError:(NSError *)error


The application that initiated the remote-notification registration process.

errorAn NSError object that encapsulates information why registration did not succeed. The application canchoose to display this information to the user.

DiscussionThe delegate receives this message after the registerForRemoteNotificationTypes: method ofUIApplication 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 PushNotification Programming Guide .


See Also– application:didReceiveRemoteNotification: (page 14)– application:didRegisterForRemoteNotificationsWithDeviceToken: (page 15)


application:didFinishLaunchingWithOptions:

Tells the delegate that the launch process is almost done and the app is almost ready to run.



11

- (BOOL)application:(UIApplication *)applicationdidFinishLaunchingWithOptions:(NSDictionary *)launchOptions



launchOptionsA dictionary indicating the reason the application was launched (if any). The contents of this dictionarymay be empty in situations where the user launched the application directly. For information about thepossible keys in this dictionary and how to handle them, see “Launch Options Keys” (page 34).

Return ValueNO if the application cannot handle the URL resource, otherwise return YES. The return value is ignored if theapplication is launched as a result of a remote notification.

DiscussionYou should use this method (and the corresponding application:willFinishLaunchingWithOptions: (page

25) method) to complete your app’s initialization and make any final tweaks. This method is called after staterestoration has occurred but before your app’s window and other UI have been presented. At some point afterthis method returns, the system calls another of your app delegate’s 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 notevaluate the keys in your application:willFinishLaunchingWithOptions: method, you should lookat them in this method and provide an appropriate response.

Objects that are not the application delegate can access the same launchOptions dictionary values byobserving the notification named UIApplicationDidFinishLaunchingNotification and accessing thenotification’s 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 theapplication:willFinishLaunchingWithOptions: method and do not use theapplicationDidFinishLaunching:method, which is intended only for apps that run on older versionsof iOS.

The return result from this method is combined with the return result from theapplication:willFinishLaunchingWithOptions: method to determine if a URL should be handled. Ifeither method returns NO, the URL is not handled. If you do not implement one of the methods, only the returnvalue of the implemented method is considered.



12


See Also– application:willFinishLaunchingWithOptions: (page 25)– applicationDidBecomeActive: (page 26)– applicationDidEnterBackground: (page 27)


application:didReceiveLocalNotification:

Sent to the delegate when a running application receives a local notification.

- (void)application:(UIApplication *)applicationdidReceiveLocalNotification:(UILocalNotification *)notification


The application that received the local notification.

notificationA local notification that encapsulates details about the notification, potentially including custom data.

DiscussionLocal 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 theoperating system then delivers it at the schedule date and time. If it delivers it when the application is notactive in the foreground, it displays an alert, badges the application icon, or plays a sound—whatever is specifiedin 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 delegateimplements 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 oneshave due dates that have transpired or are about to transpire soon. It can also reset the application icon badgenumber, and it can access any custom data in the local-notification object’s userInfo dictionary.

This method is called after the application:didFinishLaunchingWithOptions: (page 11) method (if thatmethod is implemented).



13


See Also– application:didReceiveRemoteNotification: (page 14)


application:didReceiveRemoteNotification:

Tells the delegate that the running application received a remote notification.

- (void)application:(UIApplication *)applicationdidReceiveRemoteNotification:(NSDictionary *)userInfo


The application that received the remote notification.

userInfoA dictionary that contains information related to the remote notification, potentially including a badgenumber for the application icon, an alert sound, an alert message to display to the user, a notificationidentifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts toan NSDictionary object; the dictionary may contain only property-list objects plus NSNull.

DiscussionIf 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. Forexample, you could use it as a signal to connect to a server and download the data waiting that is waiting forthe app.

The userInfo dictionary contains the aps key whose value is another dictionary. Although you should notneed the information in the aps dictionary, you can retrieve its contents using the following keys:

alert—The value is either a string for the alert message or a dictionary with two keys: body andshow-view. The value of the body key is a string containing the alert message and the value of theshow-view key is a Boolean. If the value of the show-view key is false, the alert’s View button is notshown. The default is to show the View button which, if the user taps it, launches the application.

badge—A number indicating the quantity of data items to download from the provider. This number isto be displayed on the application icon. The absence of a badge property indicates that any numbercurrently badging the icon should be removed.



14

sound—The 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 pernotification (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 theappropriate information in the launch options dictionary. The app does not call this method to handle thatpush notification. Instead, your implementation of the application:willFinishLaunchingWithOptions: (page

25) or application:didFinishLaunchingWithOptions: (page 11) method needs to get the push notificationpayload data and respond appropriately.



See Also– application:didRegisterForRemoteNotificationsWithDeviceToken: (page 15)– application:didFailToRegisterForRemoteNotificationsWithError: (page 11)


application:didRegisterForRemoteNotificationsWithDeviceToken:

Tells the delegate that the application successfully registered with Apple Push Service (APS).

- (void)application:(UIApplication *)applicationdidRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken


The application that initiated the remote-notification registration process.



15

deviceTokenA token that identifies the device to APS. The token is an opaque data type because that is the form thatthe provider needs to submit to the APS servers when it sends a notification to a device. The APS serversrequire 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.

DiscussionThe delegate receives this message after the registerForRemoteNotificationTypes: method ofUIApplication 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 theapplication’s device that are accompanied with this token. This method could be called in other rarecircumstances, such as when the user launches an application after having restored a device from data that isnot the device’s backup data. In this exceptional case, the application won’t know the new device’s token untilthe user launches it.



See Also– application:didReceiveRemoteNotification: (page 14)– application:didFailToRegisterForRemoteNotificationsWithError: (page 11)


application:handleOpenURL:

Asks the delegate to open a resource identified by URL. (Deprecated. Useapplication:openURL:sourceApplication:annotation: (page 17) instead of this method to open URLresources.)

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url


The application object.



16

urlA object representing a URL (Universal Resource Locator). See the appendix of iOS App ProgrammingGuide for Apple-registered schemes for URLs.

Return ValueYES if the delegate successfully handled the request; NO if the attempt to handle the URL failed.

DiscussionIf 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 theapplication:willFinishLaunchingWithOptions: (page 25) andapplication:didFinishLaunchingWithOptions: (page 11) methods. (If only one of the two methods isimplemented, its return value determines whether this method is called.) If your application implements theapplicationDidFinishLaunching: (page 28) method instead ofapplication:didFinishLaunchingWithOptions:, this method is called to open the specified URL afterthe application has been initialized.

If a URL arrives while your application is suspended or running in the background, the system moves yourapplication to the foreground prior to calling this method.

There is no equivalent notification for this delegation method.


See AlsoopenURL: (UIApplication)– application:willFinishLaunchingWithOptions: (page 25)– application:didFinishLaunchingWithOptions: (page 11)


application:openURL:sourceApplication:annotation:

Asks the delegate to open a resource identified by URL.

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)urlsourceApplication:(NSString *)sourceApplication annotation:(id)annotation



17


The application object.

urlA object representing a URL (Universal Resource Locator). See Apple URL Scheme Reference forApple-registered schemes for URLs.

sourceApplicationThe bundle ID of the application that is requesting your application to open the URL (url).

annotationA property-list object supplied by the source application to communicate information to the receivingapplication.

Return ValueYES if the delegate successfully handled the request; NO if the attempt to open the URL resource failed.

DiscussionYour 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 theapplication:willFinishLaunchingWithOptions: (page 25) andapplication:didFinishLaunchingWithOptions: (page 11) methods first, followed by this method. The returnvalues of those methods can be used to prevent this method from being called. (If the application is alreadyrunning, only this method is called.)

If the URL refers to a file that was opened through a document interaction controller, the annotation parametermay contain additional data that the source application wanted to send along with the URL. The format of thisdata is defined by the application that sent it but the data must consist of objects that can be put into a propertylist.

The app prefers calling this method over the application:handleOpenURL: (page 16) method. You shouldimplement the application:handleOpenURL: method only if you need to support older versions of iOS.

There is no matching notification for this method.


See AlsoopenURL: (UIApplication)– application:didFinishLaunchingWithOptions: (page 11)



18


application:shouldRestoreApplicationState:

Asks the delegate whether the app’s saved state information should be restored.

- (BOOL)application:(UIApplication *)applicationshouldRestoreApplicationState:(NSCoder *)coder



coderThe keyed archiver containing the app’s previously saved state information.

Return ValueYES if the app’s state should be restored or NO if it should not.

DiscussionApps must implement this method and the application:shouldSaveApplicationState: (page 19) methodfor state preservation to occur. In addition, your implementation of this method must return YES each timeUIKit tries to restore the state of your app. You can use the information in the provided coder object to decidewhether or not to proceed with state restoration. For example, you might return NO if the data in the coder isfrom a different version of your app and cannot be effectively restored to the current version.


See Also– application:shouldSaveApplicationState: (page 19)


application:shouldSaveApplicationState:

Asks the delegate whether the app’s state should be preserved.

- (BOOL)application:(UIApplication *)application shouldSaveApplicationState:(NSCoder*)coder



19



coderThe keyed archiver into which you can put high-level state information.

Return ValueYES if the app’s state should be preserved or NO if it should not.

DiscussionApps must implement this method and the application:shouldRestoreApplicationState: (page 19) methodfor state preservation to occur. In addition, your implementation of this method must return YES each timeUIKit tries to preserve the state of your app. You can return NO to disable state preservation temporarily. Forexample, 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. Duringrestoration, you can use that information to help decide whether or not to proceed with restoring your appto its previous state.


See Also– application:shouldRestoreApplicationState: (page 19)


application:supportedInterfaceOrientationsForWindow:

Asks the delegate for the interface orientations to use for the view controllers in the specified window.

- (NSUInteger)application:(UIApplication *)applicationsupportedInterfaceOrientationsForWindow:(UIWindow *)window



windowThe window whose interface orientations you want to retrieve.



20

Return ValueA bit mask of the UIInterfaceOrientationMask constants that indicate the orientations to use for theview controllers.

DiscussionThis method returns the interface orientations to use for any view controllers that do not specify their ownexplicitly. The orientations returned by this method are used if the view controller does not override thesupportedInterfaceOrientations or shouldAutorotateToInterfaceOrientation: method.

If you do not implement this method, the application uses the values in the UIInterfaceOrientation keyof the app’s Info.plist as the default interface orientations.



application:viewControllerWithRestorationIdentifierPath:coder:

Asks the delegate to provide the specified view controller.

- (UIViewController *)application:(UIApplication *)applicationviewControllerWithRestorationIdentifierPath:(NSArray *)identifierComponentscoder:(NSCoder *)coder



identifierComponentsAn array of NSString objects corresponding to the restoration identifiers of the desired view controllerand all of its ancestors in the view controller hierarchy. The last value in the array is the restorationidentifier of the desired view controller. Earlier entries represent the restoration identifiers of its ancestors.

coderThe keyed archiver containing the app’s saved state information.

Return ValueThe 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 othersfrom being restored too. For example, in a navigation controller, returning nil for a view controller in themiddle of the navigation stack prevents the restoration of view controllers higher up on the stack.



21

DiscussionDuring state restoration, when UIKit encounters a view controller without a restoration class, it calls this methodto ask for the corresponding view controller object. Your implementation of this method should create (orfind) the corresponding view controller object and return it. If you determine that it does not make sense todisplay this view controller now, you may return nil to prevent that view controller from being added to yourinterface 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 window’s root viewcontroller, which itself may present or embed other view controllers. Those presented or embedded viewcontrollers may themselves present and embed other view controllers. The result is a hierarchy of view controllerrelationships, with each presented or embedded view controller becoming a child of the view controller thatpresented or embedded it. The strings in the identifierComponents array identify the path through thishierarchy 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. Youcan also return an existing view controller object that was created by another means. For example, you wouldalways return the existing view controllers loaded from your app’s main storyboard file rather than create newobjects.

Your implementation of this method may use any data in the provided coder to assist in the restorationprocess. However, you usually do not need to restore the entire state of the view controller at this point. Duringa later pass, view controllers that define a decodeRestorableStateWithCoder:method are normally givena chance to restore their state form the same coder object. Similarly, the app delegate itself has aapplication:didDecodeRestorableStateWithCoder: (page 10) method that you can use to restore app-levelstate 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 thedecodeRestorableStateWithCoder: method of the view controller.



application:willChangeStatusBarFrame:

Tells the delegate when the frame of the status bar is about to change.



22

- (void)application:(UIApplication *)applicationwillChangeStatusBarFrame:(CGRect)newStatusBarFrame



newStatusBarFrameThe changed frame of the status bar, in screen coordinates.

DiscussionThe application calls this method when it receives a setStatusBarOrientation:animated: message andis about to change the interface orientation.

After calling this method, the application also posts aUIApplicationWillChangeStatusBarFrameNotification notification to give interested objects achance to respond to the change.


See Also– application:didChangeStatusBarFrame: (page 9)


application:willChangeStatusBarOrientation:duration:

Tells the delegate when the interface orientation of the status bar is about to change.

- (void)application:(UIApplication *)applicationwillChangeStatusBarOrientation:(UIInterfaceOrientation)newStatusBarOrientationduration:(NSTimeInterval)duration



newStatusBarOrientationA constant that indicates the new orientation of the application’s user interface; see “Monitoring AppState Changes” (page 5) for details.

durationThe duration of the animation to the new orientation, in seconds.



23

DiscussionThe delegate typically implements this method to prepare its windows and views for the new orientation. Thedelegate can get the current device orientation from the shared UIDevice object.

After calling this method, the application also posts aUIApplicationWillChangeStatusBarOrientationNotificationnotification to give interested objectsa chance to respond to the change.



application:willEncodeRestorableStateWithCoder:

Tells your delegate to save any high-level state information at the beginning of the state preservation process.

- (void)application:(UIApplication *)applicationwillEncodeRestorableStateWithCoder:(NSCoder *)coder



coderThe keyed archiver in which to write any state information.

DiscussionThe state preservation system calls this method at the beginning of the preservation process. This is youropportunity to add any app-level information to state information. For example, you might use this methodto write version information or the high-level configuration of your app.



24

Important: This method is not a substitute for saving your app’s data structures persistently to disk. Youshould continue to save your app’s 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 app’s userinterface. You should consider the data in the coder as purgeable and be prepared for it to be unavailableduring subsequent launches.

Your implementation of this method can encode restorable view and view controller objects that it needs toreference. Encoding a restorable view or view controller writes that object’s 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 viewcontroller defines a encodeRestorableStateWithCoder:method, that method is also called at some pointso that the object can encode its own state.

Apart from views and view controllers, other objects follow the normal serialization process and must adoptthe NSCoding protocol before they can be encoded. Encoding such objects embeds the object’s contents inthe archive directly. During the decode process, a new object is created and initialized with the data from thearchive.


See Also– application:didDecodeRestorableStateWithCoder: (page 10)


application:willFinishLaunchingWithOptions:

Tells the delegate that the launch process has begun but that state restoration has not yet occurred.

- (BOOL)application:(UIApplication *)applicationwillFinishLaunchingWithOptions:(NSDictionary *)launchOptions



launchOptionsA dictionary indicating the reason the application was launched (if any). The contents of this dictionarymay be empty in situations where the user launched the application directly. For information about thepossible keys in this dictionary and how to handle them, see “Launch Options Keys” (page 34).



25

Return ValueNO if the application cannot handle the URL resource, otherwise return YES. The return value is ignored if theapplication is launched as a result of a remote notification.

DiscussionYou 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 applicationhas been launched and its main storyboard or nib file has been loaded, but before your app’s state has beenrestored. 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 containsdata indicating the reason for the launch. Your app should look in this dictionary for any keys that correspondto 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 theUIApplicationLaunchOptionsURLKey (page 34) key and return a Boolean value indicating whether your appcan actually open the URL. You should not try to open the URL in this method. Instead, implement theapplication:openURL:sourceApplication:annotation: (page 17) method in your app delegate and usethat method to open the URL.

The return result from this method is combined with the return result from theapplication:didFinishLaunchingWithOptions: method to determine if a URL should be handled. Ifeither method returns NO, the URL is not handled. If you do not implement one of the methods, only the returnvalue of the implemented method is considered.


See Also– application:didFinishLaunchingWithOptions: (page 11)


applicationDidBecomeActive:

Tells the delegate that the application has become active.

- (void)applicationDidBecomeActive:(UIApplication *)application



26


The singleton application instance.

DiscussionThis method is called to let your application know that it moved from the inactive to active state. This canoccur because your application was launched by the user or the system. Applications can also return to theactive 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 applicationwas inactive. For example, you could use it to restart timers or throttle up OpenGL ES frame rates. If yourapplication was previously in the background, you could also use it to refresh your application’s user interface.

After calling this method, the application also posts a UIApplicationDidBecomeActiveNotificationnotification to give interested objects a chance to respond to the transition.



applicationDidEnterBackground:

Tells the delegate that the application is now in the background.

- (void)applicationDidEnterBackground:(UIApplication *)application



DiscussionIn iOS 4.0 and later, this method is called instead of the applicationWillTerminate: method when theuser quits an application that supports background execution. You should use this method to release sharedresources, save user data, invalidate timers, and store enough application state information to restore yourapplication to its current state in case it is terminated later. You should also disable updates to your application’suser interface and avoid using some types of shared system resources (such as the user’s 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 youneed additional time to perform any final tasks, you can request additional execution time from the systemby calling beginBackgroundTaskWithExpirationHandler:. In practice, you should return fromapplicationDidEnterBackground: as quickly as possible. If the method does not return before time runsout 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. Becauseit's likely any background tasks you start in applicationDidEnterBackground:will not run until after thatmethod exits, you should request additional background execution time before starting those tasks. In otherwords, first call beginBackgroundTaskWithExpirationHandler: and then run the task on a dispatchqueue or secondary thread.

The application also posts a UIApplicationDidEnterBackgroundNotification notification around thesame 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 howto start background tasks at quit time, see iOS App Programming Guide .



applicationDidFinishLaunching:

Tells the delegate when the application has finished launching.

- (void)applicationDidFinishLaunching:(UIApplication *)application



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



28

Your implementation of this method should create your application’s user interface and initialize the application’sdata structures. If your application persists its state between launches, you would also use this method torestore your application to its previous state.

After calling this method, the application also posts a UIApplicationDidFinishLaunchingNotificationnotification to give interested objects a chance to respond to the initialization cycle.



applicationDidReceiveMemoryWarning:

Tells the delegate when the application receives a memory warning from the system.

- (void)applicationDidReceiveMemoryWarning:(UIApplication *)application



DiscussionYour implementation of this method should free up as much memory as possible by purging cached dataobjects that can be recreated (or reloaded from disk) later. You use this method in conjunction with thedidReceiveMemoryWarning of the UIViewController class and theUIApplicationDidReceiveMemoryWarningNotification notification to release memory throughoutyour application.

It is strongly recommended that you implement this method. If your application does not release enoughmemory during low-memory conditions, the system may terminate it outright.


See AlsodidReceiveMemoryWarning (UIViewController)UIApplicationDidReceiveMemoryWarningNotification




29

applicationProtectedDataDidBecomeAvailable:

Tells the delegate that protected files are available now.

- (void)applicationProtectedDataDidBecomeAvailable:(UIApplication *)application



DiscussionOn a device that uses content protection, protected files are stored in an encrypted form and made availableonly at certain times, usually when the device is unlocked. This notification lets your application know that thedevice is now unlocked and that you may access certain types of protected files again.



applicationProtectedDataWillBecomeUnavailable:

Tells the delegate that the protected files are about to become unavailable.

- (void)applicationProtectedDataWillBecomeUnavailable:(UIApplication *)application



DiscussionOn a device that uses content protection, protected files are stored in an encrypted form and made availableonly at certain times, usually when the device is unlocked. This notification lets your application know that thedevice is about to be locked and that any protected files it is currently accessing might become unavailableshortly.

If your application is currently accessing a protected file, you can use this method to release any references tothat 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 whilethe device is locked.



30



applicationSignificantTimeChange:

Tells the delegate when there is a significant change in the time.

- (void)applicationSignificantTimeChange:(UIApplication *)application



DiscussionExamples of significant time changes include the arrival of midnight, an update of the time by a carrier, andthe change to daylight savings time. The delegate can implement this method to adjust any object of theapplication that displays time or is sensitive to time changes.

Prior to calling this method, the application also posts aUIApplicationSignificantTimeChangeNotification notification to give interested objects a chanceto respond to the change.

If your application is currently suspended, this message is queued until your application returns to theforeground, at which point it is delivered. If multiple time changes occur, only the most recent one is delivered.



applicationWillEnterForeground:

Tells the delegate that the application is about to enter the foreground.

- (void)applicationWillEnterForeground:(UIApplication *)application





31

DiscussionIn iOS 4.0 and later, this method is called as part of the transition from the background to the active state. Youcan 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 shortlybefore calling this method to give interested objects a chance to respond to the transition.



applicationWillResignActive:

Tells the delegate that the application is about to become inactive.

- (void)applicationWillResignActive:(UIApplication *)application



DiscussionThis 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 inthe 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 workwhile it waits to transition to either the active or background state.

After calling this method, the application also posts a UIApplicationWillResignActiveNotificationnotification to give interested objects a chance to respond to the transition.





32

applicationWillTerminate:

Tells the delegate when the application is about to terminate.

- (void)applicationWillTerminate:(UIApplication *)application



DiscussionThis 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 sharedresources, saving user data, and invalidating timers. Your implementation of this method has approximatelyfive seconds to perform any tasks and return. If the method does not return before time expires, the systemmay kill the process altogether.

For applications that do not support background execution or are linked against iOS 3.x or earlier, this methodis always called when the user quits the application. For applications that support background execution, thismethod is generally not called when the user quits the application because the application simply moves tothe background in that case. However, this method may be called in situations where the application is runningin the background (not suspended) and the system needs to terminate it for some reason.

After calling this method, the application also posts a UIApplicationWillTerminateNotificationnotification to give interested objects a chance to respond to the transition.


See Also– applicationDidEnterBackground: (page 27)– application:didFinishLaunchingWithOptions: (page 11)




33

Constants

Launch Options Keys

Keys used to access values in the launch options dictionary passed to theapplication:willFinishLaunchingWithOptions: (page 25) andapplication:didFinishLaunchingWithOptions: (page 11) methods of the application delegate.

NSString *const UIApplicationLaunchOptionsURLKey;NSString *const UIApplicationLaunchOptionsSourceApplicationKey;NSString *const UIApplicationLaunchOptionsRemoteNotificationKey;NSString *const UIApplicationLaunchOptionsAnnotationKey;NSString *const UIApplicationLaunchOptionsLocalNotificationKey;NSString *const UIApplicationLaunchOptionsLocationKey;NSString *const UIApplicationLaunchOptionsNewsstandDownloadsKey;

ConstantsUIApplicationLaunchOptionsURLKey

The presence of this key indicates that the application was launched in order to open a URL. The valueof 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 namedUIApplicationDidFinishLaunchingNotification.

Available in iOS 3.0 and later.

Declared in UIApplication.h.

UIApplicationLaunchOptionsSourceApplicationKeyThe presence of this key identifies the app that requested the launch of your app. The value of this keyis an NSString object that represents the bundle ID of the app that made the request.




UIApplicationDelegate Protocol ReferenceConstants


34

UIApplicationLaunchOptionsRemoteNotificationKeyThe presence of this key indicates that a remote notification is available for the app to process. The valueof this key is an NSDictionary containing the payload of the remote notification. See the descriptionof application:didReceiveRemoteNotification: (page 14) for further information about handlingremote notifications.




UIApplicationLaunchOptionsAnnotationKeyThe presence of this key indicates that custom data was provided by the app that requested the openingof the URL. The value of this key is a property-list object containing the custom data. The same object isalso passed to the annotation parameter of theapplication:openURL:sourceApplication:annotation: (page 17) method. The contents of thisproperty-list object are specific to the app that made the request.



UIApplicationLaunchOptionsLocalNotificationKeyThe presence of this key indicates that a local notification is available for the app to process. The valueof this key is the UILocalNotification object that was triggered. For additional information abouthandling local notifications, see the application:didReceiveLocalNotification: (page 13) method.




UIApplicationLaunchOptionsLocationKeyThe presence of this key indicates that the application was launched in response to an incoming locationevent. The value of this key is an NSNumber object containing a Boolean value. You should use thepresence 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.





35

UIApplicationLaunchOptionsNewsstandDownloadsKeyThe 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 objectscorresponding to the assets. Although you can use the identifiers for cross-checking purposes, you shouldobtain the definitive array of NKAssetDownload objects (representing asset downloads in progress orin error) through thedownloadingAssetsproperty of theNKLibraryobject representing the Newsstandapplication’s library.



App-Specific State Restoration Keys

The following keys are used when reading and writing state restoration data.

NSString *const UIApplicationStateRestorationUserInterfaceIdiomKey;NSString *const UIApplicationStateRestorationBundleVersionKey;

ConstantsUIApplicationStateRestorationUserInterfaceIdiomKey

The value of this key is an NSNumber object containing one of the values for the UIUserInterfaceIdiomenum. This value reflects whether the interface that was saved was targeting the iPad or iPhone idiom.


Declared in UIStateRestoration.h.

UIApplicationStateRestorationBundleVersionKeyThe value of this key is an NSString object that identifies the version of your app (as obtained from theCFBundleVersion key of your app’s Info.plist file) was was present when the state informationwas saved. You can use the value of this key to help make choices about how to proceed during staterestoration. For example, if the key indicates that the state is associated with an older version of yourapp, you might want to avoid restoring the previous state altogether or modify the restoration processmore significantly.


Declared in UIStateRestoration.h.



36

This table describes the changes to UIApplicationDelegate Protocol Reference .

NotesDate

Added methods related to state preservation and restoration.2012-09-19

Describes the window property added in iOS 5.0.2011-10-12

Describes the application:openURL:sourceApplication:annotation: method,which was introduced in iOS 4.2.

2010-11-15

Improved description of launchOptions parameter ofapplication:didFinishLaunchingWithOptions:.

2010-08-03

Updated for iOS 4.02010-05-11

Marked all protocols as optional.2009-11-17

Corrected API symbols that link to descriptions in reference.2009-05-19

Added remote-notification methods.2009-03-08

Added link to companion document and noted which notifications arerelated to each delegate method.

2008-09-09

New document that describes the protocol implemented by the delegateof a UIApplication object to respond to various system events.

2008-07-03


37

Document Revision History

Apple Inc.© 2012 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, iPad, iPhone, and Xcodeare trademarks of Apple Inc., registered in theU.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 SiliconGraphics, Inc.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

UIApplicationDelegate Protocol

Documents

Transcript of UIApplicationDelegate Protocol