NSApplicationDelegate Protocol Reference

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.

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.

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.

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:.)

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.

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.

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.

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.

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.

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.

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:.)

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.

Discussion

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

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.

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.

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.

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.

Discussion

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