Next Page >

Hide TOC

Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

NSApplication

Inherits from	NSResponder : NSObject
Implements	NSCoding (NSResponder)
Package	com.apple.cocoa.application
Companion guides	Application Architecture Overview Notification Programming Topics for Cocoa Sheet Programming Topics for Cocoa System Services

Class at a Glance

An NSApplication object manages an application’s main event loop in addition to resources used by all of that application’s objects.

Principal Attributes

Delegate
Key window
Display context
List of windows
Main window

Commonly Used Methods

keyWindow: Returns an NSWindow representing the key window.
mainWindow: Returns the application’s main window.
registerServicesMenuTypes: Specifies which services are valid for this application.
runModalForWindow: Runs a modal event loop for the specified NSWindow.

Overview

The NSApplication class provides the central framework for your application’s execution. Every application must have exactly one instance of NSApplication (or a subclass of NSApplication). Your program’s main() function should create this instance by invoking the sharedApplication class method. After creating the NSApplication object, the main() function should load your application’s main nib file and then start the event loop by sending the NSApplication object a run message. If you create an Application project in Xcode, this main() function is created for you. The main() function Xcode creates begins by calling a function named NSApplicationMain().

The sharedApplication class method initializes the display environment and connects your program to the window server and the display server. The NSApplication object maintains a list of all the NSWindows the application uses, so it can retrieve any of the application’s NSViews. sharedApplication only performs the initialization once; if you invoke it more than once, it simply returns the NSApplication object it created previously.

NSApplication performs the important task of receiving events from the window server and distributing them to the proper NSResponders. NSApplication.sharedApplication() translates an event into an NSEvent object, then forwards the NSEvent to the affected NSWindow object. All keyboard and mouse events go directly to the NSWindow associated with the event. The only exception to this rule is if the Command key is pressed when a key-down event occurs; in this case, every NSWindow has an opportunity to respond to the event. When an NSWindow receives an NSEvent from NSApplication.sharedApplication(), it distributes it to the objects in its view hierarchy.

NSApplication is also responsible for dispatching certain Apple events received by the application. For example, the Mac OS sends Apple events to your application at various times, such as when the application is launched or reopened. NSApplication installs Apple event handlers to handle these events by sending a message to the appropriate object. You can also use the NSAppleEventManager class to register your own Apple event handlers. The applicationWillFinishLaunching method is generally the best place to do so. For more information on how events are handled and how you can modify the default behavior, including information on working with Apple events in scriptable applications, see “How Cocoa Applications Handle Apple Events.” in Scriptable Application Programming Guide for Cocoa.

The NSApplication class sets up autorelease pools (instances of the NSAutoreleasePool class) during initialization and inside the event loop—specifically, within its initialization (or sharedApplication) and run methods. Similarly, the methods the Application Kit adds to NSBundle employ autorelease pools during the loading of nib files. These autorelease pools aren’t accessible outside the scope of the respective NSApplication and NSBundle methods. Typically, an application creates objects either while the event loop is running or by loading objects from nib files, so this lack of access usually isn’t a problem. However, if you do need to use Cocoa classes within the main() function itself (other than to load nib files or to instantiate NSApplication), you should create an autorelease pool before using the classes and then release the pool when you’re done. For more information, see NSAutoreleasePool in the Foundation Framework Reference.

The Delegate and Notifications

You can assign a delegate to NSApplication.sharedApplication(). The delegate responds to certain messages on behalf of NSApplication.sharedApplication(). Some of these messages, such as applicationOpenFile, ask the delegate to perform an action. Another message, applicationShouldTerminate, lets the delegate determine whether the application should be allowed to quit. The NSApplication class sends these messages directly to its delegate.

The NSApplication.sharedApplication() also posts notifications to the application’s default notification center. Any object may register to receive one or more of the notifications posted by NSApplication.sharedApplication() by sending the message addObserver to the default notification center (an instance of the NSNotificationCenter class). The delegate of NSApplication.sharedApplication() is automatically registered to receive these notifications if it implements certain delegate methods. For example, NSApplication.sharedApplication() posts notifications when it is about to be done launching the application and when it is done launching the application (ApplicationWillFinishLaunchingNotification and ApplicationDidFinishLaunchingNotification). The delegate has an opportunity to respond to these notifications by implementing the methods applicationWillFinishLaunching and applicationDidFinishLaunching. If the delegate wants to be informed of both events, it implements both methods. If it needs to know only when the application is finished launching, it implements only applicationDidFinishLaunching.

System Services

NSApplication interacts with the system services architecture to provide services to your application through the Services menu.

Subclassing Notes

You rarely should find a real need to create a custom NSApplication subclass. Unlike some object-oriented libraries, Cocoa does not require you to create a custom application class to customize application behavior. Instead it gives you many other ways to customize an application. This section discusses both some of the possible reasons to subclass NSApplication and some of the reasons not to subclass NSApplication.

To use a custom subclass of NSApplication, simply send sharedApplication to your subclass rather than directly to NSApplication. If you create your application in Xcode, you can accomplish this by setting your custom application class to be the principal class. In Xcode, double-click the application target in the Groups and Files list to open the Info window for the target. Then display the Properties pane of the window and replace “NSApplication” in the Principal Class field with the name of your custom class. TheNSApplicationMain function sends sharedApplication to the principal class to obtain the global application instance (NSApp)—which in this case will be an instance of your custom subclass of NSApplication.

Methods to Override

Generally, you subclass NSApplication to provide your own special responses to messages that are routinely sent to the global application object (NSApplication.sharedApplication()). NSApplication does not have primitive methods in the sense of methods that you must override in your subclass. Here are four methods that are possible candidates for overriding:

Override run if you want the application to manage the main event loop differently than it does by default. (This a critical and complex task, however, that you should only attempt with good reason.)
Override sendEvent if you want to change how events are dispatched or perform some special event processing.
Override requestUserAttention if you want to modify how your application attracts the attention of the user (for example, offering an alternative to the bouncing application icon in the Dock).
Override targetForAction to substitute another object for the target of an action message.

Special Considerations

The global application object uses autorelease pools in its run method; if you override this method, you’ll need to create your own autorelease pools.

Do not override sharedApplication. The default implementation, which is essential to application behavior, is too complex to duplicate on your own.

Alternatives to Subclassing

NSApplication defines over twenty delegation methods that offer opportunities for modifying specific aspects of application behavior. Instead of making a custom subclass of NSApplication, your application delegate may be able to implement one or more of these methods to accomplish your design goals.

In general, a better design than subclassing NSApplication is to put the code that expresses your application’s special behavior into a number of custom objects called controllers. (Controller objects usually inherit directly from NSObject.) Methods defined in your controllers can be invoked from a small dispatcher object without being closely tied to the global application object.

Tasks

Constructors

Creating and Initializing an NSApplication

Getting Information About the Framework

Changing the Active Application

Running the Event Loop

Getting, Removing, and Posting Events

Managing Sheets

Managing Windows

Hiding All Windows

Setting the Application’s Icon

Getting the Main Menu

Managing the Window Menu

Managing the Services Menu

Showing Standard Panels

Displaying Help

Sending Action Messages

Getting the Display Context

Reporting an Exception

Terminating the Application

Assigning a Delegate

Handling User Attention Requests

Loading Nib Files

Opening files

Printing

Supplying a dock menu

Activating, launching, and updating an application

Hiding and unhiding an application

Terminating an application

Handling errors

Constructors

NSApplication

public NSApplication()

Discussion

The constructor for the NSApplication object. You should not invoke this constructor directly; instead, use the sharedApplication method.

Static Methods

appkitVersionNumber

Returns the version number for the Application Kit framework.

public static double appkitVersionNumber()

beep

Plays the system beep.

public static void beep()

Discussion

A user can select a sound to be played. On a Macintosh computer, for example, the user chooses a sound with the Sound control panel.

The implementation of this method calls the C function NSBeep.

loadNibFromBundle

Unarchives the contents of the nib file named fileName in aBundle, using owner as the nib file’s owner (shown as “File’s Owner” in Interface Builder).

public static boolean loadNibFromBundle(NSBundle aBundle, String fileName, Object owner)

Discussion

The method first looks for the nib file in the language-specific “.lproj” directory of aBundle. If fileName isn’t there, this method looks for a non-localized resource in the immediate bundle directory. Returns true upon success, or false if the specified nib file couldn’t be loaded.

loadNibNamed

Unarchives the contents of the nib file named aNibName, using owner as the nib file’s owner (shown as “File’s Owner” in Interface Builder).

public static boolean loadNibNamed(String aNibName, Object owner)

Discussion

The argument aNibName need not include the “.nib” extension. If there’s a bundle for the class of owner, this method looks in that bundle for aNibName; otherwise, it looks in the main bundle. Returns true upon success, or false if the specified nib file couldn’t be loaded.

sharedApplication

Returns the NSApplication instance, creating it if it doesn’t exist yet.

public static NSApplication sharedApplication()

Discussion

This method also makes a connection to the window server and completes other initialization. Your program should invoke this method as one of the first statements in main(); this invoking is done for you if you create your application with Xcode. To retrieve the NSApplication instance after it has been created, invoke this method.

showSystemInfoPanel

Deprecated. Do not use.

public static void showSystemInfoPanel(NSDictionary aDictionary)

Instance Methods

abortModal

Aborts the event loop started by runModalForWindow or runModalSession.

public void abortModal()

Discussion

When stopped with this method, runModalForWindow and runModalSession return RunAbortedResponse.

abortModal must be used instead of stopModal or stopModalWithCode when you need to stop a modal event loop from anywhere other than a callout from that event loop. In other words, if you want to stop the loop in response to a user’s actions within the modal window, use stopModal; otherwise, use abortModal. For example, use abortModal when running in a different thread from the Application Kit’s main thread or when responding to an NSTimer that you have added to the ModalPanelRunLoopMode mode of the default NSRunLoop.

activateContextHelpMode

Places the receiver in context-sensitive help mode.

public void activateContextHelpMode(Object sender)

Discussion

In this mode, the cursor becomes a question mark, and help appears for any user interface item the user clicks.

Most applications don’t use this method. Instead, applications enter context-sensitive mode when the user presses the Help key. Applications exit context-sensitive help mode upon the first event after a help window is displayed.

activateIgnoringOtherApps

Makes the receiver the active application.

public void activateIgnoringOtherApps(boolean flag)

Discussion

If flag is false, the application is activated only if no other application is currently active. If flag is true, the application activates regardless.

The flag is normally set to false. When the Finder launches an application, using a value of false for flag allows the application to become active if the user waits for it to launch, but the application remains unobtrusive if the user activates another application. Regardless of the setting of flag, there may be a time lag before the application activates—you should not assume the application will be active immediately after sending this message.

You rarely need to invoke this method. Under most circumstances, the Application Kit takes care of proper activation. However, you might find this method useful if you implement your own methods for interapplication communication.

You don’t need to send this message to make one of the application’s NSWindows key. When you send a makeKeyWindow message to an NSWindow, you ensure the NSWindow will be the key window when the application is active.

addWindowsItem

Adds an item to the Window menu for aWindow.

public void addWindowsItem(NSWindow aWindow, String aString, boolean isFilename)

Discussion

If isFilename is false, aString appears literally in the menu. If isFilename is true, aString is assumed to be a converted pathname with the name of the file preceding the path (the way NSWindow’s setTitleWithRepresentedFilename method shows a title). If an item for aWindow already exists in the Window menu, this method has no effect. You rarely invoke this method because an item is placed in the Window menu for you whenever an NSWindow’s title is set.

applicationIconImage

Returns the NSImage used for the receiver’s icon.

public NSImage applicationIconImage()

arrangeInFront

Arranges windows listed in the Window menu in front of all other windows.

public void arrangeInFront(Object sender)

Discussion

Windows associated with the application but not listed in the Window menu are not ordered to the front.

beginModalSessionForWindow

Sets up a modal session with the NSWindow aWindow and returns an NSModalSession structure representing the session.

public NSModalSession beginModalSessionForWindow(NSWindow aWindow)

Discussion

In a modal session, the application receives mouse events only if they occur in aWindow. The NSWindow is made key and ordered to the front.

The beginModalSessionForWindow method only sets up the modal session. To actually run the session, use runModalSession. beginModalSessionForWindow should be balanced by endModalSession. Make sure these two messages are sent within the same exception-handling scope. That is, if you send beginModalSessionForWindow inside an NS_DURING construct, you must send endModalSession before NS_ENDHANDLER.

If an exception is thrown, beginModalSessionForWindow arranges for proper cleanup. Do not use NS_DURING constructs to send an endModalSession message in the event of an exception.

A loop using these methods is similar to a modal event loop run with runModalForWindow, except the application can continue processing between method invocations.

This method has been deprecated. Use beginSheet instead.

public NSModalSession beginModalSessionForWindow(NSWindow theWindow, NSWindow docWindow)

beginSheet

Starts a document modal session.

public void beginSheet(NSWindow sheet, NSWindow docWindow, Object modalDelegate, NSSelector didEndSelector, Object contextInfo)

Discussion

The didEndSelector method is optional. If implemented by the modalDelegate, this method is invoked after the modal session has ended and is passed a return code and caller specified in contextInfo. didEndSelector should have the following signature:

public void sheetDidEnd (NSWindow sheet, int returnCode, Object  contextInfo)

Use this method in cases where you do not need to do any additional background processing while your sheet runs. This method consumes only enough CPU time to process events and dispatch them to the action methods associated with the sheet. If you want to perform additional background processing, use runModalSession together with an NSModalSession object instead.

Discussion

The didEndSelector method is optional. If implemented by the modalDelegate, this method is invoked after the modal session has ended.

cancelUserAttentionRequest

Cancels a previous user attention request.

public void cancelUserAttentionRequest(int request)

Discussion

request is the return value from a previous call to requestUserAttention. A request is also canceled automatically by user activation of the application.

changeWindowsItem

Changes the item for aWindow in the Window menu to aString.

public void changeWindowsItem(NSWindow aWindow, String aString, boolean isFilename)

Discussion

If aWindow doesn’t have an item in the Window menu, this method adds the item. If isFilename is false, aString appears literally in the menu. If isFilename is true, aString is assumed to be a converted pathname with the file’s name preceding the path (the way NSWindow’s setTitleWithRepresentedFilename places a title).

context

Returns the receiver’s display context.

public NSGraphicsContext context()

currentEvent

Returns the current event, the last event the receiver retrieved from the event queue.

public NSEvent currentEvent()

Discussion

NSApplication.sharedApplication() receives events and forwards the current event to the affected NSWindow object, which then distributes it to the objects in its view hierarchy.

deactivate

Deactivates the receiver.

public void deactivate()

Discussion

Normally, you shouldn’t invoke this method—the Application Kit is responsible for proper deactivation.

delegate

Returns the receiver’s delegate.

public Object delegate()

discardEventsMatchingMask

Removes all events matching mask and generated before lastEvent from the event queue.

public void discardEventsMatchingMask(int mask, NSEvent lastEvent)

Discussion

Typically, you send this message to an NSWindow rather than to NSApplication.sharedApplication().

mask can contain these constants:

NSEvent.LeftMouseDownMask
NSEvent.LeftMouseUpMask
NSEvent.RightMouseDownMask
NSEvent.RightMouseUpMask
NSEvent.MouseMovedMask
NSEvent.LeftMouseDraggedMask
NSEvent.RightMouseDraggedMask
NSEvent.MouseEnteredMask
NSEvent.MouseExitedMask
NSEvent.KeyDownMask
NSEvent.KeyUpMask
NSEvent.FlagsChangedMask
NSEvent.PeriodicMask
NSEvent.CursorUpdateMask
NSEvent.AnyEventMask

Use this method to ignore events that occur before a particular kind of event. For example, suppose your application has a tracking loop that you exit when the user releases the mouse button, and you want to discard all events that occurred during that loop. You use NSEvent.AnyEventMask as the mask argument and pass the mouse-up event as the lastEvent argument. Passing the mouse-up event as lastEvent ensures that any events that might have occurred after the mouse-up event (that is, that appear in the queue after the mouse-up event) don’t get discarded.

This method can also be called in subthreads. Events posted in subthreads bubble up in the main thread event queue.

endModalSession

Finishes a modal session.

public void endModalSession(NSModalSession session)

Discussion

session should be the return value from a previous invocation of beginModalSessionForWindow.

endSheet

Ends a document modal session by specifying the sheet window, sheet.

public void endSheet(NSWindow sheet)

Ends a document modal session by specifying the sheet window, sheet.

public void endSheet(NSWindow sheet, int returnCode)

Discussion

Also passes along a returnCode to the delegate.

finishLaunching

Activates the receiver, opens any files specified by the NSOpen user default, and unhighlights the application’s icon.

public void finishLaunching()

Discussion

The run method invokes this method before it starts the event loop. When this method begins, it posts an ApplicationWillFinishLaunchingNotification to the default notification center. If you override finishLaunching, the subclass method should invoke the superclass method.

hide

Hides all the receiver’s windows, and the next application in line is activated.

public void hide(Object sender)

Discussion

This method is usually invoked when the user chooses Hide in the application’s main menu. When this method begins, it posts an ApplicationWillHideNotification to the default notification center. When it completes successfully, it posts an ApplicationDidHideNotification.

hideOtherApplications

Hides all applications, except the receiver.

public void hideOtherApplications(Object sender)

isActive

Returns true if this is the active application, false otherwise.

public boolean isActive()

isHidden

Returns true if the receiver is hidden, false otherwise.

public boolean isHidden()

isRunning

Returns true if the main event loop is running, false otherwise.

public boolean isRunning()

Discussion

false means the stop method was invoked.

keyWindow

Returns the key window, the NSWindow that receives keyboard events.

public NSWindow keyWindow()

Discussion

This method returns null if there is no key window, if the application’s nib file hasn’t finished loading yet, or if the receiver is not active.

mainMenu

Returns the receiver’s main menu.

public NSMenu mainMenu()

mainWindow

Returns the main window.

public NSWindow mainWindow()

Discussion

This method returns null if there is no main window, if the application’s nib file hasn’t finished loading, if the receiver is not active, or if the application is hidden.

makeWindowsPerform

Sends the aSelector message to each NSWindow in the application in turn until one returns a value other than null.

public NSWindow makeWindowsPerform(NSSelector aSelector, boolean flag)

Discussion

Returns that NSWindow, or null if all NSWindows returned null for aSelector.

If flag is true, the aSelector message is sent to each of the window server’s on-screen windows, going in z-order, until one returns non-nil. A minimized window is not considered to be onscreen for this check. If flag is false, the message is sent to all windows in NSApplication.sharedApplication()’s window list, regardless of whether they are on-screen or not. This order is unspecified.

The method designated by aSelector can’t take any arguments.

miniaturizeAll

Miniaturizes all the receiver’s windows.

public void miniaturizeAll(Object sender)

modalWindow

Returns the modal window that the receiver is displaying.

public NSWindow modalWindow()

Discussion

If the application isn’t displaying a modal window, this method returns null.

This method does not return a sheet window. If you need access to a sheet window, use NSWindow’s attachedSheet.

nextEventMatchingMask

Returns the next event matching mask, or null if no such event is found before the expiration date specified by expiration.

public NSEvent nextEventMatchingMask(int mask, NSDate expiration, String mode, boolean flag)

Discussion

A value of null for expiration is equivalent to distantPast. If flag is true, the event is removed from the queue. See the method description for discardEventsMatchingMask for a list of the possible values for mask.

The mode argument names an NSRunLoop mode that determines what other ports are listened to and what timers may fire while NSApplication.sharedApplication() is waiting for the event. The possible modes available in the Application Kit are:

NSRunLoop.DefaultRunLoopMode
NSApplication.EventTrackingRunLoopMode
NSApplication.ModalPanelRunLoopMode

Events that are skipped are left in the queue.

You can use this method to short circuit normal event dispatching and get your own events. For example, you may want to do this in response to a mouse-down event in order to track the mouse while its button is down. In this case, you would set mask to accept mouse-dragged or mouse-up events and use the NSApplication.EventTrackingRunLoopMode.

orderFrontCharacterPalette

Opens the character palette.

public void orderFrontCharacterPalette(Object sender)

Availability

Available in Mac OS X v10.3 and later.

orderFrontColorPanel

Brings up the color panel, an instance of NSColorPanel.

public void orderFrontColorPanel(Object sender)

Discussion

If the NSColorPanel does not exist yet, it creates one. This method is typically invoked when the user chooses Colors from a menu.

orderFrontStandardAboutPanel

Displays a standard About window.

public void orderFrontStandardAboutPanel(Object sender)

Discussion

This method calls orderFrontStandardAboutPanelWithOptions with a null argument. See orderFrontStandardAboutPanelWithOptions for a description of what’s displayed.

orderFrontStandardAboutPanelWithOptions

Displays a standard About window with information from optionsDictionary.

public void orderFrontStandardAboutPanelWithOptions(NSDictionary optionsDictionary)

Discussion

The following strings are keys that can occur in optionsDictionary:

"Credits": An NSAttributedString displayed in the info area of the panel. If not specified, this method then looks for a file named “Credits.html”, “Credits.rtf”, and “Credits.rtfd”, in that order, in the bundle returned by the NSBundle static method mainBundle. The first file found is used. If none is found, the info area is left blank.
"ApplicationName": A String displayed as the application’s name. If not specified, this method then uses the value of CFBundleName (localizable). If neither is found, this method uses NSProcessInfo.processInfo().processName().
"ApplicationIcon": An NSImage displayed as the application’s icon. If not specified, this method then looks for an image named “NSApplicationIcon”, using NSImage.imageNamed("ApplicationIcon"). If neither is available, this method uses the generic application icon.
"Version": A String with the build version number of the application (“58.4”), displayed as “(v58.4)”. If not specified, obtain from the CFBundleVersion key in infoDictionary; if not specified, leave blank (the “(v)” is not displayed).
"Copyright": A String with a line of copyright information. If not specified, this method then looks for the value of HumanReadableCopyright in the localized version infoDictionary. If neither is available, this method leaves the space blank.
"ApplicationVersion": A String with the application version (“Mac OS X”, “3”, “WebObjects 4.5”, “AppleWorks 6”,...). If not specified, obtain from the CFBundleShortVersionString key in infoDictionary. If neither is available, the build version, if available, is printed alone, as “Version x.x”.

postEvent

Adds anEvent to the receiver’s event queue.

public void postEvent(NSEvent anEvent, boolean flag)

Discussion

If flag is true, the event is added to the front of the queue; otherwise the event is added to the back of the queue.

This method can also be called in subthreads. Events posted in subthreads bubble up in the main thread event queue.

preventWindowOrdering

Suppresses the usual window ordering in handling the most recent mouse-down event.

public void preventWindowOrdering()

Discussion

This method is only useful for mouse-down events when you want to prevent the window that receives the event from being ordered to the front.

registerServicesMenuTypes

Registers the pasteboard types the receiver can send and receive in response to service requests.

public void registerServicesMenuTypes(NSArray sendTypes, NSArray returnTypes)

Discussion

If the receiver has a Services menu, a menu item is added for each service provider that can accept one of the specified sendTypes or return one of the specified returnTypes. You should typically invoke this method at application startup time or when an object that can use services is created. You can invoke it more than once—its purpose is to ensure there is a menu item for every service the application can use. The event-handling mechanism will dynamically enable the individual items to indicate which services are currently appropriate. All the NSResponders in your application (typically NSViews) should register every possible type they can send and receive by sending this message to NSApplication.sharedApplication().

removeWindowsItem

Removes the Window menu item for aWindow.

public void removeWindowsItem(NSWindow aWindow)

Discussion

This method doesn’t prevent the item from being automatically added again. Use NSWindow’s setExcludedFromWindowsMenu method if you want the item to remain excluded from the Window menu.

replyToApplicationShouldTerminate

If an application delegate returns TerminateLater to applicationShouldTerminate, this method must be called with shouldTerminate passed as true or false once the application decides if it can terminate.

public replyToApplicationShouldTerminate(boolean shouldTerminate)

replyToOpenOrPrint

Handles errors that might occur when the user attempts to open or print files.

public void replyToOpenOrPrint(int reply)

Discussion

Delegates should invoke this method if an error is encountered in the applicationOpenFiles or applicationPrintFiles delegate methods. Possible values for reply are described in “Constants.”

Availability

Available in Mac OS X v10.3 and later.

reportException

Logs anException .

public void reportException(Throwable anException)

Discussion

This method does not throw anException. Use it inside of an exception handler to record that the exception occurred.

requestUserAttention

Starts a user attention request.

public int requestUserAttention(int requestType)

Discussion

requestType is one of the values described in “Constants.” Activating the application cancels the user attention request. A spoken notification will occur if spoken notifications are enabled. Sending requestUserAttention to an application that is already active has no effect.

If the inactive application presents a modal panel, this method will be invoked with UserAttentionRequestCritical automatically. The modal panel is not brought to the front for an inactive application.

The value returned by this method can be used to manually cancel a request by passing it as the parameter to cancelUserAttentionRequest.

run

Starts the main event loop.

public void run()

Discussion

The loop continues until a stop or terminate message is received. Upon each iteration through the loop, the next available event from the window server is stored and then dispatched by sending it to NSApplication.sharedApplication() using sendEvent.

After creating the NSApplication object, the main function should load your application’s main nib file and then start the event loop by sending the NSApplication object a run message.If you create an Cocoa application project in Xcode, this main function is implemented for you.

runModalForWindow

Starts a modal event loop for aWindow.

public int runModalForWindow(NSWindow aWindow)

Discussion

Until the loop is broken by a stopModal, stopModalWithCode, or abortModal message, the application won’t respond to any mouse, keyboard, or window-close events unless they’re associated with aWindow. If stopModalWithCode is used to stop the modal event loop, this method returns the argument passed to stopModalWithCode. If stopModal is used, it returns the constant RunStoppedResponse. If abortModal is used, it returns the constant RunAbortedResponse.

The window aWindow is placed on the screen using NSWindow’s center method, if not already visible, and made key as a result of the runModalForWindow message. Do not send NSWindow’s makeKeyAndOrderFront to aWindow.

runModalSession

Runs a modal session represented by session, as defined in a previous invocation of beginModalSessionForWindow.

public int runModalSession(NSModalSession session)

Discussion

A loop that uses this method is similar in some ways to a modal event loop run with runModalForWindow, except with this method your code can do some additional work between method invocations. When you invoke this method, events for the NSWindow of this session are dispatched as normal. This method returns when there are no more events. You must invoke this method frequently enough in your loop that the window remains responsive to events. However, you should not invoke this method in a tight loop because it returns immediately if there are no events, and consequently you could end up polling for events rather than blocking.

Typically, you use this method in situations where you want to do some additional background processing while the modal loop runs. For example, while processing a large data set, you might want to use a modal dialog to display progress and give the user a chance to cancel the operation. If you want to display a modal dialog and do not need to do any additional work in parallel, use runModalForWindow instead. When there are no pending events, that method waits idly instead of consuming CPU time.

If the modal session was not stopped, this method returns RunContinuesResponse. At this point, your application can do some work before the next invocation of runModalSession (as indicated in the example’s doSomeWork call). If stopModal was invoked as the result of event processing, runModalSession returns RunStoppedResponse. If stopModalWithCode was invoked, this method returns the value passed to stopModalWithCode. If abortModal was invoked, this method returns RunAbortedResponse.

The window is placed on the screen and made key as a result of the runModalSession message. Do not send a separate makeKeyAndOrderFront message.

runPageLayout

Displays the receiver’s page layout panel, an instance of NSPageLayout.

public void runPageLayout(Object sender)

Discussion

If the NSPageLayout instance does not exist, this method creates one. This method is typically invoked when the user selects Page Layout from the application’s menu.

sendActionToTargetFromSender

Sends the message anAction to aTarget.

public boolean sendActionToTargetFromSender(NSSelector anAction, Object aTarget, Object sender)

Discussion

If anAction is NULL, false is returned. If aTarget is null, NSApplication.sharedApplication() looks for an object that can respond to the message—that is, an object that implements a method matching anAction. It begins with the first responder of the key window. If the first responder can’t respond, it tries the first responder’s next responder and continues following next responder links up the responder chain. If none of the objects in the key window’s responder chain can handle the message, NSApplication.sharedApplication() attempts to send the message to the key window’s delegate.

If the delegate doesn’t respond and the main window is different from the key window, NSApplication.sharedApplication() begins again with the first responder in the main window. If objects in the main window can’t respond, NSApplication.sharedApplication() attempts to send the message to the main window’s delegate. If still no object has responded, NSApplication.sharedApplication() tries to handle the message itself. If NSApplication.sharedApplication() can’t respond, it attempts to send the message to its own delegate.

Returns true if the action is successfully sent, otherwise returns false.

sendEvent

Dispatches anEvent to other objects.

public void sendEvent(NSEvent anEvent)

Discussion

You rarely invoke sendEvent directly, although you might want to override this method to perform some action on every event. sendEvent messages are sent from the main event loop (the run method). sendEvent is the method that dispatches events to the appropriate responders—NSApplication.sharedApplication() handles application events, the NSWindow indicated in the event record handles window-related events, and mouse and key events are forwarded to the appropriate NSWindow for further dispatching.

servicesMenu

Returns the Services menu, or null if no Services menu has been created.

public NSMenu servicesMenu()

servicesProvider

Returns the object that provides the services the receiver advertises in the Services menu of other applications.

public Object servicesProvider()

setApplicationIconImage

Sets the receiver’s icon to anImage. This method updates the dock application tile. anImage will be scaled as necessary to fit the tile.

public void setApplicationIconImage(NSImage anImage)

Discussion

The following code sample shows how to get the application’s icon image and then restore the dock’s image:

myImage = NSImage.imageNamed("NSApplicationIcon");

NSApplication.sharedApplication().setApplicationIconImage(myImage);

setDelegate

Makes anObject the receiver’s delegate.

public void setDelegate(Object anObject)

Discussion

The messages a delegate can expect to receive are listed at the end of this specification. The delegate doesn’t need to implement all the methods.

setMainMenu

Makes aMenu the receiver’s main menu.

public void setMainMenu(NSMenu aMenu)

setServicesMenu

Makes aMenu the receiver’s Services menu.

public void setServicesMenu(NSMenu aMenu)

setServicesProvider

Registers the object aProvider as the service provider.

public void setServicesProvider(Object aProvider)

Discussion

The service provider is an object that performs all services the application provides to other applications. When another application requests a service from the receiver, it sends the service request to aProvider. Service requests can arrive immediately after the service provider is set, so invoke this method only when your application is ready to receive requests.

setWindowsMenu

Makes aMenu the receiver’s Window menu.

public void setWindowsMenu(NSMenu aMenu)

setWindowsNeedUpdate

Sets whether the receiver’s windows need updating when the receiver has finished processing the current event, depending on the Boolean value passed in place of flag.

public void setWindowsNeedUpdate(boolean flag)

Discussion

This method is especially useful for making sure menus are updated to reflect changes not initiated by user actions, such as messages received from remote objects.

showHelp

If your project is properly registered, and the necessary keys have been set in the property list, this method launches Help Viewer and displays the first page of your application’s help book.

public void showHelp(Object sender)

Discussion

For information on how to set up your project to take advantage of having Help Viewer display your help book, see “Specifying the Comprehensive Help File”.

stop

Stops the main event loop.

public void stop(Object sender)

Discussion

This method will break the flow of control out of the run method, thereby returning to the main() function. A subsequent run message will restart the loop.

If this method is invoked during a modal event loop, it will break that loop but not the main event loop.

stopModal

Stops a modal event loop.

public void stopModal()

Discussion

This method should always be paired with a previous invocation of runModalForWindow or beginModalSessionForWindow. When runModalForWindow is stopped with this method, it returns RunStoppedResponse. This method stops the loop only if it’s executed by code responding to an event. If you need to stop a runModalForWindow loop outside of one of its event callbacks (for example, a method repeatedly invoked by an NSTimer object or a method running in a different thread), use the abortModal method.

stopModalWithCode

Like stopModal, except the argument returnCode allows you to specify the value runModalForWindow will return.

public void stopModalWithCode(int returnCode)

targetForAction

Returns the object that receives the action message aSelector.

public Object targetForAction(NSSelector aSelector)

Discussion

If aSelector is NULL, null is returned.

targetForActionToFrom

Finds an object that can receive the message specified by the selector anAction.

public Object targetForActionToFrom(NSSelector anAction, Object aTarget, Object sender)

Discussion

If anAction is NULL, null is returned. If aTarget is null, NSApplication.sharedApplication() looks for an object that can respond to the message—that is, an object that implements a method matching anAction. If aTarget is not null, aTarget is returned. The search begins with the first responder of the key window. If the first responder does not handle the message, it tries the first responder’s next responder and continues following next responder links up the responder chain. If none of the objects in the key window’s responder chain can handle the message, NSApplication.sharedApplication() asks the key window’s delegate whether it can handle the message.

If the delegate cannot handle the message and the main window is different from the key window, NSApplication.sharedApplication() begins searching again with the first responder in the main window. If objects in the main window cannot handle the message, NSApplication.sharedApplication() tries the main window’s delegate. If it cannot handle the message, NSApplication.sharedApplication() asks itself. If NSApplication.sharedApplication() doesn’t handle the message, it asks the application delegate. If there is no object capable of handling the message, null is returned.

terminate

Terminates the receiver.

public void terminate(Object sender)

Discussion

This method is typically invoked when the user chooses Quit or Exit from the application’s menu. Each use of terminate invokes applicationShouldTerminate to notify the delegate that the application will terminate. If applicationShouldTerminate returns false, control is returned to the main event loop, and the application isn’t terminated. Otherwise, the document controller of the application (if one exists) is asked to check its documents and, if there are unsaved changes, ask the user to save those changes. Then, this method posts an ApplicationWillTerminateNotification to the default notification center. Don’t put final cleanup code in your application’s main() function—it will never be executed. If cleanup is necessary, have the delegate respond to applicationWillTerminate and perform cleanup in that method.

tryToPerform

Dispatches action messages.

public boolean tryToPerform(NSSelector aSelector, Object anObject)

Discussion

If aSelector is NULL, false is returned. The receiver tries to perform the method aSelector using its inherited NSResponder method tryToPerform. If the receiver doesn’t perform aSelector, the delegate is given the opportunity to perform it. If either the receiver or its delegate accepts aSelector, this method returns true. Otherwise, it returns false.

unhide

Restores hidden windows to the screen and makes the receiver active.

public void unhide(Object sender)

Discussion

Invokes unhideWithoutActivation.

unhideAllApplications

Unhides all applications, including the receiver.

public void unhideAllApplications(Object sender)

Discussion

This action causes each application to order its windows to the front, which could obscure the currently active window in the active application.

unhideWithoutActivation

Restores hidden windows without activating their owner (the receiver).

public void unhideWithoutActivation()

Discussion

When this method begins, it posts an ApplicationWillUnhideNotification to the default notification center. If it completes successfully, it posts an ApplicationDidUnhideNotification.

updateWindows

Sends an update message to each onscreen NSWindow.

public void updateWindows()

Discussion

This method is invoked automatically in the main event loop after each event when running in NSRunLoop.DefaultRunLoopMode or NSApplication.ModalRunLoopMode. This method is not invoked automatically when running in NSApplication.EventTrackingRunLoopMode. If the NSWindow has automatic updating turned on, its update method will redraw all the NSWindow’s NSViews that need redrawing. If automatic updating is turned off, the update message does nothing. (You turn automatic updating on and off by sending setAutodisplay to an NSWindow.)

When this method begins, it posts an ApplicationWillUpdateNotification to the default notification center. When it successfully completes, it posts an ApplicationDidUpdateNotification.

updateWindowsItem

Updates the Window menu item for aWindow to reflect the edited status of aWindow.

public void updateWindowsItem(NSWindow aWindow)

Discussion

You rarely need to invoke this method because it is invoked automatically when the edit status of an NSWindow is set.

validRequestorForTypes

Indicates whether the receiver can send and receive the specified pasteboard types.

public Object validRequestorForTypes(String sendType, String returnType)

Discussion

This message is sent to all responders in a responder chain. NSApplication.sharedApplication() is typically the last item in the responder chain, so it usually receives this message only if none of the current responders can send sendType data and accept back returnType data.

The receiver passes this message on to its delegate if the delegate can respond (and isn’t an NSResponder with its own next responder). If the delegate can’t respond or returns null, this method returns null. If the delegate can find an object that can send sendType data and accept back returnType data, it returns that object.

windows

Returns an NSArray of the receiver’s NSWindows, including offscreen windows.

public NSArray windows()

windowsMenu

Returns the Window menu or null if no Window menu has been created.

public NSMenu windowsMenu()

windowWithWindowNumber

Returns the NSWindow object corresponding to windowNum.

public NSWindow windowWithWindowNumber(int windowNum)

Constants

These are possible return values for runModalForWindow and runModalSession:

Constant	Description
`RunStoppedResponse`	Modal session was broken with `stopModal`.
`RunAbortedResponse`	Modal session was broken with `abortModal`.
`RunContinuesResponse`	Modal session is continuing (returned by `runModalSession` only).

The following constants define whether an application should terminate:

Constant	Description
`TerminateNow`	It is OK to proceed with termination.
`TerminateCancel`	The application should not be terminated.
`TerminateLater`	It may be OK to proceed with termination later. The application must call `replyToApplicationShouldTerminate` with `true` or `false` once the answer is known. This return value is for delegates that need to provide document modal alerts (sheets) in order to decide whether to quit.

The following constants indicate whether or not a copy or print operation was successful, was cancelled, or failed. These constants are used by the replyToOpenOrPrint method:

Constant	Description
`DelegateReplySuccess`	Indicates the operation succeeded.
`DelegateReplyCancel`	Indicates the user cancelled the operation.
`DelegateReplyFailure`	Indicates an error occurred processing the operation.

The following NSApplicationPrintReply constants are returned by applicationPrintFiles:

Constant	Description
`PrintingCancelled`	Printing was cancelled. Available in Mac OS X v10.4 and later.
`PrintingSuccess`	Printing was successful. Available in Mac OS X v10.4 and later.
`PrintingFailure`	Printing failed. Available in Mac OS X v10.4 and later.
`PrintingReplyLater`	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 `replyToOpenOrPrint` when the entire print operation has been completed, successfully or not. Available in Mac OS X v10.4 and later.

The following loop mode constants are defined by NSApplication:

Constant	Description
`EventTrackingRunLoopMode`	A run loop should be set to this mode when tracking events modally, such as a mouse-dragging loop.
`ModalPanelRunLoopMode`	A run loop should be set to this mode when waiting for input from a modal panel, such as SavePanel or OpenPanel.

The following constants specify the level of severity of a user attention request and are used by cancelUserAttentionRequest and requestUserAttention:

Constant	Description
`UserAttentionRequestCritical`	The user attention request is a critical request. The dock icon will bounce until either the application becomes active or the request is canceled.
`UserAttentionRequestInformational`	The user attention request is an informational request. The dock icon will bounce for one second (usually a single bounce). The request, though, remains active until either the application becomes active or the request is canceled.

The following constant can be used to determine if you are using a version of the Application Kit framework newer than the version delivered in Mac OS X v10.0:

Constant	Description
`AppKitVersionNumber10_0`	The Application Kit framework included in Mac OS X v10.0
`AppKitVersionNumber10_1`	The Application Kit framework included in Mac OS X v10.1
`AppKitVersionNumber10_2`	The Application Kit framework included in Mac OS X v10.2
`AppKitVersionNumber10_2_3`	The Application Kit framework included in Mac OS X v10.2.3

Delegate Methods

applicationDidBecomeActive

public abstract void applicationDidBecomeActive(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application becomes active. aNotification is always an ApplicationDidBecomeActiveNotification. You can retrieve the NSApplication object by sending object to aNotification.

applicationDidChangeScreenParameters

public abstract void applicationDidChangeScreenParameters(NSNotification aNotification)

Discussion

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). aNotification is always an ApplicationDidChangeScreenParametersNotification. You can retrieve the NSApplication object by sending object to aNotification.

applicationDidFinishLaunching

public abstract void applicationDidFinishLaunching(NSNotification aNotification)

Discussion

Sent by the default notification center after the application has been launched and initialized but before it has received its first event. aNotification is always an ApplicationDidFinishLaunchingNotification. You can retrieve the NSApplication object in question by sending object to aNotification. The delegate can implement this method to perform further initialization. If the user started up the application by double-clicking a file, the delegate receives the applicationOpenFile message before receiving applicationDidFinishLaunching. (applicationWillFinishLaunching is sent before applicationOpenFile.)

applicationDidHide

public abstract void applicationDidHide(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is hidden. aNotification is always an ApplicationDidHideNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationDidResignActive

public abstract void applicationDidResignActive(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is deactivated. aNotification is always an ApplicationDidResignActiveNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationDidUnhide

public abstract void applicationDidUnhide(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is made visible. aNotification is always an ApplicationDidUnhideNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationDidUpdate

public abstract void applicationDidUpdate(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the NSApplication object updates its NSWindows. aNotification is always an ApplicationDidUpdateNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationDockMenu

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

public abstract NSMenu applicationDockMenu(NSApplication sender)

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 (NSApplication.sharedApplication().sendActionToTargetFromSender (selector, target, null).

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.

applicationOpenFile

public abstract boolean applicationOpenFile(NSApplication theApplication, String filename)

Discussion

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

applicationOpenFiles

Identical to applicationOpenFile except that the receiver opens multiple files corresponding to the file names in the filenames array.

public abstract void applicationOpenFiles(NSApplication sender, NSArray filenames)

Discussion

Delegates should invoke the replyToOpenOrPrint method upon success or failure, or when the user cancels the operation.

Availability

Available in Mac OS X v10.3 and later.

applicationOpenFileWithoutUI

public abstract boolean applicationOpenFileWithoutUI(Object sender, String filename)

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. Returns true if the file was successfully opened, false otherwise.

applicationOpenTempFile

public abstract boolean applicationOpenTempFile(NSApplication theApplication, String filename)

Discussion

Sent directly by theApplication to the delegate. The method should attempt to open the file filename, returning true if the file is successfully opened, and false 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.

applicationOpenUntitledFile

public abstract boolean applicationOpenUntitledFile(NSApplication theApplication)

Discussion

Sent directly by theApplication to the delegate to request that a new, untitled file be opened. Returns true if the file was successfully opened, false otherwise.

applicationPrintFile

public abstract boolean applicationPrintFile(NSApplication theApplication, String filename)

Discussion

Sent when the user starts up the application on the command line with the -NSPrint option. Sent directly by theApplication to the delegate.

The method should attempt to print the file filename, returning true if the file was successfully printed, and false otherwise. 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 to print.

applicationPrintFiles

Identical to applicationPrintFile except that the receiver prints multiple files corresponding to the file names in the filenames array.

public abstract void applicationPrintFiles(NSApplication sender, NSArray filenames)

Discussion

Delegates should invoke the replyToOpenOrPrint method upon success or failure, or when the user cancels the operation.

This method has been deprecated. Use applicationPrintFiles instead.

Availability

Deprecated in Mac OS X v10.4.

applicationPrintFiles

Prints a group of files.

public abstract int applicationPrintFiles(NSApplication application, NSArray fileNames, NSDictionary printSettings, boolean showPrintPanels)

Discussion

Sent to the delegate by application. The method should print the files named in the fileNames array using printSettings, a dictionary containing NSPrintInfo-compatible print job attributes. The showPrintPanels argument is a flag indicating whether or not a print panel should be presented for each file being printed. If it is false, no print panels should be presented (but print progress indicators should still be presented).

The value returned should be one of the NSApplicationPrintReply values defined in “Constants.”

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 applicationPrintFiles, 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 Mac OS X v10.4 and later.

applicationShouldHandleReopen

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

public abstract boolean applicationShouldHandleReopen(NSApplication theApplication, boolean flag)

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 NSWindows (not NSPanels), 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 delegations.If you implement this method in your application delegate, it will be called before any of the default behavior happens. If you return true, then NSApplication will go on to do its normal thing. If you return false, then NSApplication will do nothing. So, you can either implement this method, do nothing, and return false 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 false.

flag indicates whether NSApplication has found any visible NSWindows in your application. flag can be used as an indication of whether NSApplication would do anything if you return true.

Note that what happens to minimized windows is not determined yet, but the intent is that flag being false indicates whether the Application Kit will create a new window to satisfy the reopen event.

applicationShouldOpenUntitledFile

public abstract boolean applicationShouldOpenUntitledFile(NSApplication sender)

Discussion

Invoked immediately before opening an untitled file. Return false to prevent the application from opening an untitled file; return true otherwise. Note that applicationOpenUntitledFile is invoked if this method returns true.

applicationShouldTerminate

public abstract boolean applicationShouldTerminate(NSApplication sender)

Discussion

Invoked from within the terminate method immediately before the application terminates. sender is the NSApplication to be terminated. If this method returns false, the application is not terminated, and control returns to the main event loop. Return true to allow the application to terminate.

applicationShouldTerminateAfterLastWindowClosed

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

public abstract boolean applicationShouldTerminateAfterLastWindowClosed(NSApplication theApplication)

Discussion

This method is sent when the last window is closed regardless of whether there are still open panels (a panel in this case is defined as being an instance of NSPanel or one of its subclasses).

If this method returns false, the application is not terminated, and control returns to the main event loop. Return true to allow the application to terminate. Note that applicationShouldTerminate is invoked if this method returns true.

applicationWillBecomeActive

public abstract void applicationWillBecomeActive(NSNotification aNotification)

Discussion

Sent by the default notification center immediately before the application becomes active. aNotification is always an ApplicationWillBecomeActiveNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationWillFinishLaunching

public abstract void applicationWillFinishLaunching(NSNotification aNotification)

Discussion

Sent by the default notification center immediately before the NSApplication object is initialized. aNotification is always an ApplicationWillFinishLaunchingNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationWillHide

public abstract void applicationWillHide(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is hidden. aNotification is always an ApplicationWillHideNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationWillPresentError

Sent to the delegate before application presents an error message, based on the information in error, to the user.

public abstract NSError applicationWillPresentError(NSApplication application, NSError error)

Discussion

The delegate can return a new NSError object or the same one passed in error.

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 Mac OS X v10.4 and later.

applicationWillResignActive

public abstract void applicationWillResignActive(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is deactivated. aNotification is always an ApplicationWillResignActiveNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationWillTerminate

public abstract void applicationWillTerminate(NSNotification aNotification)

Discussion

Sent by the default notification center immediately before the application terminates. aNotification is always an ApplicationWillTerminateNotification. You can retrieve the NSApplication object in question by sending object to aNotification. Put any necessary cleanup code in this method.

applicationWillUnhide

public abstract void applicationWillUnhide(NSNotification aNotification)

Discussion

Sent by the default notification center immediately after the application is unhidden. aNotification is always an ApplicationWillUnhideNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

applicationWillUpdate

public abstract void applicationWillUpdate(NSNotification aNotification)

Discussion

Sent by the default notification center immediately before the NSApplication object updates its NSWindows. aNotification is always an ApplicationWillUpdateNotification. You can retrieve the NSApplication object in question by sending object to aNotification.

Notifications

These notifications apply to NSApplication. See “Notifications” in NSWorkspace for additional, similar notifications.

ApplicationDidBecomeActiveNotification

Posted immediately after the application becomes active. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidChangeScreenParametersNotification

Posted 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). The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidFinishLaunchingNotification

Posted at the end of the finishLaunching method to indicate that the application has completed launching and is ready to run. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidHideNotification

Posted at the end of the hide method to indicate that the application is now hidden. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidResignActiveNotification

Posted immediately after the application gives up its active status to another application. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidUnhideNotification

Posted at the end of the unhideWithoutActivation method to indicate that the application is now visible. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationDidUpdateNotification

Posted at the end of the updateWindows method to indicate that the application has finished updating its windows. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillBecomeActiveNotification

Posted immediately after the application becomes active. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillFinishLaunchingNotification

Posted at the start of the finishLaunching method to indicate that the application has completed its initialization process and is about to finish launching. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillHideNotification

Posted at the start of the hide method to indicate that the application is about to be hidden. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillResignActiveNotification

Posted immediately before the application gives up its active status to another application. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillTerminateNotification

Posted by the terminate method to indicate that the application will terminate. Posted only if the delegate method applicationShouldTerminate returns true. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillUnhideNotification

Posted at the start of the unhideWithoutActivation method to indicate that the application is about to be visible. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

ApplicationWillUpdateNotification

Posted at the start of the updateWindows method to indicate that the application is about to update its windows. The notification object is NSApplication.sharedApplication(). This notification does not contain a userInfo dictionary.

Next Page >

Hide TOC

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.

Legacy Document

NSApplication

Class at a Glance

Principal Attributes

Commonly Used Methods

Overview

The Delegate and Notifications

System Services

Subclassing Notes

Methods to Override

Special Considerations

Alternatives to Subclassing

Tasks

Constructors

Creating and Initializing an NSApplication

Getting Information About the Framework

Changing the Active Application

Running the Event Loop

Getting, Removing, and Posting Events

Managing Sheets

Managing Windows

Hiding All Windows

Setting the Application’s Icon

Getting the Main Menu

Managing the Window Menu

Managing the Services Menu

Showing Standard Panels

Displaying Help

Sending Action Messages

Getting the Display Context

Reporting an Exception

Terminating the Application

Assigning a Delegate

Handling User Attention Requests

Loading Nib Files

Opening files

Printing

Supplying a dock menu

Activating, launching, and updating an application

Hiding and unhiding an application

Terminating an application

Handling errors

Constructors

NSApplication

Discussion

Static Methods

appkitVersionNumber

beep

Discussion

loadNibFromBundle

Discussion

loadNibNamed

Discussion

sharedApplication

Discussion

See Also

showSystemInfoPanel

Instance Methods

abortModal

Discussion

See Also

activateContextHelpMode

Discussion

See Also

activateIgnoringOtherApps

Discussion

See Also

addWindowsItem

Discussion

See Also

applicationIconImage

See Also

arrangeInFront

Discussion

See Also

beginModalSessionForWindow

Discussion

beginSheet

Discussion

See Also