NSApplicationDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Declared in
NSApplication.h
Companion guides
Related sample code

Overview

The NSApplicationDelegate protocol defines the methods that may be implemented by delegates of NSApplication objects.

Tasks

Launching Applications

Terminating Applications

Managing Active Status

Hiding Applications

Managing Windows

Managing the Dock Menu

Displaying Errors

Managing the Screen

Opening Files

Printing

Handling Push Notifications

Application Restorable State

Occlusion State

Instance Methods

application:didDecodeRestorableState:

Tells the delegate the application has extracted its restorable state from a given archiver.

- (void)application:(NSApplication *)app didDecodeRestorableState:(NSCoder *)coder
Parameters
app

The application.

coder

The coder extracting the archive.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSApplication.h

application:didFailToRegisterForRemoteNotificationsWithError:

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

- (void)application:(NSApplication *)application 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 display this information to the user.

Discussion

The delegate receives this message after the registerForRemoteNotificationTypes: method of NSApplication 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 OS X v10.7 and later.
Declared In
NSApplication.h

application:didReceiveRemoteNotification:

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

- (void)application:(NSApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
Parameters
application

The application that received the remote notification.

userInfo

A dictionary that contains information related to the remote notification, specifically a badge number for the application icon, a notification identifier, and possibly custom data. The provider originates it as a JSON-defined dictionary that AppKit converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.

Discussion

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 using the following keys:

  • badge—A number indicating the quantity of data items to obtain 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.

    Icon badging is the only notification type supported for non-running applications.

  • 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). You may ignore the second key.

  • 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 applicationDidFinishLaunching: and a push notification for the application has recently arrived, this method is not invoked for that push notification. In this case, you can access the JSON data in the userInfo dictionary of the passed-in NSNotification object.

For more information about how to implement push notifications in your application, see Local and Push Notification Programming Guide.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSApplication.h

application:didRegisterForRemoteNotificationsWithDeviceToken:

Sent to the delegate when Apple Push Services successfully completes the registration process.

- (void)application:(NSApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
Parameters
application

The application that initiated the remote-notification registration process.

deviceToken

A token that identifies the device to Apple Push Notification Service (APNS). The token is an opaque data type because that is the form that the provider needs to submit to the APNS servers when it sends a notification to a device. The APNS servers require a binary format for performance reasons.

The size of a device token is 32 bytes.

Discussion

The delegate receives this message after the registerForRemoteNotificationTypes:method of NSApplication 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. APNS only pushes notifications to the application’s computer that are accompanied with this token.

For more information about how to implement push notifications in your application, see Local and Push Notification Programming Guide.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSApplication.h

application:openFile:

Tells the delegate to open a single file.

- (BOOL)application:(NSApplication *)theApplication openFile:(NSString *)filename
Parameters
theApplication

The application object associated with the delegate.

filename

The name of the file to open.

Return Value

YES if the file was successfully opened or NO if it was not.

Discussion

Sent directly by theApplication to the delegate. The method should open the file filename, returning YES if the file is successfully opened, and NO otherwise. If the user started up the application by double-clicking a file, the delegate receives the application:openFile: message before receiving applicationDidFinishLaunching:. (applicationWillFinishLaunching: is sent before application:openFile:.)

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Related Sample Code
Declared In
NSApplication.h

application:openFiles:

Tells the delegate to open multiple files.

- (void)application:(NSApplication *)sender openFiles:(NSArray *)filenames
Parameters
sender

The application object associated with the delegate.

filenames

An array of NSString objects containing the names of the files to open..

Discussion

Identical to application:openFile: except that the receiver opens multiple files corresponding to the file names in the filenames array. Delegates should invoke the replyToOpenOrPrint: method upon success or failure, or when the user cancels the operation.

Availability
  • Available in OS X v10.3 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

application:openFileWithoutUI:

Tells the delegate to open a file programmatically.

- (BOOL)application:(id)sender openFileWithoutUI:(NSString *)filename
Parameters
sender

The object that sent the command.

filename

The name of the file to open.

Return Value

YES if the file was successfully opened or NO if it was not.

Discussion

Sent directly by sender to the delegate to request that the file filename be opened as a linked file. The method should open the file without bringing up its application’s user interface—that is, work with the file is under programmatic control of sender, rather than under keyboard control of the user.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

application:openTempFile:

Tells the delegate to open a temporary file.

- (BOOL)application:(NSApplication *)theApplication openTempFile:(NSString *)filename
Parameters
theApplication

The application object associated with the delegate.

filename

The name of the temporary file to open.

Return Value

YES if the file was successfully opened or NO if it was not.

Discussion

Sent directly by theApplication to the delegate. The method should attempt to open the file filename, returning YES if the file is successfully opened, and NO otherwise.

By design, a file opened through this method is assumed to be temporary—it’s the application’s responsibility to remove the file at the appropriate time.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

application:printFile:

Sent when the user starts up the application on the command line with the -NSPrint option.

- (BOOL)application:(NSApplication *)theApplication printFile:(NSString *)filename
Parameters
theApplication

The application object that is handling the printing.

filename

The name of the file to print.

Return Value

YES if the file was successfully printed or NO if it was not.

Discussion

This message is sent directly by theApplication to the delegate. The application terminates (using the terminate: method) after this method returns.

If at all possible, this method should print the file without displaying the user interface. For example, if you pass the -NSPrint option to the TextEdit application, TextEdit assumes you want to print the entire contents of the specified file. However, if the application opens more complex documents, you may want to display a panel that lets the user choose exactly what they want to print.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

application:printFiles:withSettings:showPrintPanels:

Prints a group of files.

- (NSApplicationPrintReply)application:(NSApplication *)application printFiles:(NSArray *)fileNames withSettings:(NSDictionary *)printSettings showPrintPanels:(BOOL)showPrintPanels
Parameters
application

The application object that is handling the printing.

fileNames

An array of NSString objects, each of which contains the name of a file to print.

printSettings

A dictionary containing NSPrintInfo-compatible print job attributes.

showPrintPanels

A Boolean that specifies whether the print panel should be displayed for each file printed. Print progress indicators will be presented even if this value is NO.

Return Value

A constant indicating whether printing was successful. For a list of possible values, see NSApplicationPrintReply.

Discussion

Return NSPrintingReplyLater if the result of printing cannot be returned immediately, for example, if printing will cause the presentation of a sheet. If your method returns NSPrintingReplyLater it must always invoke the NSApplication method replyToOpenOrPrint:] when the entire print operation has been completed, successfully or not.

This delegate method replaces application:printFiles:, which is now deprecated. If your application delegate only implements the deprecated method, it is still invoked, and NSApplication uses private functionality to arrange for the print settings to take effect.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

application:willEncodeRestorableState:

Tells the delegate the application will encode any application state that was preserved between application launches.

- (void)application:(NSApplication *)app willEncodeRestorableState:(NSCoder *)coder
Parameters
app

The application.

coder

The coder extracting the archive.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSApplication.h

application:willPresentError:

Sent to the delegate before the specified application presents an error message to the user.

- (NSError *)application:(NSApplication *)application willPresentError:(NSError *)error
Parameters
application

The application object associated with the delegate.

error

The error object that is used to construct the error message. Your implementation of this method can return a new NSError object or the same one in this parameter.

Return Value

The error object to display.

Discussion

You can implement this delegate method to customize the presentation of any error presented by your application, as long as no code in your application overrides either of the NSResponder methods presentError:modalForWindow:delegate:didPresentSelector:contextInfo: or presentError: in a way that prevents errors from being passed down the responder chain to the application object.

Your implementation of this delegate method can examine error and, if its localized description or recovery information is unhelpfully generic, return an error object with specific localized text that is more suitable for presentation in alert sheets and dialogs. If you do this, always use the domain and error code of the NSError object to distinguish between errors whose presentation you want to customize and those you do not. Don’t make decisions based on the localized description, recovery suggestion, or recovery options because parsing localized text is problematic. If you decide not to customize the error presentation, just return the passed-in error object.

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidBecomeActive:

Sent by the default notification center immediately after the application becomes active.

- (void)applicationDidBecomeActive:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidBecomeActiveNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidChangeOcclusionState:

Tells the delegate the application’s occlusion state changed.

- (void)applicationDidChangeOcclusionState:(NSNotification *)notification
Parameters
notification

A notification named NSApplicationDidChangeOcclusionStateNotification. Calling the object method of this notification returns the NSApplication object itself.

Discussion

Upon receiving this method, you can query the application for its occlusion state. Note that this only notifies about changes in the state of the occlusion, not when the occlusion region changes. You can use this method to increase responsiveness and save power by halting any expensive calculations that the user can not see.

Availability
  • Available in OS X v10.9 and later.
Declared In
NSApplication.h

applicationDidChangeScreenParameters:

Sent by the default notification center when the configuration of the displays attached to the computer is changed (either programmatically or when the user changes settings in the Displays control panel).

- (void)applicationDidChangeScreenParameters:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidChangeScreenParametersNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidFinishLaunching:

Sent by the default notification center after the application has been launched and initialized but before it has received its first event.

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidFinishLaunchingNotification. Calling the object method of this notification returns the NSApplication object itself.

Discussion

Delegates can implement this method to perform further initialization. This method is called after the application’s main run loop has been started but before it has processed any events. If the application was launched by the user opening a file, the delegate’s application:openFile: method is called before this method. If you want to perform initialization before any files are opened, implement the applicationWillFinishLaunching: method in your delegate, which is called before application:openFile:.)

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidHide:

Sent by the default notification center immediately after the application is hidden.

- (void)applicationDidHide:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidHideNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidResignActive:

Sent by the default notification center immediately after the application is deactivated.

- (void)applicationDidResignActive:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidResignActiveNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidUnhide:

Sent by the default notification center immediately after the application is made visible.

- (void)applicationDidUnhide:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidUnhideNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDidUpdate:

Sent by the default notification center immediately after the application object updates its windows.

- (void)applicationDidUpdate:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationDidUpdateNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationDockMenu:

Allows the delegate to supply a dock menu for the application dynamically.

- (NSMenu *)applicationDockMenu:(NSApplication *)sender
Parameters
sender

The application object associated with the delegate.

Return Value

The menu to display in the dock.

Discussion

You can also connect a menu in Interface Builder to the dockMenu outlet. A third way for your application to specify a dock menu is to provide an NSMenu in a nib.

If this method returns a menu, this menu takes precedence over the dockMenu in the nib.

The target and action for each menu item are passed to the dock. On selection of the menu item the dock messages your application, which should invoke [NSApp sendAction:selector to:target from:nil].

To specify an NSMenu in a nib, you add the nib name to the info.plist, using the key AppleDockMenu. The nib name is specified without an extension. You then create a connection from the file’s owner object (which by default is NSApplication) to the menu. Connect the menu to the dockMenu outlet of NSApplication. The menu is in its own nib file so it can be loaded lazily when the dockMenu is requested, rather than at launch time.

Availability
  • Available in OS X v10.1 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationOpenUntitledFile:

Tells the delegate to open an untitled file.

- (BOOL)applicationOpenUntitledFile:(NSApplication *)theApplication
Parameters
theApplication

The application object associated with the delegate.

Return Value

YES if the file was successfully opened or NO if it was not.

Discussion

Sent directly by theApplication to the delegate to request that a new, untitled file be opened.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationShouldHandleReopen:hasVisibleWindows:

Sent by the application to the delegate prior to default behavior to reopen (rapp) AppleEvents.

- (BOOL)applicationShouldHandleReopen:(NSApplication *)theApplication hasVisibleWindows:(BOOL)flag
Parameters
theApplication

The application object.

flag

Indicates whether the NSApplication object found any visible windows in your application. You can use this value as an indication of whether the application would do anything if you return YES.

Return Value

YES if you want the application to perform its normal tasks or NO if you want the application to do nothing.

Discussion

These events are sent whenever the Finder reactivates an already running application because someone double-clicked it again or used the dock to activate it.

By default the Application Kit will handle this event by checking whether there are any visible NSWindow (not NSPanel) objects, and, if there are none, it goes through the standard untitled document creation (the same as it does if theApplication is launched without any document to open). For most document-based applications, an untitled document will be created.

The application delegate will also get a chance to respond to the normal untitled document delegate methods. If you implement this method in your application delegate, it will be called before any of the default behavior happens. If you return YES, then NSApplication will proceed as normal. If you return NO, then NSApplication will do nothing. So, you can either implement this method with a version that does nothing, and return NO if you do not want anything to happen at all (not recommended), or you can implement this method, handle the event yourself in some custom way, and return NO.

Miniaturized windows, windows in the Dock, are considered visible by this method, and cause flag to return YES, despite the fact that miniaturized windows return NO when sent an isVisible message.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationShouldOpenUntitledFile:

Invoked immediately before opening an untitled file.

- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender
Parameters
sender

The application object associated with the delegate.

Return Value

YES if the application should open a new untitled file or NO if it should not.

Discussion

Use this method to decide whether the application should open a new, untitled file. Note that applicationOpenUntitledFile: is invoked if this method returns YES.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationShouldTerminate:

Sent to notify the delegate that the application is about to terminate.

- (NSApplicationTerminateReply)applicationShouldTerminate:(NSApplication *)sender
Parameters
sender

The application object that is about to be terminated.

Return Value

One of the values defined in NSApplicationTerminateReply constants indicating whether the application should terminate. For compatibility reasons, a return value of NO is equivalent to NSTerminateCancel, and a return value of YES is equivalent to NSTerminateNow.

Discussion

This method is called after the application’s Quit menu item has been selected, or after the terminate: method has been called. Generally, you should return NSTerminateNow to allow the termination to complete, but you can cancel the termination process or delay it somewhat as needed. For example, you might delay termination to finish processing some critical data but then terminate the application as soon as you are done by calling the replyToApplicationShouldTerminate: method.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationShouldTerminateAfterLastWindowClosed:

Invoked when the user closes the last window the application has open.

- (BOOL)applicationShouldTerminateAfterLastWindowClosed:(NSApplication *)theApplication
Parameters
theApplication

The application object whose last window was closed.

Return Value

NO if the application should not be terminated when its last window is closed; otherwise, YES to terminate the application.

Discussion

The application sends this message to your delegate when the application’s last window is closed. It sends this message regardless of whether there are still panels open. (A panel in this case is defined as being an instance of NSPanel or one of its subclasses.)

If your implementation returns NO, control returns to the main event loop and the application is not terminated. If you return YES, your delegate’s applicationShouldTerminate: method is subsequently invoked to confirm that the application should be terminated.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillBecomeActive:

Sent by the default notification center immediately before the application becomes active.

- (void)applicationWillBecomeActive:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillBecomeActiveNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillFinishLaunching:

Sent by the default notification center immediately before the application object is initialized.

- (void)applicationWillFinishLaunching:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillFinishLaunchingNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillHide:

Sent by the default notification center immediately before the application is hidden.

- (void)applicationWillHide:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillHideNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSApplication.h

applicationWillResignActive:

Sent by the default notification center immediately before the application is deactivated.

- (void)applicationWillResignActive:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillResignActiveNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillTerminate:

Sent by the default notification center immediately before the application terminates.

- (void)applicationWillTerminate:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillTerminateNotification. Calling the object method of this notification returns the NSApplication object itself.

Discussion

Your delegate can use this method to perform any final cleanup before the application terminates.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillUnhide:

Sent by the default notification center immediately after the application is unhidden.

- (void)applicationWillUnhide:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillUnhideNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSApplication.h

applicationWillUpdate:

Sent by the default notification center immediately before the application object updates its windows.

- (void)applicationWillUpdate:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSApplicationWillUpdateNotification. Calling the object method of this notification returns the NSApplication object itself.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
See Also
Declared In
NSApplication.h