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 NSApplication(GSGUIInternal) category
  3. Software documentation for the NSObject(NSServicesRequests) informal protocol
  4. Software documentation for the GSAppDelegateProtocol protocol

Software documentation for the NSApplication class

NSApplication : NSResponder

Declared in:
AppKit/NSApplication.h
Conforms to:
NSCoding
Standards:

Description forthcoming.


Instance Variables

Method summary

detachDrawingThread: toTarget: withObject: 

+ (void) detachDrawingThread: (SEL)selector toTarget: (id)target withObject: (id)argument;

Description forthcoming.


sharedApplication 

+ (NSApplication*) sharedApplication;

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;

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;

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;

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.

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

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;

Returns the main menu of the receiver.


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;

Calls -orderFrontStandardAboutPanelWithOptions: with nil passed as the options dictionary.


orderFrontStandardAboutPanelWithOptions: 

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

Calls -orderFrontStandardInfoPanelWithOptions:


orderFrontStandardInfoPanel: 

- (void) orderFrontStandardInfoPanel: (id)sender;

Calls -orderFrontStandardInfoPanelWithOptions: with nil passed as the options dictionary.


orderFrontStandardInfoPanelWithOptions: 

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

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 -applicationIconImage] 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.peromi.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;

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;

Accepts an array of sendTypes and an array of returnTypes.


removeWindowsItem: 

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

Description forthcoming.


replyToApplicationShouldTerminate: 

- (void) replyToApplicationShouldTerminate: (BOOL)shouldTerminate;

Perform the actual application termination.


reportException: 

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

Description forthcoming.


requestUserAttention: 

- (int) requestUserAttention: (NSRequestUserAttentionType)requestType;

Description forthcoming.


run 

- (void) run;

This method starts the main event loop of the application.


runModalForWindow: 

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

Description forthcoming.


runModalForWindow: relativeToWindow: 

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

Description forthcoming.


runModalSession: 

- (int) runModalSession: (NSModalSession)theSession;

Processes any events for a modal session described by the theSession variable. Before processing the events, 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)

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

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;

Return the services menu of the receiver.


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;

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.


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;

Sets the main menu of the receiver


setServicesMenu: 

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

Sets the services menu for the receiver.


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;

Sets the windows menu of the receiver. The windows menu keeps track of all windows open in the application.


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;

Terminates the application.


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.




Instance Variables for NSApplication Class

_app_icon

@protected NSImage* _app_icon;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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;

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 NSAutoreleasePool* _runLoopPool;

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;

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;

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;

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;

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(GSGUIInternal) category

NSApplication(GSGUIInternal)

Declared in:
AppKit/NSApplication.h
Standards:

Description forthcoming.

Method summary

_windowWillDealloc: 

- (void) _windowWillDealloc: (NSWindow*)window;

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(NSServicesRequests) informal protocol

NSObject(NSServicesRequests)

Declared in:
AppKit/NSApplication.h
Standards:

Description forthcoming.

Method summary

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:

Description forthcoming.

Method summary

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