Up

# NSApplication

### Authors

Scott Christley (`scottc@net-community.com`)
Felipe A. Rodriguez (`far@ix.netcom.com`)
Richard Frith-Macdonald (`richard@brainstorm.co.uk`)

> The one and only application class.

Copyright: (C) 1996-2105 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSApplication class
2. Software documentation for the NSApplication(CharacterPanel) category
3. Software documentation for the NSApplication(GSGUIInternal) category
4. Software documentation for the NSObject(NSApplicationDelegate) informal protocol
5. Software documentation for the NSObject(NSServicesRequests) informal protocol
6. Software documentation for the NSApplicationDelegate protocol

# Software documentation for the NSApplication class

## NSApplication : NSResponder

> Declared in:
>   AppKit/NSApplication.h

> Conforms to:
>   NSCoding
>   NSUserInterfaceValidations

Availability: OpenStep

Every graphical GNUstep application has exactly one instance of `NSApplication` (or a subclass) instantiated. Usually this is created through the +sharedApplication method. Once created, this instance is always accessible through the global variable ' `NSApp` '.

The NSApplication instance manages the main run loop, dispatches events, and manages resources. It sets up the connection to the window server and provides special methods for putting up "modal" (always on top) windows.

Typically, -run is called by an application's `main` method after the NSApplication instance is created, which never returns. However, applications needing to integrate other event loops may strategically call the -stop: method, followed by -run later on.

To avoid most common needs for subclassing, NSApplication allows you to specify a delegate that is messaged in particular situations. See -delegate , -setDelegate: , and <NSApplicationDelegate> .

Subclassing should be a last resort, and delegate methods should be used in most cases. However, subclassing is most frequently done to implement custom event loop management by overriding -run when the method described above is not sufficient, or to intercept events by overriding -sendEvent: .

Instance Variables
Method summary

- -orderFrontCharacterPalette:
- -_windowWillDealloc:
- -orderFrontColorPanel:
- -orderFrontDataLinkPanel:
- -activateContextHelpMode:
- -showHelp:
- -orderFrontHelpPanel:
- -runPageLayout:
- -registerUserInterfaceItemSearchHandler:
- -searchString:inUserInterfaceItemString:searchRange:foundRange:
- -unregisterUserInterfaceItemSearchHandler:
- +detachDrawingThread:toTarget:withObject:
- +sharedApplication
- -abortModal
- -activateIgnoringOtherApps:
- -addWindowsItem:title:filename:
- -applicationIconImage
- -arrangeInFront:
- -beginModalSessionForWindow:
- -beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo:
- -cancelUserAttentionRequest:
- -changeWindowsItem:title:filename:
- -context
- -currentEvent
- -currentPresentationOptions
- -deactivate
- -delegate
- -discardEventsMatchingMask:beforeEvent:
- -endModalSession:
- -endSheet:
- -endSheet:returnCode:
- -finishLaunching
- -hide:
- -hideOtherApplications:
- -isActive
- -isHidden
- -isRunning
- -keyWindow
- -mainMenu
- -mainWindow
- -makeWindowsPerform:inOrder:
- -miniaturizeAll:
- -modalWindow
- -nextEventMatchingMask:untilDate:inMode:dequeue:
- -orderFrontStandardAboutPanel:
- -orderFrontStandardAboutPanelWithOptions:
- -orderFrontStandardInfoPanel:
- -orderFrontStandardInfoPanelWithOptions:
- -orderedDocuments
- -orderedWindows
- -postEvent:atStart:
- -presentationOptions
- -preventWindowOrdering
- -registerServicesMenuSendTypes:returnTypes:
- -removeWindowsItem:
- -replyToApplicationShouldTerminate:
- -replyToOpenOrPrint:
- -reportException:
- -requestUserAttention:
- -run
- -runModalForWindow:
- -runModalForWindow:relativeToWindow:
- -runModalSession:
- -sendAction:to:from:
- -sendEvent:
- -servicesMenu
- -servicesProvider
- -setAppleMenu:
- -setApplicationIconImage:
- -setDelegate:
- -setMainMenu:
- -setPresentationOptions:
- -setServicesMenu:
- -setServicesProvider:
- -setWindowsMenu:
- -setWindowsNeedUpdate:
- -stop:
- -stopModal
- -stopModalWithCode:
- -targetForAction:
- -targetForAction:to:from:
- -terminate:
- -tryToPerform:with:
- -unhide:
- -unhideAllApplications:
- -unhideWithoutActivation
- -updateWindows
- -updateWindowsItem:
- -validRequestorForSendType:returnType:
- -windowWithWindowNumber:
- -windows
- -windowsMenu

### detachDrawingThread: toTarget: withObject:

+ (void) detachDrawingThread: (SEL)selector toTarget: (id)target withObject: (id)argument;
Availability: MacOS-X 10.0.0
Calls [NSThread +detachNewThreadSelector:toTarget:withObject:] with the invocation wrapped by an autorelease pool.

### sharedApplication

+ (NSApplication*) sharedApplication;
Availability: OpenStep

Return the shared application instance, creating one (of the receiver class) if needed. There is (and must always be) only a single shared application instance for each application. After the shared application instance has been created, you can access it directly via the global variable `NSApp` (but not before!). When the shared application instance is created, it is also automatically initialized (that is, its `init` method is called), which connects to the window server and prepares the gui library for actual operation. For this reason, you must always call `[NSApplication sharedApplication]` before using any functionality of the gui library - so, normally, this should be one of the first commands in your program (if you use `NSApplicationMain()` , this is automatically done).

The shared application instance is normally an instance of NSApplication; but you can subclass NSApplication, and have an instance of your own subclass be created and used as the shared application instance. If you want to get this result, you need to make sure the first time you call +sharedApplication is on your custom NSApplication subclass (rather than on NSApplication). Putting `[MyApplicationClass sharedApplication]` ; as the first command in your program is the recommended way. :-) If you use `NSApplicationMain()` , it automatically creates the appropriate instance (which you can control by editing the info dictionary of the application).

It is not safe to call this method from multiple threads - it would be useless anyway since the whole library is not thread safe: there must always be at most one thread using the gui library at a time. (If you absolutely need to have multiple threads in your application, make sure only one of them uses the gui [the 'drawing' thread], and the other ones do not).

### abortModal

- (void) abortModal;
Availability: OpenStep
Halts a currently running modal event loop started by -runModalForWindow: or -runModalSession: . If you wish to halt the session in response to user interaction with the modal window, use -stopModalWithCode: or -stopModal instead; only use this to halt the loop from elsewhere, such as another thread.

### activateIgnoringOtherApps:

- (void) activateIgnoringOtherApps: (BOOL)flag;
Availability: OpenStep
Activate app unconditionally if flag is `YES`, otherwise only if no other app is active. ( Note: this is currently not implemented under GNUstep. The app is always activated unconditionally. ) Usually it is not necessary to manually call this method, except in some circumstances of interapplication communication.

### addWindowsItem: title: filename:

- (void) addWindowsItem: (NSWindow*)aWindow title: (NSString*)aString filename: (BOOL)isFilename;
Availability: OpenStep
Adds an item to the app's Windows menu. This is usually done automatically so you don't need to call this method.

### applicationIconImage

- (NSImage*) applicationIconImage;
Availability: OpenStep

Returns the current icon be used for the application.

See Also: -setApplicationIconImage:

### arrangeInFront:

- (void) arrangeInFront: (id)sender;
Availability: OpenStep
Arranges all non-miniaturized app's windows in front by successively calling [NSWindow -orderFront:] on each window in the app's Windows menu.

### beginModalSessionForWindow:

- (NSModalSession) beginModalSessionForWindow: (NSWindow*)theWindow;
Availability: OpenStep
Set up modal session for theWindow, and, if it is not visible already, puts it up on screen, centering it if it is an NSPanel. It is then ordered front and made key or main window.

### beginSheet: modalForWindow: modalDelegate: didEndSelector: contextInfo:

- (void) beginSheet: (NSWindow*)sheet modalForWindow: (NSWindow*)docWindow modalDelegate: (id)modalDelegate didEndSelector: (SEL)didEndSelector contextInfo: (void*)contextInfo;
Availability: MacOS-X 10.0.0
Put up a modal sheet sliding down from top of docWindow. If modalDelegate is non-nil and responds to didEndSelector (this is optional), it is invoked after the session ends. The selector should take three arguments: NSWindow *, int, void *. It is passed the sheet window, the return code, and the contextInfo passed in here. Under GNUstep, the sheet aspect is not implemented (just centers window on the screen), but modalDelegate didEndSelector is called if both non-nil.

### cancelUserAttentionRequest:

- (void) cancelUserAttentionRequest: (NSInteger)request;
Availability: MacOS-X 10.0.0
Cancels a request previously made through calling -requestUserAttention: . Note that request is cancelled automatically if user activates the app.

### changeWindowsItem: title: filename:

- (void) changeWindowsItem: (NSWindow*)aWindow title: (NSString*)aString filename: (BOOL)isFilename;
Availability: OpenStep
Changes the Window menu item associated with aWindow to aString. If no associated window item exists, one is created. If isFilename is `YES`, then aString is assumed to be a filename representation the way [NSWindow -setTitleWithRepresentedFilename:] would format it, otherwise the string is displayed literally in the menu item.

### context

- (NSGraphicsContext*) context;
Availability: OpenStep
Returns the default drawing context for the app.

### currentEvent

- (NSEvent*) currentEvent;
Availability: OpenStep
Returns the most recent event -run pulled off the event queue.

### currentPresentationOptions

- (NSApplicationPresentationOptions) currentPresentationOptions;
Availability: MacOS-X 10.6.0
Description forthcoming.

### deactivate

- (void) deactivate;
Availability: OpenStep
Forcefully deactivate the app, without activating another. It is rarely necessary to use this method.

### delegate

- (id) delegate;
Availability: OpenStep
Returns the application's delegate, as set by the -setDelegate: method.

The application delegate will automatically be sent various notifications (as long as it implements the appropriate methods) when application events occur. The method to handle each of these notifications has name mirroring the notification name, so for instance an NSApplicationDidBecomeActiveNotification is handled by an `applicationDidBecomeActive:` method.

- NSApplicationDidBecomeActiveNotification
- NSApplicationDidFinishLaunchingNotification
- NSApplicationDidHideNotification
- NSApplicationDidResignActiveNotification
- NSApplicationDidUnhideNotification
- NSApplicationDidUpdateNotification
- NSApplicationWillBecomeActiveNotification
- NSApplicationWillFinishLaunchingNotification
- NSApplicationWillHideNotification
- NSApplicationWillResignActiveNotification
- NSApplicationWillTerminateNotification
- NSApplicationWillUnhideNotification
- NSApplicationWillUpdateNotification

The delegate is also sent various messages to ask for authorisation to perform actions, or to ask it to perform actions (again, as long as it implements the appropriate methods).

- application:shouldTerminateAfterLastWindowClosed:
- application:shouldOpenUntitledFile:
- application:openFile:
- application:openFiles:
- application:openFileWithoutUI:
- application:openTempFile:
- application:openUntitledFile:
- application:shouldOpenUntitledFile:
- application:printFile:
- application:shouldTerminate:
- application:shouldTerminateAfterLastWindowClosed:

The delegate is also called upon to respond to any actions which are not handled by a window, a window delgate, or by the application object itself. This is controlled by the -targetForAction: method.

Finally, the application delegate is responsible for handling messages sent to the application from remote processes (see the section documenting distributed objects for NSPasteboard ).

See -setDelegate: and <NSApplicationDelegate> for more information.

### discardEventsMatchingMask: beforeEvent:

- (void) discardEventsMatchingMask: (NSUInteger)mask beforeEvent: (NSEvent*)lastEvent;
Availability: OpenStep
Drop events matching mask from the queue, before but not including lastEvent. The mask is a bitwise AND of event mask constants. See (EventType). Use `NSAnyEventMask` to discard everything up to lastEvent.

### endModalSession:

- (void) endModalSession: (NSModalSession)theSession;
Availability: OpenStep
Clean up after a modal session has been run. Called with theSession returned from a previous call to beginModalSessionForWindow:.

### endSheet:

- (void) endSheet: (NSWindow*)sheet;
Availability: MacOS-X 10.0.0
Analogous to -stopModal for sheets.

### endSheet: returnCode:

- (void) endSheet: (NSWindow*)sheet returnCode: (NSInteger)returnCode;
Availability: MacOS-X 10.0.0
Analogous to -stopModalWithCode: for sheets.

### finishLaunching

- (void) finishLaunching;
Availability: OpenStep

Activates the application, sets the application icon, loads the main Nib file if `NSMainNibFile` is set in the application property list, posts an `NSApplicationWillFinishLaunchingNotification` , and takes care of a few other startup tasks. If you override this method, be sure to call super.

The -run method calls this the first time it is called, before starting the event loop for the first time.

### hide:

- (void) hide: (id)sender;
Availability: OpenStep

Request this application to "hide" (unmap all windows from the screen except the icon window). Posts `NSApplicationWillHideNotification` and `NSApplicationDidHideNotification`. On OS X this activates the next app that is running, however on GNUstep this is up to the window manager.

See Also: -unhide: -isHidden

Ask the window manager to hide all the application windows for us. Return whether they have been hidden.

### hideOtherApplications:

- (void) hideOtherApplications: (id)sender;
Availability: MacOS-X 10.0.0
Cause all other apps to hide themselves.

### isActive

- (BOOL) isActive;
Availability: OpenStep
Returns whether this app is the currently active GNUstep application. Note that on a GNUstep system, unlike OS X, it is possible for `NO` GNUstep app to be active.

### isHidden

- (BOOL) isHidden;
Availability: OpenStep

Returns whether app is currently in hidden state.

See Also: -hide: -unhide:

### isRunning

- (BOOL) isRunning;
Availability: OpenStep
Returns whether the event loop managed by -run is currently active.

### keyWindow

- (NSWindow*) keyWindow;
Availability: OpenStep
Returns current key window. If this app is active, one window should be key. If this app is not active, `nil` should be returned. The key window is the one that will receive keyboard input.

### mainMenu

- (NSMenu*) mainMenu;
Availability: OpenStep
Returns the main menu of the receiver.

### mainWindow

- (NSWindow*) mainWindow;
Availability: OpenStep
Returns current main window of this application. There need not necessarily be a main window, even if app is active, and this should return `nil` if the app is inactive.

### makeWindowsPerform: inOrder:

- (NSWindow*) makeWindowsPerform: (SEL)aSelector inOrder: (BOOL)flag;
Availability: OpenStep
Sends aSelector to each window, either in the app's internal window list (flag = `NO`) or their stacking order from front to back on the screen (flag = `YES`, currently not implemented under GNUstep).

### miniaturizeAll:

- (void) miniaturizeAll: (id)sender;
Availability: OpenStep
Iconify all windows in the app.

### modalWindow

- (NSWindow*) modalWindow;
Availability: OpenStep

Returns the window that is part of the current modal session, if any.

See -runModalForWindow:

### nextEventMatchingMask: untilDate: inMode: dequeue:

- (NSEvent*) nextEventMatchingMask: (NSUInteger)mask untilDate: (NSDate*)expiration inMode: (NSString*)mode dequeue: (BOOL)flag;
Availability: OpenStep
Return the next event matching mask from the queue, dequeuing if flag is `YES`. Intervening events are NOT dequeued. If no matching event is on the queue, will wait for one until expiration, returning `nil` if none found. See (EventType) for the list of masks.

### orderFrontStandardAboutPanel:

- (void) orderFrontStandardAboutPanel: (id)sender;
Availability: MacOS-X 10.0.0
Calls -orderFrontStandardAboutPanelWithOptions: with `nil` passed as the options dictionary.

### orderFrontStandardAboutPanelWithOptions:

- (void) orderFrontStandardAboutPanelWithOptions: (NSDictionary*)dictionary;
Availability: MacOS-X 10.0.0
OS X compatibility: Calls -orderFrontStandardInfoPanelWithOptions: .

### orderFrontStandardInfoPanel:

- (void) orderFrontStandardInfoPanel: (id)sender;
Availability: Not in OpenStep/MacOS-X
Calls -orderFrontStandardInfoPanelWithOptions: with `nil` passed as the options dictionary.

### orderFrontStandardInfoPanelWithOptions:

- (void) orderFrontStandardInfoPanelWithOptions: (NSDictionary*)dictionary;
Availability: Not in OpenStep/MacOS-X

Orders front the standard info panel for the application, taking the needed information from the `dictionary` argument. There is a single standard info panel per application; it is created the first time that this method is invoked, and then reused in all subsequent calls. The application standard info panel is immutable and can not be changed after creation. Useful keys for the `dictionary` are:

ApplicationName
  A string with the name of the application (eg, "Gorm"). If not available, the `Info-gnustep.plist` file is searched for the value of ApplicationName followed by NSHumanReadableShortName. If this also fails, the string returned by [NSProcessInfo -processName] is used.
ApplicationDescription
  A string with a very short description of the application (eg, "GNUstep Graphics Objects Relationship Modeller" ). If not available, `Info-gnustep.plist` is searched for that key; if this fails, no application description is shown.
ApplicationIcon
  An image to be shown near the title. If not available, `Info-gnustep.plist` is searched for ApplicationIcon; if this fails, NSApp's -applicationIconImage method is used instead.
ApplicationRelease
  A string with the name of the application, release included (eg, "Gorm 0.1"). If not available, the value for ApplicationVersion is used instead. If this fails, `Info-gnustep.plist` is searched for ApplicationRelease or NSAppVersion, otherwise, "Unknown" is used.
FullVersionID
  A string with the full version of the application (eg, "0.1.2b" or "snap011100"). If not available, Version is used instead. If this fails, `Info-gnustep.plist` is looked for NSBuildVersion. If all fails, no full version is shown.
Authors
  An array of strings, each one with the name of an author (eg, [NSArray arrayWithObject: "Nicola Pero <n.pero\@mi.flashnet.it>"] ). If not found, `Info-gnustep.plist` is searched for Authors, if this fails, "Unknown" is displayed.
URL
  [This field is still under work, so it might be changed] A string with an URL (eg, "See http://www.gnustep.org").
Copyright
  A string with copyright owners (eg, "Copyright (C) 2000 The Free Software Foundation, Inc." ). Support for multiple line strings is planned but not yet available. If not found, `Info-gnustep.plist` is searched for Copyright and then (failing this) for NSHumanReadableCopyright. If all fails, "Copyright Information Not Available" is used.
CopyrightDescription
  A string describing the kind of copyright (eg, "Released under the GNU General Public License 2.0" ). If not available, `Info-gnustep.plist` is searched for CopyrightDescription. If this fails, no copyright description is shown.

### orderedDocuments

- (NSArray*) orderedDocuments;
Availability: MacOS-X 10.0.0
OS X scripting method to return document objects being handled by application. Not implemented yet under GNUstep.

### orderedWindows

- (NSArray*) orderedWindows;
Availability: MacOS-X 10.0.0
OS X scripting method to return windows in front-to-back on-screen order for scriptable windows. The GNUstep implementation returns all the windows excluding NSPanels. some backends may return an array in an unspecified order.

### postEvent: atStart:

- (void) postEvent: (NSEvent*)event atStart: (BOOL)flag;
Availability: OpenStep
Add an event to be processed by the app, either at end or at beginning (next up) if flag is `YES`. This provides a way to provide synthetic input to an application, or, for whatever reason, to allow a real event to be re-dispatched.

### presentationOptions

- (NSApplicationPresentationOptions) presentationOptions;
Availability: MacOS-X 10.6.0
Description forthcoming.

### preventWindowOrdering

- (void) preventWindowOrdering;
Availability: OpenStep
Prevent window reordering in response to most recent mouse down (useful to prevent raise-on-mouse-click). Not implemented under GNUstep.

### registerServicesMenuSendTypes: returnTypes:

- (void) registerServicesMenuSendTypes: (NSArray*)sendTypes returnTypes: (NSArray*)returnTypes;
Availability: OpenStep
Registers the types this application can send and receive over Services. sendTypes represents the pasteboard types this app can receive in Service invocation. This is used to set up the services menu of this app -- an item is added for each registered service that can accept one of sendTypes or return one of returnTypes

### removeWindowsItem:

- (void) removeWindowsItem: (NSWindow*)aWindow;
Availability: OpenStep
Removes an item from the app's Windows menu. This is usually done automatically so you don't need to call this method.

### replyToApplicationShouldTerminate:

- (void) replyToApplicationShouldTerminate: (BOOL)shouldTerminate;
Availability: MacOS-X 10.0.0
Terminates the app if shouldTerminate is `YES`, otherwise does nothing. This should be called by user code if a delegate has returned `NSTerminateLater` to an -applicationShouldTerminate: message.

### replyToOpenOrPrint:

- (void) replyToOpenOrPrint: (NSApplicationDelegateReply)reply;
Availability: MacOS-X 10.3.0
Description forthcoming.

### reportException:

- (void) reportException: (NSException*)anException;
Availability: OpenStep
NSLogs an exception without raising it.

### requestUserAttention:

- (NSInteger) requestUserAttention: (NSRequestUserAttentionType)requestType;
Availability: MacOS-X 10.0.0
Method that on OS X makes the icon jump in the doc. Mercifully, this is unimplemented under GNUstep. If it were implemented, requestType could be either `NSCriticalRequest` (bounce endlessly) or `NSInformationalRequest` (bounce for one second).

### run

- (void) run;
Availability: OpenStep

This method first calls -finishLaunching (if this is the first time -run) has been called, then starts the main event loop of the application which continues until -terminate: or -stop: is called.

At each iteration, at most one event is dispatched, the main and services menus are sent [NSMenu -update] messages, and -updateWindows is possibly called if this has been flagged as necessary.

### runModalForWindow:

- (NSInteger) runModalForWindow: (NSWindow*)theWindow;
Availability: OpenStep
Starts modal event loop for given window, after calling -beginModalSessionForWindow: . Loop is broken only by -stopModal , -stopModalWithCode: , or -abortModal , at which time -endModalSession: is called automatically.

### runModalForWindow: relativeToWindow:

- (NSInteger) runModalForWindow: (NSWindow*)theWindow relativeToWindow: (NSWindow*)docWindow;
Availability: MacOS-X 10.0.0
Put up a modal window centered relative to docWindow. On OS X this is deprecated in favor of -beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo: .

### runModalSession:

- (NSInteger) runModalSession: (NSModalSession)theSession;
Availability: OpenStep

Processes any events for a modal session described by the theSession variable. When finished, it returns the state of the session (i.e. whether it is still running or has been stopped, etc)

If there are no pending events for the session, this method returns immediately.

Although Apple's docs state that, before processing the events, it makes the session window key and orders the window front, this method does not attempt to do this, because: 1) we don't want to interfere with use of other apps during modal session for this app; 2) occasionally other windows are active and should be usable during modal sessions (e.g., a popup dialog from a modal window); 3) most of the time -beginModalSessionForWindow: will have been called in advance. If the latter is not the case, you may need to order the window front yourself in advance.

See Also: -runModalForWindow:

### sendAction: to: from:

- (BOOL) sendAction: (SEL)aSelector to: (id)aTarget from: (id)sender;
Availability: OpenStep
Sends the aSelector message to the receiver returned by the -targetForAction:to:from: method (to which the aTarget and sender arguments are passed).
The method in the receiver must expect a single argument ... the sender.
Any value returned by the method in the receiver is ignored.
This method returns `YES` on success, `NO` on failure (when no receiver can be found for aSelector).

### sendEvent:

- (void) sendEvent: (NSEvent*)theEvent;
Availability: OpenStep
Called by -run to dispatch events that are received according to AppKit's forwarding conventions. You rarely need to invoke this directly. If you want to synthesize an event for processing, call -postEvent:atStart: .

### servicesMenu

- (NSMenu*) servicesMenu;
Availability: OpenStep

Returns the services menu of the receiver.

See Also: -setServicesMenu:

### servicesProvider

- (id) servicesProvider;
Availability: OpenStep

Returns the services provided previously registered using the -setServicesProvider: method.

See Also: -setServicesProvider:

### setAppleMenu:

- (void) setAppleMenu: (NSMenu*)aMenu;
Availability: MacOS-X 10.0.0
Here for compatibility with OS X, but currently a no-op.

### setApplicationIconImage:

- (void) setApplicationIconImage: (NSImage*)anImage;
Availability: OpenStep

Sets the application's icon. Any windows that use the old application icon image as their mini window image will be updated to use the new image.

See Also: -applicationIconImage

### setDelegate:

- (void) setDelegate: (id)anObject;
Availability: OpenStep
Sets the delegate of the application to anObject.

Beware, this does not retain anObject, so you must be sure that, in the event of anObject being deallocated, you stop it being the application delagate by calling this method again with another object (or `nil`) as the argument.

See -delegate and <NSApplicationDelegate> for more information.

### setMainMenu:

- (void) setMainMenu: (NSMenu*)aMenu;
Availability: OpenStep
Sets the main menu of the receiver. This is sent update messages by the main event loop.

### setPresentationOptions:

- (void) setPresentationOptions: (NSApplicationPresentationOptions)options;
Availability: MacOS-X 10.6.0
Currently unimplemented and unused in GNUstep, it could be extended to handle special GNUstep needs too

### setServicesMenu:

- (void) setServicesMenu: (NSMenu*)aMenu;
Availability: OpenStep

ets the services menu for the receiver. This should be called, otherwise warnings will be generated by the main event loop, which is in charge of updating all menus, including the Services menu.

See Also: -servicesMenu

### setServicesProvider:

- (void) setServicesProvider: (id)anObject;
Availability: OpenStep
Sets the object which provides services to other applications.
Passing a `nil` value for anObject will result in the provision of services to other applications by this application being disabled.
See NSPasteboard for information about providing services.

### setWindowsMenu:

- (void) setWindowsMenu: (NSMenu*)aMenu;
Availability: OpenStep
Sets the windows menu of the receiver. The windows menu keeps track of all windows open in the application.

### setWindowsNeedUpdate:

- (void) setWindowsNeedUpdate: (BOOL)flag;
Availability: OpenStep
Set whether the main run loop will request all visible windows update themselves after the current or next event is processed. (Update occurs after event dispatch in the loop.) This is needed when in NSEventTrackingRunLoopMode. When the application is using NSDefaultRunLoopMode or NSModalPanelRunLoopMode windows are updated after each loop iteration irrespective of this setting.

### stop:

- (void) stop: (id)sender;
Availability: OpenStep
Stops the main run loop, as well as a modal session if it is running.

### stopModal

- (void) stopModal;
Availability: OpenStep

Stops a running modal session causing -runModalForWindow: or -runModalSession: to return `NSRunStoppedResponse`. Use this or -stopModalWithCode: to end a modal session in response to user input.

See Also: -stopModalWithCode:

### stopModalWithCode:

- (void) stopModalWithCode: (NSInteger)returnCode;
Availability: OpenStep
Stops a running modal session causing -runModalForWindow: or -runModalSession: to return the specified integer code. Use this or -stopModal to end a modal session in response to user input.

### targetForAction:

- (id) targetForAction: (SEL)aSelector;
Availability: OpenStep

Returns the target object that will respond to aSelector, if any. The method first checks if any of the key window's first responders, the key window or its delegate responds. Next it checks the main window in the same way. Finally it checks the receiver (NSApplication) and its delegate.

### targetForAction: to: from:

- (id) targetForAction: (SEL)theAction to: (id)theTarget from: (id)sender;
Availability: MacOS-X 10.0.0
If theTarget responds to theAction it is returned, otherwise the application searches for an object which will handle theAction and returns the first object found.
Returns `nil` on failure.

### terminate:

- (void) terminate: (id)sender;
Availability: OpenStep
Requests the application terminates the application. First an -applicationShouldTerminate: message is sent to the delegate, and only if it returns `NSTerminateNow` will termination be carried out.
The old version of -applicationShouldTerminate: returned a BOOL, and this should still work as `YES` is equivalent to `NSTerminateNow` and `NO` is equivalent to `NSTerminateCancel`.

### tryToPerform: with:

- (BOOL) tryToPerform: (SEL)aSelector with: (id)anObject;
Availability: OpenStep
Attempts to perform aSelector using [NSResponder -tryToPerform:with:] and if that is not possible, attempts to get the application delegate to perform the aSelector.
Returns `YES` if an object was found to perform aSelector, `NO` otherwise.

### unhide:

- (void) unhide: (id)sender;
Availability: OpenStep

Unhides and activates this application.

See Also: -unhideWithoutActivation -hide: -isHidden

### unhideAllApplications:

- (void) unhideAllApplications: (id)sender;
Availability: MacOS-X 10.0.0
Cause all apps including this one to unhide themselves.

### unhideWithoutActivation

- (void) unhideWithoutActivation;
Availability: OpenStep
Unhides this app (displays its windows) but does not activate it.

### updateWindows

- (void) updateWindows;
Availability: OpenStep
Sends each of the app's visible windows an [NSWindow -update] message. This method is called automatically for every iteration of the run loop in NSDefaultRunLoopMode or NSModalPanelRunLoopMode, but is only called during NSEventTrackingRunLoopMode if -setWindowsNeedUpdate: is set to `YES`.

### updateWindowsItem:

- (void) updateWindowsItem: (NSWindow*)aWindow;
Availability: OpenStep
Update Windows menu item for aWindow, to reflect its edited status. This is usually done automatically so you don't need to call this.

### validRequestorForSendType: returnType:

- (id) validRequestorForSendType: (NSString*)sendType returnType: (NSString*)returnType;
Availability: OpenStep
Return an object capable of sending and receiving the specified sendType and returnType in a services interaction. NSApp is generally the last responder to get this request, and the implementation passes it on to the delegate if it handles it and is not itself an NSResponder , or returns `nil` otherwise.

### windowWithWindowNumber:

- (NSWindow*) windowWithWindowNumber: (NSInteger)windowNum;
Availability: OpenStep
Returns window for windowNum. Note the window number can be obtained for a window from [NSWindow -windowNumber] .

### windows

- (NSArray*) windows;
Availability: OpenStep
Returns array of app's visible and invisible windows.

### windowsMenu

- (NSMenu*) windowsMenu;
Availability: OpenStep
Returns current Windows menu for the application (whose window contents are managed automatically by this class and NSWindow).

## Instance Variables for NSApplication Class

### _app_icon

@protected NSImage* _app_icon;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _app_icon_window

@protected NSWindow* _app_icon_window;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _app_is_active

@protected BOOL _app_is_active;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _app_is_hidden

@protected BOOL _app_is_hidden;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _app_is_launched

@protected BOOL _app_is_launched;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _app_is_running

@protected BOOL _app_is_running;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _appearance

@protected NSAppearance* _appearance;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _current_event

@protected NSEvent* _current_event;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _default_context

@protected NSGraphicsContext* _default_context;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _delegate

@protected id _delegate;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _dock_tile

@protected NSDockTile* _dock_tile;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _hidden

@protected NSMutableArray* _hidden;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _hidden_key

@protected NSWindow* _hidden_key;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _hidden_main

@protected NSWindow* _hidden_main;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _inactive

@protected NSMutableArray* _inactive;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _infoPanel

@protected GSInfoPanel* _infoPanel;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _key_window

@protected NSWindow* _key_window;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _listener

@protected id _listener;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _main_menu

@protected NSMenu* _main_menu;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _main_window

@protected NSWindow* _main_window;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _presentationOptions

@protected NSApplicationPresentationOptions _presentationOptions;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _runLoopPool

@protected id _runLoopPool;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _session

@protected NSModalSession _session;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _unhide_on_activation

@protected BOOL _unhide_on_activation;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _windows_menu

@protected NSMenu* _windows_menu;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

### _windows_need_update

@protected BOOL _windows_need_update;
Availability: OpenStep
Warning the underscore at the start of the name of this instance variable indicates that, even though it is not technically private, it is intended for internal use within the package, and you should not use the variable in other code.

# Software documentation for the NSApplication(CharacterPanel) category

## NSApplication(CharacterPanel)

> Declared in:
>   AppKit/NSApplication.h

Availability: MacOS-X 10.3.0
Description forthcoming.
Method summary

- -orderFrontCharacterPalette:

### orderFrontCharacterPalette:

- (void) orderFrontCharacterPalette: (id)sender;
Availability: MacOS-X 10.3.0
Description forthcoming.

# Software documentation for the NSApplication(GSGUIInternal) category

## NSApplication(GSGUIInternal)

> Declared in:
>   AppKit/NSApplication.h

Availability: Not in OpenStep/MacOS-X
Description forthcoming.
Method summary

- -_windowWillDealloc:

### _windowWillDealloc:

- (void) _windowWillDealloc: (NSWindow*)window;
Availability: Not in OpenStep/MacOS-X
Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.

# Software documentation for the NSObject(NSApplicationDelegate) informal protocol

## NSObject(NSApplicationDelegate)

> Declared in:
>   AppKit/NSApplication.h

Availability: Not in OpenStep/MacOS-X
Description forthcoming.
Method summary

- -application:delegateHandlesKey:
- -application:openFile:
- -application:openFileWithoutUI:
- -application:openFiles:
- -application:openTempFile:
- -application:printFile:
- -application:printFiles:
- -application:printFiles:withSettings:showPrintPanels:
- -application:willPresentError:
- -applicationDidBecomeActive:
- -applicationDidChangeScreenParameters:
- -applicationDidFinishLaunching:
- -applicationDidHide:
- -applicationDidResignActive:
- -applicationDidUnhide:
- -applicationDidUpdate:
- -applicationDockMenu:
- -applicationOpenUntitledFile:
- -applicationShouldHandleReopen:hasVisibleWindows:
- -applicationShouldOpenUntitledFile:
- -applicationShouldTerminate:
- -applicationShouldTerminateAfterLastWindowClosed:
- -applicationWillBecomeActive:
- -applicationWillFinishLaunching:
- -applicationWillHide:
- -applicationWillResignActive:
- -applicationWillTerminate:
- -applicationWillUnhide:
- -applicationWillUpdate:

### application: delegateHandlesKey:

- (BOOL) application: (NSApplication*)sender delegateHandlesKey: (NSString*)key;
Availability: MacOS-X 10.0.0
Method called by scripting framework on OS X. Not implemented (sent) yet on GNUstep.

### application: openFile:

- (BOOL) application: (NSApplication*)app openFile: (NSString*)filename;
Availability: Not in OpenStep/MacOS-X
Sender requests application to open filename. `YES` should be returned on success, `NO` on failure.

### application: openFileWithoutUI:

- (BOOL) application: (NSApplication*)app openFileWithoutUI: (NSString*)filename;
Availability: Not in OpenStep/MacOS-X
Sender app (not necessarily this application) requests application to open file without bringing up its normal UI, for programmatic manipulation. `YES` should be returned on success, `NO` on failure.

### application: openFiles:

- (void) application: (NSApplication*)app openFiles: (NSArray*)filenames;
Availability: MacOS-X 10.3.0
Sender requests application to open filenames.

### application: openTempFile:

- (BOOL) application: (NSApplication*)app openTempFile: (NSString*)filename;
Availability: Not in OpenStep/MacOS-X
Sender requests application to open a temporary file. Responsibility for eventual deletion lies with this application. `YES` should be returned on success, `NO` on failure.

### application: printFile:

- (BOOL) application: (NSApplication*)theApplication printFile: (NSString*)filename;
Availability: Not in OpenStep/MacOS-X
Sender requests application to print filename. This should generally be done without presenting a GUI to the user, unless default options are likely to be changed. `YES` should be returned on success, `NO` on failure.

### application: printFiles:

- (void) application: (NSApplication*)app printFiles: (NSArray*)filenames;
Availability: MacOS-X 10.3.0
Description forthcoming.

### application: printFiles: withSettings: showPrintPanels:

- (NSApplicationPrintReply) application: (NSApplication*)app printFiles: (NSArray*)files withSettings: (NSDictionary*)settings showPrintPanels: (BOOL)flag;
Availability: MacOS-X 10.4.0
Description forthcoming.

### application: willPresentError:

- (NSError*) application: (NSApplication*)app willPresentError: (NSError*)error;
Availability: MacOS-X 10.4.0
Ask delegate for an error replacement.

### applicationDidBecomeActive:

- (void) applicationDidBecomeActive: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has become active.

### applicationDidChangeScreenParameters:

- (void) applicationDidChangeScreenParameters: (NSNotification*)aNotification;
Availability: MacOS-X 10.0.0
Called on OS X when the resolution or other characteristics of the display have changed (through control panel operation, connecting a new monitor, etc.). Not implemented/sent yet under GNUstep.

### applicationDidFinishLaunching:

- (void) applicationDidFinishLaunching: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has finished launching ([NSApplication-finishLaunching] has completed, but no event dispatching has begun.

### applicationDidHide:

- (void) applicationDidHide: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has just been hidden.

### applicationDidResignActive:

- (void) applicationDidResignActive: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has just been deactivated.

### applicationDidUnhide:

- (void) applicationDidUnhide: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has just been unhidden.

### applicationDidUpdate:

- (void) applicationDidUpdate: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application has updated its windows.

### applicationDockMenu:

- (NSMenu*) applicationDockMenu: (NSApplication*)sender;
Availability: MacOS-X 10.1.0
Method used on OS X to allow an application to override the standard menu obtained by right-clicking on the application's dock icon. Called when the application uses Macintosh or Windows95 style menus.

### applicationOpenUntitledFile:

- (BOOL) applicationOpenUntitledFile: (NSApplication*)app;
Availability: Not in OpenStep/MacOS-X
Sender requests application to open a fresh document. `YES` should be returned on success, `NO` on failure.

### applicationShouldHandleReopen: hasVisibleWindows:

- (BOOL) applicationShouldHandleReopen: (NSApplication*)theApplication hasVisibleWindows: (BOOL)flag;
Availability: MacOS-X 10.0.0
Method used on OS X to allow delegate to handle event when user clicks on dock icon of an already-open app. If `YES` is returned, a default implementation executes (for example, to create a new untitled document); if `NO` is returned nothing is done (and you can handle it here in this method). Not sent yet under GNUstep.

### applicationShouldOpenUntitledFile:

- (BOOL) applicationShouldOpenUntitledFile: (NSApplication*)sender;
Availability: Not in OpenStep/MacOS-X
Sender will request application to open a fresh document, unless `NO` is returned here.

### applicationShouldTerminate:

- (BOOL) applicationShouldTerminate: (id)sender;
Availability: Not in OpenStep/MacOS-X
Sent from within the [NSApplication -terminate:] . If `NO` is returned termination will not proceed.

### applicationShouldTerminateAfterLastWindowClosed:

- (BOOL) applicationShouldTerminateAfterLastWindowClosed: (id)sender;
Availability: Not in OpenStep/MacOS-X
Invoked when the last window is closed in an application. If `YES` is returned, -applicationShouldTerminate: is invoked.

### applicationWillBecomeActive:

- (void) applicationWillBecomeActive: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application will become active.

### applicationWillFinishLaunching:

- (void) applicationWillFinishLaunching: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application will become active.

### applicationWillHide:

- (void) applicationWillHide: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application will be hidden.

### applicationWillResignActive:

- (void) applicationWillResignActive: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification just before application resigns active status.

### applicationWillTerminate:

- (void) applicationWillTerminate: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification just before application terminates. (There is no opportunity to avert it now.)

### applicationWillUnhide:

- (void) applicationWillUnhide: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application will be unhidden.

### applicationWillUpdate:

- (void) applicationWillUpdate: (NSNotification*)aNotification;
Availability: Not in OpenStep/MacOS-X
Invoked on notification that application will now update its windows. (See [NSApplication -updateWindows] .

# Software documentation for the NSObject(NSServicesRequests) informal protocol

## NSObject(NSServicesRequests)

> Declared in:
>   AppKit/NSApplication.h

Availability: OpenStep
Informal protocol declaring methods for sending to and receiving from remote services providers.
Method summary

- -iconWindow
- -readSelectionFromPasteboard:
- -writeSelectionToPasteboard:types:

### iconWindow

- (NSWindow*) iconWindow;
Availability: Not in OpenStep/MacOS-X
Description forthcoming.

### readSelectionFromPasteboard:

- (BOOL) readSelectionFromPasteboard: (NSPasteboard*)pboard;
Availability: OpenStep
Request to transfer data from given pasteboard to selection (called when a called remote service has provided data to this pasteboard).

### writeSelectionToPasteboard: types:

- (BOOL) writeSelectionToPasteboard: (NSPasteboard*)pboard types: (NSArray*)types;
Availability: OpenStep
Request to write selection data to given pasteboard (called when a called remote service is to be invoked).

# Software documentation for the NSApplicationDelegate protocol

## NSApplicationDelegate

> Declared in:
>   AppKit/NSApplication.h

> Conforms to:
>   NSObject

Availability: Not in OpenStep/MacOS-X
This is now a formal optional protocol. Your delegate does not need to implement the full formal protocol. Your delegate should just implement the methods it needs to, which will allow `NSApp` to use default implementations in other cases.
Up