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,1999 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSApplication class
2. Software documentation for the NSObject(NSServicesRequests) informal protocol
3. Software documentation for the GSAppDelegateProtocol protocol

# Software documentation for the NSApplication class

## NSApplication : NSResponder

> Declared in:
>   AppKit/NSApplication.h

> Conforms to:
>   NSCoding

> Standards:
> - MacOS-X
> - OpenStep
> - GNUstep

Description forthcoming.

Method summary

- -orderFrontColorPanel:
- -orderFrontDataLinkPanel:
- -activateContextHelpMode:
- -showHelp:
- -orderFrontHelpPanel:
- -runPageLayout:
- +detachDrawingThread:toTarget:withObject:
- +sharedApplication
- -abortModal
- -activateIgnoringOtherApps:
- -addWindowsItem:title:filename:
- -applicationIconImage
- -arrangeInFront:
- -beginModalSessionForWindow:
- -beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo:
- -cancelUserAttentionRequest:
- -changeWindowsItem:title:filename:
- -context
- -currentEvent
- -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:
- -preventWindowOrdering
- -registerServicesMenuSendTypes:returnTypes:
- -removeWindowsItem:
- -replyToApplicationShouldTerminate:
- -reportException:
- -requestUserAttention:
- -run
- -runModalForWindow:
- -runModalForWindow:relativeToWindow:
- -runModalSession:
- -sendAction:to:from:
- -sendEvent:
- -servicesMenu
- -servicesProvider
- -setAppleMenu:
- -setApplicationIconImage:
- -setDelegate:
- -setMainMenu:
- -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;

Description forthcoming.

### sharedApplication

+ (NSApplication*) sharedApplication;

Description forthcoming.

### abortModal

- (void) abortModal;

Description forthcoming.

### activateIgnoringOtherApps:

- (void) activateIgnoringOtherApps: (BOOL)flag;

Description forthcoming.

### addWindowsItem:title:filename:

- (void) addWindowsItem: (NSWindow*)aWindow title: (NSString*)aString filename: (BOOL)isFilename;

Description forthcoming.

### applicationIconImage

- (NSImage*) applicationIconImage;

Description forthcoming.

### arrangeInFront:

- (void) arrangeInFront: (id)sender;

Description forthcoming.

### beginModalSessionForWindow:

- (NSModalSession) beginModalSessionForWindow: (NSWindow*)theWindow;

Description forthcoming.

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

- (void) beginSheet: (NSWindow*)sheet modalForWindow: (NSWindow*)docWindow modalDelegate: (id)modalDelegate didEndSelector: (SEL)didEndSelector contextInfo: (void*)contextInfo;

Description forthcoming.

### cancelUserAttentionRequest:

- (void) cancelUserAttentionRequest: (int)request;

Description forthcoming.

### changeWindowsItem:title:filename:

- (void) changeWindowsItem: (NSWindow*)aWindow title: (NSString*)aString filename: (BOOL)isFilename;

Description forthcoming.

### context

- (NSGraphicsContext*) context;

Description forthcoming.

### currentEvent

- (NSEvent*) currentEvent;

Description forthcoming.

### deactivate

- (void) deactivate;

Description forthcoming.

### delegate

- (id) delegate;

Returns the applications 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).

- applicationShouldTerminateAfterLastWindowClosed:
- applicationShouldOpenUntitledFile:
- applicationOpenUntitledFile:
- applicationShouldTerminate:

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

### discardEventsMatchingMask:beforeEvent:

- (void) discardEventsMatchingMask: (unsigned int)mask beforeEvent: (NSEvent*)lastEvent;

Description forthcoming.

### endModalSession:

- (void) endModalSession: (NSModalSession)theSession;

Description forthcoming.

### endSheet:

- (void) endSheet: (NSWindow*)sheet;

Description forthcoming.

### endSheet:returnCode:

- (void) endSheet: (NSWindow*)sheet returnCode: (int)returnCode;

Description forthcoming.

### finishLaunching

- (void) finishLaunching;

Description forthcoming.

### hide:

- (void) hide: (id)sender;

Description forthcoming.

### hideOtherApplications:

- (void) hideOtherApplications: (id)sender;

Description forthcoming.

### isActive

- (BOOL) isActive;

Description forthcoming.

### isHidden

- (BOOL) isHidden;

Description forthcoming.

### isRunning

- (BOOL) isRunning;

Description forthcoming.

### keyWindow

- (NSWindow*) keyWindow;

Description forthcoming.

### mainMenu

- (NSMenu*) mainMenu;

Description forthcoming.

### mainWindow

- (NSWindow*) mainWindow;

Description forthcoming.

### makeWindowsPerform:inOrder:

- (NSWindow*) makeWindowsPerform: (SEL)aSelector inOrder: (BOOL)flag;

Description forthcoming.

### miniaturizeAll:

- (void) miniaturizeAll: (id)sender;

Description forthcoming.

### modalWindow

- (NSWindow*) modalWindow;

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

See -runModalForWindow:

### nextEventMatchingMask:untilDate:inMode:dequeue:

- (NSEvent*) nextEventMatchingMask: (unsigned int)mask untilDate: (NSDate*)expiration inMode: (NSString*)mode dequeue: (BOOL)flag;

Description forthcoming.

### orderFrontStandardAboutPanel:

- (void) orderFrontStandardAboutPanel: (id)sender;

Description forthcoming.

### orderFrontStandardAboutPanelWithOptions:

- (void) orderFrontStandardAboutPanelWithOptions: (NSDictionary*)dictionary;

Description forthcoming.

### orderFrontStandardInfoPanel:

- (void) orderFrontStandardInfoPanel: (id)sender;

Description forthcoming.

### orderFrontStandardInfoPanelWithOptions:

- (void) orderFrontStandardInfoPanelWithOptions: (NSDictionary*)dictionary;

Description forthcoming.

### orderedDocuments

- (NSArray*) orderedDocuments;

Description forthcoming.

### orderedWindows

- (NSArray*) orderedWindows;

Description forthcoming.

### postEvent:atStart:

- (void) postEvent: (NSEvent*)event atStart: (BOOL)flag;

Description forthcoming.

### preventWindowOrdering

- (void) preventWindowOrdering;

Description forthcoming.

### registerServicesMenuSendTypes:returnTypes:

- (void) registerServicesMenuSendTypes: (NSArray*)sendTypes returnTypes: (NSArray*)returnTypes;

Description forthcoming.

### removeWindowsItem:

- (void) removeWindowsItem: (NSWindow*)aWindow;

Description forthcoming.

### replyToApplicationShouldTerminate:

- (void) replyToApplicationShouldTerminate: (BOOL)shouldTerminate;

Description forthcoming.

### reportException:

- (void) reportException: (NSException*)anException;

Description forthcoming.

### requestUserAttention:

- (int) requestUserAttention: (NSRequestUserAttentionType)requestType;

Description forthcoming.

### run

- (void) run;

Description forthcoming.

### runModalForWindow:

- (int) runModalForWindow: (NSWindow*)theWindow;

Description forthcoming.

### runModalForWindow:relativeToWindow:

- (int) runModalForWindow: (NSWindow*)theWindow relativeToWindow: (NSWindow*)docWindow;

Description forthcoming.

### runModalSession:

- (int) runModalSession: (NSModalSession)theSession;

Processes one event for a modal session described by the theSession variable. Before processing the event, it makes the session window key and orders the window front, so there is no need to do this separately. When finished, it returns the state of the session (i.e. whether it is still running or has been stopped, etc)

See Also: -runModalForWindow:

### sendAction:to:from:

- (BOOL) sendAction: (SEL)aSelector to: (id)aTarget from: (id)sender;

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;

Description forthcoming.

### servicesMenu

- (NSMenu*) servicesMenu;

Description forthcoming.

### servicesProvider

- (id) servicesProvider;

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

### setAppleMenu:

- (void) setAppleMenu: (NSMenu*)aMenu;

Description forthcoming.

### setApplicationIconImage:

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

Description forthcoming.

### setDelegate:

- (void) setDelegate: (id)anObject;

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.

### setMainMenu:

- (void) setMainMenu: (NSMenu*)aMenu;

Description forthcoming.

### setServicesMenu:

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

Description forthcoming.

### setServicesProvider:

- (void) setServicesProvider: (id)anObject;

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;

Description forthcoming.

### setWindowsNeedUpdate:

- (void) setWindowsNeedUpdate: (BOOL)flag;

Description forthcoming.

### stop:

- (void) stop: (id)sender;

Description forthcoming.

### stopModal

- (void) stopModal;

Description forthcoming.

### stopModalWithCode:

- (void) stopModalWithCode: (int)returnCode;

Description forthcoming.

### targetForAction:

- (id) targetForAction: (SEL)aSelector;

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 it's delegate.

### targetForAction:to:from:

- (id) targetForAction: (SEL)theAction to: (id)theTarget from: (id)sender;

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;

Description forthcoming.

### tryToPerform:with:

- (BOOL) tryToPerform: (SEL)aSelector with: (id)anObject;

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;

Description forthcoming.

### unhideAllApplications:

- (void) unhideAllApplications: (id)sender;

Description forthcoming.

### unhideWithoutActivation

- (void) unhideWithoutActivation;

Description forthcoming.

### updateWindows

- (void) updateWindows;

Description forthcoming.

### updateWindowsItem:

- (void) updateWindowsItem: (NSWindow*)aWindow;

Description forthcoming.

### validRequestorForSendType:returnType:

- (id) validRequestorForSendType: (NSString*)sendType returnType: (NSString*)returnType;

Description forthcoming.

### windowWithWindowNumber:

- (NSWindow*) windowWithWindowNumber: (int)windowNum;

Description forthcoming.

### windows

- (NSArray*) windows;

Description forthcoming.

### windowsMenu

- (NSMenu*) windowsMenu;

Description forthcoming.

# Software documentation for the NSObject(NSServicesRequests) informal protocol

## NSObject(NSServicesRequests)

> Declared in:
>   AppKit/NSApplication.h

> Standards:
> - MacOS-X
> - OpenStep
> - GNUstep

Description forthcoming.

Method summary

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

### iconWindow

- (NSWindow*) iconWindow;

Description forthcoming.

### readSelectionFromPasteboard:

- (BOOL) readSelectionFromPasteboard: (NSPasteboard*)pboard;

Description forthcoming.

### writeSelectionToPasteboard:types:

- (BOOL) writeSelectionToPasteboard: (NSPasteboard*)pboard types: (NSArray*)types;

Description forthcoming.

# Software documentation for the GSAppDelegateProtocol protocol

## GSAppDelegateProtocol

> Declared in:
>   AppKit/NSApplication.h

> Standards:
> - NotOpenStep
> - NotMacOS-X
> - GNUstep

Description forthcoming.

Method summary

- -application:delegateHandlesKey:
- -application:openFile:
- -application:openFileWithoutUI:
- -application:openTempFile:
- -application:printFile:
- -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;

Description forthcoming.

### application:openFile:

- (BOOL) application: (NSApplication*)app openFile: (NSString*)filename;

Description forthcoming.

### application:openFileWithoutUI:

- (BOOL) application: (NSApplication*)app openFileWithoutUI: (NSString*)filename;

Description forthcoming.

### application:openTempFile:

- (BOOL) application: (NSApplication*)app openTempFile: (NSString*)filename;

Description forthcoming.

### application:printFile:

- (BOOL) application: (NSApplication*)theApplication printFile: (NSString*)filename;

Description forthcoming.

### applicationDidBecomeActive:

- (void) applicationDidBecomeActive: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidChangeScreenParameters:

- (void) applicationDidChangeScreenParameters: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidFinishLaunching:

- (void) applicationDidFinishLaunching: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidHide:

- (void) applicationDidHide: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidResignActive:

- (void) applicationDidResignActive: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidUnhide:

- (void) applicationDidUnhide: (NSNotification*)aNotification;

Description forthcoming.

### applicationDidUpdate:

- (void) applicationDidUpdate: (NSNotification*)aNotification;

Description forthcoming.

### applicationDockMenu:

- (NSMenu*) applicationDockMenu: (NSApplication*)sender;

Description forthcoming.

### applicationOpenUntitledFile:

- (BOOL) applicationOpenUntitledFile: (NSApplication*)app;

Description forthcoming.

### applicationShouldHandleReopen:hasVisibleWindows:

- (BOOL) applicationShouldHandleReopen: (NSApplication*)theApplication hasVisibleWindows: (BOOL)flag;

Description forthcoming.

### applicationShouldOpenUntitledFile:

- (BOOL) applicationShouldOpenUntitledFile: (NSApplication*)sender;

Description forthcoming.

### applicationShouldTerminate:

- (NSApplicationTerminateReply) applicationShouldTerminate: (NSApplication*)sender;

Description forthcoming.

### applicationShouldTerminateAfterLastWindowClosed:

- (BOOL) applicationShouldTerminateAfterLastWindowClosed: (id)sender;

Description forthcoming.

### applicationWillBecomeActive:

- (void) applicationWillBecomeActive: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillFinishLaunching:

- (void) applicationWillFinishLaunching: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillHide:

- (void) applicationWillHide: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillResignActive:

- (void) applicationWillResignActive: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillTerminate:

- (void) applicationWillTerminate: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillUnhide:

- (void) applicationWillUnhide: (NSNotification*)aNotification;

Description forthcoming.

### applicationWillUpdate:

- (void) applicationWillUpdate: (NSNotification*)aNotification;

Description forthcoming.

Up