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

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

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

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

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

• - (void)setApplicationIconImage:(NSImage *)anImage Sets the application's icon to anImage.
• - (NSImage *)applicationIconImage Returns the NSImage used for the application's icon.

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

• - (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 NSWindowsin 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.

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

• - (NSMenu *)mainMenu Returns the id of the application's main menu.
• - (void)setMainMenu:(NSMenu *)aMenu Makes aMenu the application's main 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.

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

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

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

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

• - (id)delegate Returns the NSApplication's delegate.
• - (void)setDelegate:(id)anObject Makes anObject the NSApplication's 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.