Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSApplication

Inherits From:	NSResponder : NSObject

Conforms To:	NSCoding (NSResponder)
NSObject (NSObject)

Declared In:	AppKit/NSApplication.h
AppKit/NSColorPanel.h
AppKit/NSDataLinkPanel.h
AppKit/NSHelpPanel.h
AppKit/NSPageLayout.h 

Class Description

The NSApplication class provides the central framework of your application's execution. Every application must have exactly one instance of NSApplication (or of a custom subclass of NSApplication). Your program's main() function should create this instance by calling the sharedApplication class method. (Alternatively, you could use alloc and init, making sure they're called only once.) After creating the NSApplication, the main() function should load your application's main nib file, and then start the event loop by sending the NSApplication a run message. Here's an example of a typical OpenStep main() function in its entirety:

void main(int argc, char *argv[]) {
    NSApplication *app = [NSApplication sharedApplication];
    [NSBundle loadNibNamed:@"myMain" owner:app];
	    [app run];
}

Creating the NSApplication object connects the program to the window system and the Display PostScript server, and initializes its PostScript environment. The NSApplication object maintains a list of all the NSWindows that the application uses, so it can retrieve any of the application's NSViews. 

The NSApplication object's main task is to receive events from the window system and distribute them to the proper NSResponders. The NSApplication translates an event into an NSEvent object, then forwards the NSEvent to the affected NSWindow object. A key-down event that occurs while the Command key is pressed results in a commandKey: message, and every NSWindow has an opportunity to respond to it. Other keyboard and mouse events are sent to the NSWindow associated with the event; the NSWindow then distributes these NSEvents to the objects in its view hierarchy.

In general, it's neater and cleaner 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 the NSApplication object. It's rarely necessary to create a custom subclass of NSApplication. You will need to do so only if you need to provide your own special response to messages that are routinely sent to the NSApplication object. To use a custom subclass of NSApplication, simply substitute it for NSApplication in the main() function above.

When you create an instance of NSApplication (or of a custom subclass of NSApplication), it gets stored as the global variable NSApp. Although this global variable isn't used in the example main() function above, you might find it convenient to refer to NSApp within the source code for your application's custom objects. Note that you can also retrieve the NSApplication object by invoking sharedApplication.

The NSApplication class sets up autorelease pools during initialization and during the event loopÐthat is, within its init (or sharedApplication) and run methods. Similarly, the methods that the Application Kit adds to NSBundle employ autorelease pools during the loading of nib files. The autorelease pools aren't accessible outside the scope of the respective NSApplication and NSBundle methods. This isn't usually a problem, because a typical OpenStep application instantiates its objects by loading nib files (and by having the objects from the nib file create other objects during initialization and during the event loop). However, if you do need to use OpenStep classes within the main() function itself (other than to invoke the methods just mentioned), you should instantiate an autorelease pool before using the classes, and then release the pool once you're done. For more information, see the description of the NSAutoreleasePool class in the Foundation Kit.

The Delegate and Observers

The NSApplication object can be assigned a delegate that responds on behalf of the NSApplication to certain messages addressed to the NSApplication object. Some of these messages, such as application:openFile:withType:, ask the delegate to open a file. Another message, applicationShouldTerminate:, lets the delegate determine whether the application should be allowed to quit.

An NSApplication can also have observers. Observers receive notifications of changes in the NSApplication, but they don't have the unique responsibility that a delegate has. Any instance of a class that implements an observer method can register to receive the corresponding notification. For example, if a class implements applicationDidFinishLaunching: and registers to receive the corresponding notification, instances of this class are given an opportunity to react after the NSApplication has been initialized. (The observer methods are listed later in this class specification. For information about how to register to receive notifications, see the class specification for the Foundation Kit's NSNotificationCenter class.)

There can be only one delegate, but there can be many observers. The delegate itself can be an observerÐin fact, in many applications the delegate might be the only observer. Whereas most observers need to explicitly register with an NSNotificationCenter before they can receive a particular notification message, the delegate need only implement the method. By simply implementing an observer method, the NSApplication's delegate is automatically registered to receive the corresponding notification.

Creating and Initializing the NSApplication

+ (NSApplication *)sharedApplication	Returns the NSApplication instance, creating it if it doesn't yet exist.

- (void)finishLaunching	Activates the application, opens any files specified by the ªNSOpenº user default, and unhighlights the application's icon in the Workspace Manager. This method is invoked by run before it starts the event loop. When this method begins, it posts the notification NSApplicationWillFinishLaunchingNotification with the receiving object to the default notification center. When it successfully completes, it posts the notification NSApplicationDidFinishLaunchingNotification. If you override finishLaunching, the subclass method should invoke the superclass method.

Changing the Active Application 

- (void)activateIgnoringOtherApps:(BOOL)flag	Makes this the active application. If flag is NO, the application is activated only if no other application is currently active. 

- (void)deactivate	Deactivates the application. 

- (BOOL)isActive	Returns whether this is the active application. 

Running the Event Loop 

- (void)abortModal	Aborts the event loop started by runModalForWindow:. 

- (NSModalSession)beginModalSessionForWindow:(NSWindow *)theWindow
	Sets up a modal session with theWindow. 

- (void)endModalSession:(NSModalSession)session
	Finishes a modal session. 

- (BOOL)isRunning	Returns whether the main event loop is running. 

- (void)run	Starts the main event loop. 

- (int)runModalForWindow:(NSWindow *)theWindow
	Starts a modal event loop for theWindow. 

- (int)runModalSession:(NSModalSession)session
	Runs a modal session. 

- (void)sendEvent:(NSEvent *)theEvent	Dispatches events to other objects. When sending the activate application event, this method posts the notifications NSApplicationWillBecomeActive and NSApplicationDidBecomeActive with the receiving object to the default notification center. When sending the deactivate application event, it posts the NSApplicationWillResignActiveNotification and NSApplicationDidResignActiveNotification notifications with the receiving object to the default notification center.

- (void)stop:(id)sender	Stops the main event loop. 

- (void)stopModal	Stops the modal event loop. 

- (void)stopModalWithCode:(int)returnCode	Stops the event loop started by runModalForWindow: and sets the code that runModalForWindow: will return.

Getting, Removing, and Posting Events 

- (NSEvent *)currentEvent	Returns the current event. 

- (void)discardEventsMatchingMask:(unsigned int)mask 
beforeEvent:(NSEvent *)lastEvent	Removes from the event queue all events matching mask that were generated before lastEvent.

- (NSEvent *)nextEventMatchingMask:(unsigned int)mask
untilDate:(NSDate *)expiration 	Returns the next event matching mask, or nil if
inMode:(NSString *)mode 		no such event is found before the expiration date. If flag
dequeue:(BOOL)flag;		is YES, the event is removed from the queue. The mode argument names an NSRunLoop mode that determines what other ports are listened to and what timers may fire while the NSApplication is waiting for the event.

- (void)postEvent:(NSEvent *)event atStart:(BOOL)flag
	Adds event to the beginning of the application's event queue if flag is YES, and to the end otherwise.

Sending Action Messages 

- (BOOL)sendAction:(SEL)aSelector	Sends an action message to aTarget or up the responder
to:(id)aTarget		chain. 
from:(id)sender

- (id)targetForAction:(SEL)aSelector	Returns the object that receives the action message aSelector.

- (BOOL)tryToPerform:(SEL)aSelector	Attempts to send a message to the application or the
with:(id)anObject		delegate. 

Setting the Application's Icon

- (void)setApplicationIconImage:(NSImage *)anImage
	Sets the application's icon to anImage.

- (NSImage *)applicationIconImage	Returns the NSImage used for the application's icon.

Hiding All Windows 

- (void)hide:(id)sender	Hides all the application's windows. When this method begins, it posts the notification NSApplicationWillHideNotification with the receiving object to the default notification center. When it completes successfully, it posts the notification NSApplicationDidHideNotification.

- (BOOL)isHidden	Returns YES if windows are hidden. 

- (void)unhide:(id)sender	Restores hidden windows to the screen. 

- (void)unhideWithoutActivation	Restores hidden windows without activating their owner. When this method begins, it posts the notification NSApplicationWillUnhideNotification with the receiving object to the default notification center. When it completes successfully, it posts the notification NSApplicationDidUnhideNotification.

Managing Windows 

- (NSWindow *)keyWindow	Returns the key window.

- (NSWindow *)mainWindow	Returns the main window.

- (NSWindow *)makeWindowsPerform:(SEL)aSelector
inOrder:(BOOL)flag	Sends the aSelector message to the application's NSWindowsÐin front-to-back order if flag is YES, otherwise in the order of the array that the windows method returns.

- (void)miniaturizeAll:(id)sender	Miniaturizes all the receiver's application windows.

- (void)preventWindowOrdering	Suppresses the usual window ordering in handling the most recent mouse-down event.

- (void)setWindowsNeedUpdate:(BOOL)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.

- (void)updateWindows	Sends an update message to on-screen NSWindows. When this method begins, it sends the notification NSApplicationWillUpdateNotification with the receiving object to the default notification center. When it successfully completes, it sends the notification NSApplicationDidUpdateNotification.

- (NSArray *)windows	Returns an array of the application's NSWindows.

- (NSWindow *)windowWithWindowNumber:(int)windowNum
	Returns the NSWindow object corresponding to windowNum.

Showing Standard Panels 

- (void)orderFrontColorPanel:(id)sender	Brings up the color panel. 

- (void)orderFrontDataLinkPanel:(id)sender	Shows the shared instance of the data link panel, creating it first if necessary.

- (void)orderFrontHelpPanel:(id)sender	Shows the application's help panel or the default one.

- (void)runPageLayout:(id)sender	Runs the application's page layout panel. 

Getting the Main Menu 

- (NSMenu *)mainMenu	Returns the id of the application's main menu. 

- (void)setMainMenu:(NSMenu *)aMenu	Makes aMenu the application's main menu. 

Managing the Windows Menu 

- (void)addWindowsItem:(id)aWindow	Adds a Windows menu item for aWindow.
title:(NSString *)aString
filename:(BOOL)isFilename

- (void)arrangeInFront:(id)sender	Orders all registered NSWindows to the front. 

- (void)changeWindowsItem:(id)aWindow	Changes the Windows menu item for aWindow.
title:(NSString *)aString
filename:(BOOL)isFilename

-(void)removeWindowsItem:(id)aWindow	Removes the Windows menu item for aWindow.

- (void)setWindowsMenu:(id)aMenu	Sets the Windows menu. 

- (void)updateWindowsItem:(id)aWindow	Updates the Windows menu item for aWindow.

- (NSMenu *)windowsMenu	Returns the Windows menu. 

Managing the Services menu 

- (void)registerServicesMenuSendTypes:(NSArray *)sendTypes
returnTypes:(NSArray *)returnTypes	Registers pasteboard types the application can send and receive. 

- (NSMenu *)servicesMenu	Returns the Services menu. 

- (void)setServicesMenu:(NSMenu *)aMenu	Sets the Services menu. 

- (id)validRequestorForSendType:(NSString *)sendType
returnType:(NSString *)returnType	Indicates whether the NSApplication can send and receive the specified types. 

Getting the Display PostScript Context 

- (NSDPSContext *)context	Returns the NSApplication's Display PostScript context. 

Reporting an Exception 

- (void)reportException:(NSException *)anException
	Logs the given exception by calling NSLog().

Terminating the Application 

- (void)terminate:(id)sender	Frees the NSApplication object and exits the application. 

Assigning a Delegate 

- (id)delegate	Returns the NSApplication's delegate. 

- (void)setDelegate:(id)anObject	Makes anObject the NSApplication's delegate. 

Implemented by the Delegate 

- (BOOL)application:(id)sender	Sent directly by sender to the delegate. Opens the specified 
openFileWithoutUI:(NSString *)filename		file to run without a user interface.Work with the file will be under programmatic control of sender, rather than under keyboard control of the user. Returns YES or NO to indicate whether the file was successfully opened

- (BOOL)application:(NSApplication *)application	Sent directly by application to the delegate. Like 
openFile:(NSString *)filename		application:openFileWithoutUI:, but brings up the user interface of the file's application. 

- (BOOL)application:(NSApplication *)application	Sent directly by application to the delegate. Like 
openTempFile:(NSString *)filename		application:openFile:, but 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.

- (void)applicationDidBecomeActive:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidBecomeActiveNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidFinishLaunchingNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationDidHide:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidHideNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationDidResignActive:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidResignActiveNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationDidUnhide:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidUnhideNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationDidUpdate:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationDidUpdateNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (BOOL)applicationOpenUntitledFile:(NSApplication *)application
	Sent directly by application to the delegate. Like application:openFile:, but opens a new, untitled document.

- (BOOL)applicationShouldTerminate:(id)sender	Sent directly by sender to the delegate. Returns YES if the application should terminate. 

- (void)applicationWillBecomeActive:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillBecomeActiveNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)applicationWillFinishLaunching:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillFinishLaunchingNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)applicationWillHide:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillHideNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)applicationWillResignActive:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillResignActiveNotification. If the delegate implements this method, it's automatically registered to receive this notification.

- (void)applicationWillUnhide:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillUnhideNotification. If the delegate implements this method, it's automatically registered to receive the notification.

- (void)applicationWillUpdate:(NSNotification *)aNotification
	Sent by the default notification center to the delegate; aNotification is always NSApplicationWillUpdateNotification. If the delegate implements this method, it's automatically registered to receive this notification.