NSApplicationDelegate Protocol Reference

Instance Methods

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.

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

See Also

• – application:openFileWithoutUI:
• – application:openTempFile:
• – applicationOpenUntitledFile:

Related Sample Code

• TextSizingExample

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.

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.

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.

See Also

• – application:openFile:
• – application:openTempFile:
• – applicationOpenUntitledFile:
• – application:printFile:

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.

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.

See Also

• – application:openFile:
• – application:openFileWithoutUI:
• – applicationOpenUntitledFile:

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.

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.

See Also

• – application:openFileWithoutUI:

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.

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.

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.

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.

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.

See Also

• – applicationDidFinishLaunching:
• – applicationDidResignActive:
• – applicationWillBecomeActive:

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.

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

See Also

• – finishLaunching (NSApplication)
• – applicationWillFinishLaunching:
• – applicationDidBecomeActive:
• – application:openFile:

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.

See Also

• – applicationWillHide:
• – applicationDidHide:
• – unhide: (NSApplication)

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.

See Also

• – applicationDidBecomeActive:
• – applicationWillResignActive:

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.

See Also

• – applicationDidHide:
• – applicationWillUnhide:
• – unhide: (NSApplication)

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.

See Also

• – applicationWillUpdate:
• – updateWindows (NSApplication)

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.

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.

applicationOpenUntitledFile:

Tells the delegate to open an untitled file.

- (BOOL)applicationOpenUntitledFile:(NSApplication *)theApplication

Parameters

theApplication

The application object associated with the delegate.

Discussion

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

See Also

• – application:openFile:
• – application:openFileWithoutUI:
• – application:openTempFile:

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.

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.

applicationShouldOpenUntitledFile:

Invoked immediately before opening an untitled file.

- (BOOL)applicationShouldOpenUntitledFile:(NSApplication *)sender

Parameters

sender

The application object associated with the delegate.

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.

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.

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.

See Also

• – terminate: (NSApplication)
• – applicationShouldTerminateAfterLastWindowClosed:
• – applicationWillTerminate:

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.

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.

See Also

• – terminate:
• – applicationShouldTerminate:

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.

See Also

• – applicationDidBecomeActive:
• – applicationWillFinishLaunching:
• – applicationWillResignActive:

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.

See Also

• – applicationDidFinishLaunching:
• – applicationWillBecomeActive:
• – finishLaunching (NSApplication)

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.

See Also

• – applicationDidHide:
• – hide: (NSApplication)

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.

See Also

• – applicationWillBecomeActive:
• – applicationDidResignActive:

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.

See Also

• – applicationShouldTerminate:
• – terminate: (NSApplication)

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.

See Also

• – unhide: (NSApplication)
• – applicationDidUnhide:
• – applicationWillHide:

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.

See Also

• – applicationDidUpdate:
• – updateWindows (NSApplication)