| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Companion guide | |
| Declared in | UIApplication.h |
| Related sample code |
The UIApplicationDelegate protocol declares methods that are implemented by the delegate of the singleton UIApplication object.
By implementing these methods, the delegate can respond to application launch and termination, low-memory warnings, the opening of URL resources, changes in status-bar orientation, and other system events.
For iPhone OS 3.0, this protocol has added a number of methods related to remote notifications; see “Handling Remote Notifications” for descriptions of these methods. Another method introduced in iPhone 3.0 that is of interest is application:didFinishLaunchingWithOptions:. If the delegate implements this method (as is recommended), it is called instead of applicationDidFinishLaunching:. The new method is intended to be used in two situations:
iPhone OS delivers a remote notification for the application and the user launches it in response to the notification.
Another application invokes the openURL: method of UIApplication and, as a result, this application is launched so it can handle the resource type specified in the URL scheme.
Because the reasons for launching are different from the usual case, the application may choose to display a different user interface. UIApplication passes in an options dictionary into application:didFinishLaunchingWithOptions:. Depending on the reason for launching, this dictionary contains either a URL object and the bundle ID of the application calling openURL:, or it contains the payload dictionary accompanying the remote notification. If the delegate implements this method, the calling sequence at launch time is the following:
application:didFinishLaunchingWithOptions:
instead of
applicationDidFinishLaunching:
applicationDidBecomeActive:
application:handleOpenURL: (if URL is used to launch application)
Similarly, if you implement both the application:didFinishLaunchingWithOptions: method and the application:didReceiveRemoteNotification: method, and your application is launched as a result of an incoming push notification, the latter method is not called to handle that notification. So be sure to handle remote notifications in both places.
– applicationDidFinishLaunching:
– application:didFinishLaunchingWithOptions:
– applicationWillTerminate:
– applicationDidReceiveMemoryWarning:
– applicationSignificantTimeChange:
Tells the delegate when the frame of the status bar has changed.
- (void)application:(UIApplication *)application didChangeStatusBarFrame:(CGRect)oldStatusBarFrame
The delegating application object.
The previous frame of the status bar, in screen coordinates.
The application post a UIApplicationDidChangeStatusBarFrameNotification at the same time it calls this method.
UIApplication.hTells the delegate when the interface orientation of the status bar has changed.
- (void)application:(UIApplication *)application didChangeStatusBarOrientation:(UIInterfaceOrientation)oldStatusBarOrientation
The delegating application object.
A constant that indicates the previous orientation of the applicationâs user interface; see “Controlling Application Behavior” for details.
The delegate can get the current device orientation from the shared UIDevice object.
The application posts a UIApplicationDidChangeStatusBarOrientationNotification at the same time it sends this message to its delegate.
UIApplication.hSent to the delegate when Apple Push Service cannot successfully complete the registration process.
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
The application that initiated the remote-notification registration process.
An NSError object that encapsulates information why registration did not succeed. The application can choose to display this information to the user.
The delegate receives this message after the registerForRemoteNotifications method of UIApplication is invoked and there is an error in the registration process.
– application:didReceiveRemoteNotification:– application:didRegisterForRemoteNotificationsWithDeviceToken:UIApplication.hTells the delegate when the application has launched due to a remote notification or the opening of a URL resource.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
The delegating application object.
A dictionary containing information related to one of two situations:
iPhone OS has delivered a remote notification targeted at the application and the user has launched the application through the displayed alert message.
Another application has opened a URL resource whose scheme is claimed by the receiving application.
In the former case, the launchOptions dictionary contains the notification payload dictionary (see application:didReceiveRemoteNotification:). In the latter case, the launchOptions dictionary contains both an object representing the URL and the bundle ID of the application attempting to open the URL. The dictionary is nil if the user launched the application by tapping the application icon. See “UserInfo Dictionary Keys” in the reference for the UIApplication class for descriptions of the keys used to access these dictionary objects.
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.
Objects that are not the application delegate can access the same launchOptions dictionary values by observing the notification named UIApplicationDidFinishLaunchingNotification and accessing the notification’s userInfo dictionary.
It is recommended that you implement this method instead of applicationDidFinishLaunching:. See the class description for the differences in calling sequences between the two methods.
UIApplication.hSent to the delegate when a running application receives a remote notification.
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
The application interested in the remote notification.
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 iPhone OS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
The delegate receives this message when the application is running and a remote notification arrives for it. In response, the application typically connects with its provider and downloads the data waiting for it. It may also process the notification in any other way it deems useful.
The userInfo dictionary contains another dictionary that you can obtain using the aps key. You can access the contents of the aps dictionary—though you shouldn’t need to in most cases—using the following keys:
alert—The value may either be a string for the alert message or a dictionary with two keys: body and show-view. The value of the former is the alert message and the latter is a Boolean (false or true). If false, the alert’s View button is not shown. 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 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.
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 per notification (256 bytes) and delivery is not guaranteed.
If you implement application:didFinishLaunchingWithOptions: to handle an incoming push notification that causes the launch of the application, this method is not invoked for that push notification. See the class description for more information.
– application:didRegisterForRemoteNotificationsWithDeviceToken:– application:didFailToRegisterForRemoteNotificationsWithError:UIApplication.hSent to the delegate when the application successfully registers with Apple Push Service (APS).
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
The application that initiated the remote-notification registration process.
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.
The delegate receives this message after the registerForRemoteNotifications 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 application’s 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 device’s backup data. In this exceptional case, the application won’t know the new device’s token until the user launches it.
– application:didReceiveRemoteNotification:– application:didFailToRegisterForRemoteNotificationsWithError:UIApplication.hAsks the delegate to open a resource identified by URL.
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
The application object.
A object representing a URL (Universal Resource Locator). See the appendix of iPhone Application Programming Guide for Apple-registered schemes for URLs.
YES if the delegate successfully handle the request; NO if the attempt to handle the URL failed.
Applications may choose to handle the opening of their URLs by implementing the application:didFinishLaunchingWithOptions: instead. If they implement that method, application:handleOpenURL: is not invoked. There is no equivalent notification for this delegation method.
– openURL: (UIApplication)– application:didFinishLaunchingWithOptions:UIApplication.hTells the delegate when the frame of the status bar is about to change.
- (void)application:(UIApplication *)application willChangeStatusBarFrame:(CGRect)newStatusBarFrame
The delegating application object.
The changed frame of the status bar, in screen coordinates.
The application calls this method when it receives a setStatusBarOrientation:animated: message and is about to change the interface orientation.
The application posts a UIApplicationWillChangeStatusBarFrameNotification at the same time it calls this method.
UIApplication.hTells the delegate when the interface orientation of the status bar is about to change.
- (void)application:(UIApplication *)application willChangeStatusBarOrientation:(UIInterfaceOrientation)newStatusBarOrientation duration:(NSTimeInterval)duration
The delegating application object.
A constant that indicates the new orientation of the applicationâs user interface; see “Controlling Application Behavior” for details.
The duration of the animation to the new orientation, in seconds.
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.
The application posts a UIApplicationWillChangeStatusBarOrientationNotification at the same time it sends this message to its delegate.
UIApplication.hTells the delegate that the application has become active.
- (void)applicationDidBecomeActive:(UIApplication *)application
The singleton application instance.
The delegate can implement this method to make adjustments when the application transitions from an inactive state to an active state. When an application is inactive, it is executing but is not dispatching incoming events. This occurs when an overlay window pops up or when the device is locked.
Just after it becomes active, the application also posts a UIApplicationDidBecomeActiveNotification.
UIApplication.hTells the delegate when the application has finished launching.
- (void)applicationDidFinishLaunching:(UIApplication *)application
The delegating application object.
This method is the ideal place for the delegate to perform various initialization and configuration tasks, especially restoring the application to the previous state and setting up the initial windows and views of the application.
The application posts a UIApplicationDidFinishLaunchingNotification at the same time it calls this method.
It is recommended that you implement application:didFinishLaunchingWithOptions: instead of this method. See the class description for the differences in calling sequences between the two methods.
UIApplication.hTells the delegate when the application receives a memory warning from the system.
- (void)applicationDidReceiveMemoryWarning:(UIApplication *)application
The delegating application object.
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.
– didReceiveMemoryWarning (UIViewController)UIApplicationDidReceiveMemoryWarningNotificationUIApplication.hTells the delegate when there is a significant change in the time.
- (void)applicationSignificantTimeChange:(UIApplication *)application
The delegating application object.
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.
The application posts a UIApplicationSignificantTimeChangeNotification at the same time it calls this method.
UIApplication.hTells the delegate that the application will become inactive.
- (void)applicationWillResignActive:(UIApplication *)application
The singleton application instance.
The delegate can implement this method to make adjustments when the application transitions from an active state to an inactive state. When an application is inactive, it is executing but is not dispatching incoming events. This occurs when an overlay window pops up or when the device is locked.
Just before it becomes inactive, the application also posts a UIApplicationWillResignActiveNotification.
UIApplication.hTells the delegate when the application is about to terminate.
- (void)applicationWillTerminate:(UIApplication *)application
The delegating application object.
This method is the ideal place for the delegate to perform clean-up tasks, such as freeing allocated memory, invalidating timers, and storing application state.
The application posts a UIApplicationWillTerminateNotification at the same time it calls this method.
UIApplication.hLast updated: 2009-11-17
iPhone OS Reference Library Data Management: Event Handling UIApplicationDelegate Protocol Reference