PATH  Documentation > Mac OS X > Application Kit Reference: Java

Table of Contents

NSApplication


Inherits from:
NSResponder : NSObject
Package:
com.apple.yellow.application

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


Commonly Used Methods



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


Class Description


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 Project Builder, this main() function is created for you. The main() function Project Builder creates begins by calling a function named NSApplicationMain()., which is functionally similar to the following:

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 also initializes the global variable NSApp, which you use to retrieve the NSApplication instance. sharedApplication only performs the initialization once; if you invoke it more than once, it simply returns the NSApplication object it created previously.

NSApplication's main purpose is to receive events from the Window Server and distribute them to the proper NSResponders. NSApp 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 NSApp, it distributes it to the objects in its view hierarchy.

The NSApplication class sets up autorelease pools (instances of the NSAutoreleasePool class) during initialization and inside the event loop-specifically, within its init (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 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 the NSAutoreleasePool class specification in the Foundation Framework Reference.


Subclassing NSApplication


Rarely do you need to create a custom NSApplication subclass. In general, a better design is to separate the code that embodies your program's functionality into a number of custom objects. Usually, those custom objects are subclasses of NSObject. Methods defined in your custom objects can be invoked from a small dispatcher object without being closely tied to NSApp. The only reason to subclass NSApplication is if you need to provide your own special response to messages that are routinely sent to NSApp. (Even then, NSApp's delegate is often given a chance to respond to such messages, so it's more appropriate to implement the delegate methods.) To use a custom subclass of NSApplication, simply send sharedApplication to your custom class rather than directly to NSApplication. If you create your application in Project Builder, set the application class on the Project Attributes inspector, and Project Builder will update the main() function accordingly. As mentioned previously, NSApp uses autorelease pools in its init and run methods; if you override these methods, you'll need to create your own autorelease pools.


The Delegate and Notifications


You can assign a delegate to NSApp. The delegate responds to certain messages on behalf of NSApp. 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.

NSApp also posts notifications to the application's default notification center. Any object may register to receive one or more of the notifications posted by NSApp by sending the message addObserver:selector:name:object: to the default notification center (an instance of the NSNotificationCenter class). NSApp's delegate is automatically registered to receive these notifications if it implements certain delegate methods. For example, NSApp 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 only needs to know when the application is finished launching, it implements only applicationDidFinishLaunching. For more information on notifications, see the NSNotificationCenter class specification in the Foundation Framework Reference.




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)



Method Types


Constructors
NSApplication
Creating and initializing an NSApplication
sharedApplication
finishLaunching
Changing the active application
activateIgnoringOtherApps
isActive
deactivate
Running the event loop
run
isRunning
stop
runModalForWindow
stopModal
stopModalWithCode
abortModal
beginModalSessionForWindow
runModalSession
endModalSession
sendEvent
Getting, removing, and posting events
currentEvent
nextEventMatchingMask
discardEventsMatchingMask
postEvent
Managing windows
keyWindow
mainWindow
windowWithWindowNumber
windows
makeWindowsPerform
setWindowsNeedUpdate
updateWindows
miniaturizeAll
preventWindowOrdering
Hiding all windows
hide
isHidden
unhide
unhideWithoutActivation
Setting the application's icon
setApplicationIconImage
applicationIconImage
Getting the main menu
setMainMenu
mainMenu
Managing the Window menu
setWindowsMenu
windowsMenu
arrangeInFront
addWindowsItem
changeWindowsItem
removeWindowsItem
updateWindowsItem
Managing the Services menu
setServicesMenu
servicesMenu
registerServicesMenuTypes
validRequestorForTypes
setServicesProvider
servicesProvider
Showing standard panels
orderFrontColorPanel
runPageLayout
showSystemInfoPanel
Displaying help
showHelp
activateContextHelpMode
Sending action messages
sendActionToTargetFromSender
tryToPerform
targetForAction
targetForActionToFrom
Getting the display context
context
Reporting an exception
reportException
Terminating the application
terminate
Assigning a delegate
setDelegate
delegate


Constructors



NSApplication

public NSApplication()

Description forthcoming.


Static Methods



beep

public static void beep()

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

As part of its implementation, this method calls the function NSBeep.



loadNibFromBundle

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

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). The method first looks for the nib file in aBundle's language-specific ".lproj" directory. 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

public static boolean loadNibNamed( String aNibName, Object owner)

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). The argument aNibName need not include the ".nib" extension. If there's a bundle for owner's class, 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

+ (NSApplication *)sharedApplication

Returns the NSApplication instance (the global variable NSApp), creating it if it doesn't exist yet. 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 is done for you if you create your application with Project Builder. To retrieve the NSApplication instance after it has been created, use the global variable NSApp or invoke this method.

See Also: run, terminate



showSystemInfoPanel

public static native void showSystemInfoPanel(NSDictionary aDictionary)

Description forthcoming.


Instance Methods



abortModal

public void abortModal()

Aborts the event loop started by runModalForWindow by throwing an AbortModalException, which is caught by runModalForWindow. Because this method throws an exception, it never returns; runModalForWindow, when stopped with this method, returns RunAbortedResponse. abortModal is typically sent by objects registered with the default NSRunLoop; for example, by objects that have registered a method to be repeatedly invoked by the NSRunLoop through the use of an NSTimer object.

This method can also abort a modal session created by beginModalSessionForWindow, provided the loop that runs the modal session (by invoking runModalSession) catches AbortModalException.

See Also: endModalSession, stopModal, stopModalWithCode



activateContextHelpMode

public void activateContextHelpMode(Object sender)

Places the application in context-sensitive help mode. 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.

See Also: showHelp



activateIgnoringOtherApps

public void activateIgnoringOtherApps(boolean flag)

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

flag is normally set to false. When the Workspace Manager 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.

See Also: deactivate, isActive



addWindowsItem

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

Adds an item to the Window menu for aWindow. If isFilename is false, aString appears literally in the menu. If isFilename is true, aString is assumed to be a converted path name 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.

See Also: changeWindowsItem, setTitle (NSWindow)



applicationIconImage

public NSImage applicationIconImage()

Returns the NSImage used for the application's icon.

See Also: setApplicationIconImage



arrangeInFront

public void arrangeInFront(Object sender)

Arranges windows listed in the Window menu in front of all other windows. Windows associated with the application but not listed in the Window menu are not ordered to the front.

See Also: addWindowsItem, removeWindowsItem, makeKeyAndOrderFront (NSWindow)



beginModalSessionForWindow

public NSModalSession beginModalSessionForWindow(NSWindow aWindow)

Sets up a modal session with the NSWindow aWindow and returns an NSModalSession structure representing the session. 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.

beginModalSessionForWindow 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.



changeWindowsItem

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

Changes the item for aWindow in the Window menu to aString. 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 path name with the file's name preceding the path (the way NSWindow's setTitleWithRepresentedFilename places a title).

See Also: addWindowsItem, removeWindowsItem, setTitle (NSWindow)



context

public NSDPSContext context()

Returns the receiver's display context.

currentEvent

public NSEvent currentEvent()

Returns the current event, the last event the receiver retrieved from the event queue. NSApp receives events and forwards the current event to the affected NSWindow object, which then distributes it to the objects in its view hierarchy.

See Also: discardEventsMatchingMask, postEvent, sendEvent



deactivate

public void deactivate()

Deactivates the application. Normally, you shouldn't invoke this method-the Application Kit is responsible for proper deactivation.

See Also: activateIgnoringOtherApps



delegate

public Object delegate()

- (id)delegate

Returns the receiver's delegate.

See Also: setDelegate



discardEventsMatchingMask

public void discardEventsMatchingMask( int mask, NSEvent lastEvent)

Removes all events matching mask and generated before lastEvent from the event queue. Typically, you send this message to an NSWindow rather than to NSApp.

mask can contain these constants:

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

See Also: nextEventMatchingMask



endModalSession

public void endModalSession(NSModalSession session)

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

See Also: runModalSession



finishLaunching

public void finishLaunching()

Activates the application, opens any files specified by the "NSOpen" user default, and unhighlights the application's icon. 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. When it successfully completes, it posts an ApplicationDidFinishLaunchingNotification. If you override finishLaunching, the subclass method should invoke the superclass method.

See Also: applicationWillFinishLaunching, applicationDidFinishLaunching



hide

public void hide(Object sender)

Hides all the application's windows. 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.

See Also: miniaturizeAll, unhide, unhideWithoutActivation, applicationDidHide, applicationWillHide



isActive

public boolean isActive()

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

See Also: activateIgnoringOtherApps, deactivate



isHidden

public boolean isHidden()

Returns true if the application is hidden, false otherwise.

See Also: hide, unhide, unhideWithoutActivation



isRunning

public boolean isRunning()

Returns true if the main event loop is running, false otherwise. false means the stop method was invoked.

See Also: run, terminate



keyWindow

public NSWindow keyWindow()

Returns the key window, the NSWindow that receives keyboard events. This method returns null if there is no key window, if the application's nib file hasn't finished loading yet, or if the key window belongs to another application.

See Also: mainWindow, isKeyWindow (NSWindow)



mainMenu

public NSMenu mainMenu()

Returns the application's main menu.

See Also: setMainMenu



mainWindow

public NSWindow mainWindow()

Returns the main window. This method returns null if there is no main window, if the application's nib file hasn't finished loading, if the main window belongs to another application, or if the application is hidden.

See Also: keyWindow, isMainWindow (NSWindow)



makeWindowsPerform

public NSWindow makeWindowsPerform( NSSelector aSelector, boolean flag)

Sends the aSelector message to each NSWindow in the application in turn until one returns a value other than null. Returns that NSWindow, or null if all NSWindows returned null for aSelector.

If flag is true, the NSWindows receive the aSelector message in the front-to-back order in which they appear in the Window Server's window list. If flag is false, NSWindows receive the message in the order they appear in NSApp's window list. This order is unspecified.

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

See Also: sendActionToTargetFromSender, tryToPerform, windows



miniaturizeAll

public void miniaturizeAll(Object sender)

Miniaturizes all the receiver's windows.

See Also: hide



modalWindow

public NSWindow modalWindow()

Returns the modal window that the application is displaying. If the application isn't displaying a modal window, this method returns null.

nextEventMatchingMask

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

Returns the next event matching mask, or null if no such event is found before the expiration date. 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 NSApp is waiting for the event. The possible modes available in the Application Kit are:

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 it's down. In this case, you would set mask to accept mouse-dragged or mouse-up events and use the EventTrackingRunLoopMode.

See Also: postEvent, run, runModalForWindow



orderFrontColorPanel

public void orderFrontColorPanel(Object sender)

Brings up the color panel, an instance of NSColorPanel. If the NSColorPanel does not exist yet, it creates one. This method is typically invoked when the user chooses Colors from a menu.

orderFrontStandardAboutPanel

public void orderFrontStandardAboutPanel(Object sender)

Displays a standard About panel. This method calls orderFrontStandardAboutPanelWithOptions with a null argument. See orderFrontStandardAboutPanelWithOptions for a description of what's displayed.

orderFrontStandardAboutPanelWithOptions

public void orderFrontStandardAboutPanelWithOptions(NSDictionary optionsDictionary)

Displays a standard About panel with information from optionsDictionary.

The following are keys that can occur in optionsDictionary:

See Also: orderFrontStandardAboutPanel



postEvent

public void postEvent( NSEvent anEvent, boolean flag)

Adds anEvent to the application's event queue. 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.

See Also: currentEvent, sendEvent



preventWindowOrdering

public void preventWindowOrdering()

Suppresses the usual window ordering in handling the most recent mouse-down event. 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

public void registerServicesMenuTypes( NSArray sendTypes, NSArray returnTypes)

Registers the pasteboard types the application can send and receive in response to service requests. If the application 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 start-up 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 NSApp.

See Also: validRequestorForTypes, readSelectionFromPasteboard: (NSServicesRequests protocol), writeSelectionToPasteboard:types: (NSServicesRequests protocol)



removeWindowsItem

public void removeWindowsItem(NSWindow aWindow)

Removes the Window menu item for aWindow. 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.

See Also: addWindowsItem, changeWindowsItem



reportException

public void reportException(Throwable anException)

Logs anException by calling NSLog(). This method does not throw the exception. Use it inside of an exception handler to record that the exception occurred.

run

public void run()

Starts the main event loop. 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 NSApp using sendEvent.

Send a run message as the last statement from main(), after the application's objects have been initialized.

See Also: runModalForWindow, runModalSession, applicationDidFinishLaunching



runModalForWindow

public int runModalForWindow(NSWindow aWindow)

Starts a modal event loop for aWindow. 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 and made key as a result of the runModalForWindow message. Do not send NSWindow's makeKeyAndOrderFront to aWindow.

See Also: run, runModalSession



runModalSession

public int runModalSession(NSModalSession session)

Runs a modal session represented by session, as defined in a previous invocation of beginModalSessionForWindow. A loop using this method is similar to a modal event loop run with runModalForWindow, except with this method the application can continue processing 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 that the window remains responsive to events.

If the modal session was not stopped, this method returns RunContinuesResponse. If stopModalwas invoked as the result of event processing, RunStoppedResponse is returned. If stopModalWithCode was invoked, this method returns the value passed to stopModalWithCode. The AbortModalException thrown by abortModal isn't caught, so abortModal will not stop the loop.

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

See Also: endModalSession, run



runPageLayout

public void runPageLayout(Object sender)

Displays the application's page layout panel, an instance of NSPageLayout. If the NSPageLayout instance does not exist, it creates one. This method is typically invoked when the user selects Page Layout from the application's menu.

sendActionToTargetFromSender

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

Sends the message anAction to aTarget. If aTarget is null, NSApp 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, NSApp 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, NSApp begins again with the first responder in the main window. If objects in the main window can't respond, NSApp attempts to send the message to the main window's delegate. If still no object has responded, NSApp tries to handle the message itself. If NSApp can't respond, it attempts to send the message to its own delegate.

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

See Also: targetForAction, tryToPerform, makeWindowsPerform



sendEvent

public void sendEvent(NSEvent anEvent)

Dispatches anEvent to other objects. 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-NSApp 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.

See Also: currentEvent, postEvent



servicesMenu

public NSMenu servicesMenu()

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

See Also: setServicesMenu



servicesProvider

public Object servicesProvider()

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

See Also: setServicesProvider



setApplicationIconImage

public void setApplicationIconImage(NSImage anImage)

Sets the application's icon to anImage.

See Also: applicationIconImage



setDelegate

public void setDelegate(Object anObject)

Makes anObject the receiver's delegate. 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.

See Also: delegate



setMainMenu

public void setMainMenu(NSMenu aMenu)

Makes aMenu the application's main menu.

See Also: mainMenu



setServicesMenu

public void setServicesMenu(NSMenu aMenu)

Makes aMenu the application's Services menu.

See Also: servicesMenu



setServicesProvider

public void setServicesProvider(Object aProvider)

Registers the object aProvider as the service provider. 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.

For more information on registering services, see the on-line document on Service.

See Also: servicesProvider



setWindowsMenu

public void setWindowsMenu(NSMenu aMenu)

Makes aMenu the application's Window menu.

See Also: windowsMenu



setWindowsNeedUpdate

public void setWindowsNeedUpdate(boolean flag)

Sets whether the application's windows need updating when the application has finished processing the current event. 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.

See Also: updateWindows



showHelp

public void showHelp(Object sender)

Brings up the application's help file by sending a request to the shared NSWorkspace object to open the file using the default application for the help file's type. (You set the application's help file using Project Builder.) This method is typically invoked when the user chooses the Help command or one of the commands from the Help menu.

The help file is typically an RTF file and is displayed using Edit, but the help file can be anything. For example, Project Builder brings up a Digital Librarian bookshelf in response to its Help command.

For more information on providing on-line help for your application, see the NSHelpManager class specification.

See Also: activateContextHelpMode



stop

public void stop(Object sender)

Stops the main event loop. 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.

See Also: runModalForWindow, runModalSession, terminate



stopModal

public void stopModal()

Stops a modal event loop. 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 will stop the loop only if it's executed by code responding to an event. If you need to stop a runModalForWindow loop from a method registered with the current NSRunLoop (for example, a method repeatedly invoked by an NSTimer object), use the abortModal method.

See Also: runModalSession, stopModalWithCode



stopModalWithCode

public void stopModalWithCode(int returnCode)

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

See Also: abortModal



targetForAction

public Object targetForAction(NSSelector aSelector)

Returns the object that receives the action message aSelector.

See Also: sendActionToTargetFromSender, tryToPerform



targetForActionToFrom

public Object targetForActionToFrom( NSSelector theAction, Object theTarget, Object sender)

Description forthcoming.

terminate

public void terminate(Object sender)

Terminates the application. 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, 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.

See Also: run, stop



tryToPerform

public boolean tryToPerform( NSSelector aSelector, Object anObject)

Dispatches action messages. 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 using its inherited NSObject method performSelector:withObject:. If either the receiver or its delegate accept aSelector, this method returns true. Otherwise, it returns false.

See Also: - respondsToSelector: (NSObject)



unhide

public void unhide(Object sender)

Restores hidden windows to the screen and makes the application active. Invokes unhideWithoutActivation.

See Also: activateIgnoringOtherApps, hide



unhideWithoutActivation

public void unhideWithoutActivation()

Restores hidden windows without activating their owner (the receiver). When this method begins, it posts an ApplicationWillUnhideNotification to the default notification center. If it completes successfully, it posts an ApplicationDidUnhideNotification.

See Also: activateIgnoringOtherApps, hide, applicationDidUnhide, applicationWillUnhide



updateWindows

public void updateWindows()

Sends an update message to each on-screen NSWindow. This method is invoked automatically in the main event loop after each event. 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.

See Also: setWindowsNeedUpdate, applicationDidUpdate, applicationWillUpdate



updateWindowsItem

public void updateWindowsItem(NSWindow aWindow)

Updates the Window menu item for aWindow to reflect the edited status of aWindow. You rarely need to invoke this method because it is invoked automatically when the edit status of an NSWindow is set.

See Also: changeWindowsItem, setDocumentEdited (NSWindow)



validRequestorForTypes

public Object validRequestorForTypes( String sendType, String returnType)

Indicates whether the receiver can send and receive the specified pasteboard types. This message is sent to all responders in a responder chain. NSApp is typically the last item in the responder chain, so it usually only receives this message 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, that object is returned.

See Also: registerServicesMenuTypes, validRequestorForTypes (NSResponder), readSelectionFromPasteboard: (NSServicesRequests protocol), writeSelectionToPasteboard:types: (NSServicesRequests protocol)



windowWithWindowNumber

public NSWindow windowWithWindowNumber(int windowNum)

Returns the NSWindow object corresponding to windowNum.

windows

public NSArray windows()

Returns an NSArray of the application's NSWindows, including off-screen windows.

windowsMenu

public NSMenu windowsMenu()

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

See Also: setWindowsMenu




Methods Implemented By the Delegate


applicationOpenFile

public abstract boolean applicationOpenFile( NSApplication theApplication, String filename)

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

See Also: applicationOpenFileWithoutUI, applicationOpenTempFile, applicationOpenUntitledFile



applicationOpenFileWithoutUI

public abstract boolean applicationOpenFileWithoutUI( Object sender, String filename)

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.

See Also: applicationOpenFile, applicationOpenTempFile, applicationOpenUntitledFile, applicationPrintFile



applicationOpenTempFile

public abstract boolean applicationOpenTempFile( NSApplication theApplication, String filename)

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.

See Also: applicationOpenFile, applicationOpenFileWithoutUI, applicationOpenUntitledFile



applicationOpenUntitledFile

public abstract boolean applicationOpenUntitledFile(NSApplication theApplication)

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.

See Also: applicationOpenFile, applicationOpenFileWithoutUI, applicationOpenTempFile



applicationPrintFile

public abstract boolean applicationPrintFile( NSApplication theApplication, String filename)

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 they want to print.

See Also: applicationOpenFileWithoutUI



applicationShouldOpenUntitledFile

public abstract boolean applicationShouldOpenUntitledFile(NSApplication sender)

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)

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.

See Also: terminate, applicationShouldTerminateAfterLastWindowClosed, applicationWillTerminate



applicationShouldTerminateAfterLastWindowClosed

public abstract boolean applicationShouldTerminateAfterLastWindowClosed(NSApplication theApplication)

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

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.

See Also: terminate



applicationDidBecomeActive

public abstract void applicationDidBecomeActive(NSNotification aNotification)

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.

See Also: applicationDidFinishLaunching, applicationDidResignActive, applicationWillBecomeActive



applicationDidFinishLaunching

public abstract void applicationDidFinishLaunching(NSNotification aNotification)

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

See Also: finishLaunching, applicationDidBecomeActive



applicationDidHide

public abstract void applicationDidHide(NSNotification aNotification)

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.

See Also: applicationWillHide, applicationDidUnhide, hide



applicationDidResignActive

public abstract void applicationDidResignActive(NSNotification aNotification)

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.

See Also: applicationDidBecomeActive, applicationWillResignActive



applicationDidUnhide

public abstract void applicationDidUnhide(NSNotification aNotification)

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.

See Also: applicationDidHide, applicationWillUnhide, unhide



applicationDidUpdate

public abstract void applicationDidUpdate(NSNotification aNotification)

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.

See Also: applicationWillUpdate, updateWindows



applicationWillBecomeActive

public abstract void applicationWillBecomeActive(NSNotification aNotification)

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.

See Also: applicationDidBecomeActive, applicationWillFinishLaunching, applicationWillResignActive



applicationWillFinishLaunching

public abstract void applicationWillFinishLaunching(NSNotification aNotification)

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.

See Also: applicationDidFinishLaunching, applicationWillBecomeActive, finishLaunching



applicationWillHide

public abstract void applicationWillHide(NSNotification aNotification)

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.

See Also: applicationDidHide, hide



applicationWillResignActive

public abstract void applicationWillResignActive(NSNotification aNotification)

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.

See Also: applicationWillBecomeActive, applicationDidResignActive



applicationWillTerminate

public abstract void applicationWillTerminate(NSNotification aNotification)

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.

applicationWillTerminate does not get called for logout for power-off. See NSWorkspaceWillPowerOffNotification, which is sent for these events.

See Also: applicationShouldTerminate, terminate



applicationWillUnhide

public abstract void applicationWillUnhide(NSNotification aNotification)

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.

See Also: unhide, applicationDidUnhide, applicationWillHide



applicationWillUpdate

public abstract void applicationWillUpdate(NSNotification aNotification)

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.

See Also: applicationDidUpdate, updateWindows




Notifications


These notifications apply to NSApplication. See "Notifications" (page 1850) in NSWorkspace for additional, similar notifications.

ApplicationDidBecomeActiveNotification

Posted immediately after the application becomes active. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationDidFinishLaunchingNotification

Posted at the end of the finishLaunching method to indicate that the application has completed launching and is ready to run. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationDidHideNotification

Posted at the end of the hide method to indicate that the application is now hidden. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationDidResignActiveNotification

Posted immediately after the application gives up its active status to another application. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationDidUnhideNotification

Posted at the end of the unhideWithoutActivation method to indicate that the application is now visible. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationDidUpdateNotification

Posted at the end of the updateWindows method to indicate that the application has finished updating its windows. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillBecomeActiveNotification

Posted immediately after the application becomes active. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

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. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillHideNotification

Posted at the start of the hide method to indicate that the application is about to be hidden. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillResignActiveNotification

Posted immediately before the application gives up its active status to another application. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillTerminateNotification

Posted by the terminate method to indicate that the application will terminate. Posted only if the delegate method applicationShouldTerminate returns true. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillUnhideNotification

Posted at the start of the unhideWithoutActivation method to indicate that the application is about to be visible. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

ApplicationWillUpdateNotification

Posted at the start of the updateWindows method to indicate that the application is about to update its windows. This notification contains a notification object but no userInfo dictionary. The notification object is NSApp.

Table of Contents