scottc@net-community.com
)far@ix.netcom.com
)richard@brainstorm.co.uk
)The one and only application class.
Copyright: (C) 1996,1999 Free Software Foundation, Inc.
- Declared in:
- AppKit/NSApplication.h
Availability: Not in OpenStep/MacOS-X
- Conforms to:
- NSCoding
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 <GSAppDelegateProtocol> .
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: .
Calls [NSThread +detachNewThreadSelector:toTarget:withObject:] with the invocation wrapped by an autorelease pool.
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).
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.
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.
Adds an item to the app's Windows menu. This is usually done automatically so you don't need to call this method.
Returns the current icon be used for the application.
Arranges all app's windows in front by successively calling [NSWindow -orderFront:] on each window in the app's Windows menu.
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.
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.
Cancels a request previously made through calling -requestUserAttention: . Note that request is cancelled automatically if user activates the app.
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.
Returns the default drawing context for the app.
Returns the most recent event -run pulled off the event queue.
Forcefully deactivate the app, without activating another. It is rarely necessary to use this method.
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.
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 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 <GSAppDelegateProtocol> for more information.
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.
Clean up after a modal session has been run. Called with theSession returned from a previous call to beginModalSessionForWindow:.
Analogous to -stopModal for sheets.
Analogous to -stopModalWithCode: for sheets.
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, then
posts
NSApplicationDidFinishLaunchingNotification
. 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.
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.
Cause all other apps to hide themselves. Unimplemented under GNUstep.
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.
Returns whether app is currently in hidden state.
Returns whether the event loop managed by -run is currently active.
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.
Returns the main menu of the receiver.
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.
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).
Iconify all windows in the app.
Returns the window that is part of the current modal session, if any.
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.
Calls
-orderFrontStandardAboutPanelWithOptions:
with nil
passed as the options dictionary.
OS X compatibility: Calls -orderFrontStandardInfoPanelWithOptions: .
Calls
-orderFrontStandardInfoPanelWithOptions:
with nil
passed as the options 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:
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.
Info-gnustep.plist
is searched for that key; if this fails, no
application description is shown.
Info-gnustep.plist
is searched for ApplicationIcon; if this
fails, NSApp's
-applicationIconImage
method is used instead.
Info-gnustep.plist
is
searched for ApplicationRelease or
NSAppVersion, otherwise,
"Unknown" is used.
Info-gnustep.plist
is looked
for NSBuildVersion. If all fails, no
full version is shown.
Info-gnustep.plist
is
searched for Authors, if this
fails, "Unknown" is displayed.
Info-gnustep.plist
is searched for
Copyright and then (failing this) for
NSHumanReadableCopyright. If all
fails,
"Copyright Information Not Available"
is used.
Info-gnustep.plist
is searched for CopyrightDescription. If
this fails, no copyright description is shown.
OS X scripting method to return document objects being handled by application. Not implemented yet under GNUstep.
OS X scripting method to return windows in front-to-back on-screen order. The GNUstep implementation returns all the windows in an arbitrary order.
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.
Prevent window reordering in response to most recent mouse down (useful to prevent raise-on-mouse-click). Not implemented under GNUstep.
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
Removes an item from the app's Windows menu. This is usually done automatically so you don't need to call this method.
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.
NSLogs an exception without raising it.
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).
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.
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.
Put up a modal window centered relative to docWindow. On OS X this is deprecated in favor of -beginSheet:modalForWindow:modalDelegate:didEndSelector:contextInfo: . Not implemented under GNUstep. Currently just centers window on the screen.
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:
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).
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: .
Return the services menu of the receiver.
Returns the services provided previously registered using the -setServicesProvider: method.
Here for compatibility with OS X, but currently a no-op.
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.
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 <GSAppDelegateProtocol> for more information.
Sets the main menu of the receiver. This is sent update messages by the main event loop.
Sets 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.
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.
Sets the windows menu of the receiver. The windows menu keeps track of all windows open in the application.
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.)
Stops the main run loop, as well as a modal session if it is running.
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.
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.
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.
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.
Requests the application terminates the
application. First an
-applicationShouldTerminate:
message is sent to the delegate, and only if it
returns YES
(or
NSTerminateNow
) will termination be
carried out.
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.
Unhides and activates this application.
Cause all apps including this one to unhide themselves. Unimplemented under GNUstep.
Unhides this app (displays its windows) but does not activate it.
Sends each of the app's visible windows an [NSWindow -update] message. This method is called once per iteration of the main run loop managed by -run .
Update Windows menu item for aWindow, to reflect its edited status. This is usually done automatically so you don't need to call this.
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.
Returns window for windowNum. Note the window number can be obtained for a window from [NSWindow -windowNumber] .
Returns array of app's visible and invisible windows.
Returns current Windows menu for the application (whose window contents are managed automatically by this class and NSWindow).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Availability: Gui 0.0
- Declared in:
- AppKit/NSApplication.h
Description forthcoming.
Method summaryWarning 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.
Availability: Not in OpenStep/MacOS-X
- Declared in:
- AppKit/NSApplication.h
Informal protocol declaring methods for sending to and receiving from remote services providers.
Method summaryDescription forthcoming.
Request to transfer data from given pasteboard to selection (called when a called remote service has provided data to this pasteboard).
Request to write selection data to given pasteboard (called when a called remote service is to be invoked).
Availability: Gui 0.0
- Declared in:
- AppKit/NSApplication.h
This is a formal protocol that duplicates the informal
protocol for
NSApplication
delegates. Your delegate does not need to
implement the formal protocol; it is declared
only for documentation purposes. Your delegate should
just implement the methods it needs to, which will
allow NSApp
to use default
implementations in other cases.
Method called by scripting framework on OS X. Not implemented (sent) yet on GNUstep.
Sender requests application to open
filename. YES
should be
returned on success, NO
on failure.
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.
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.
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.
Invoked on notification that application has become active.
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.
Invoked on notification that application has finished launching ( [NSApplication -finishLaunching] has completed, but no event dispatching has begun.
Invoked on notification that application has just been hidden.
Invoked on notification that application has just been deactivated.
Invoked on notification that application has just been unhidden.
Invoked on notification that application has updated its windows.
Method used on OS X to allow an application to override the standard menu obtained by right-clicking on the application's dock icon. Not sent yet in GNUstep.
Sender requests application to open a fresh
document. YES
should be returned on
success, NO
on failure.
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.
Sender will request application to open a fresh
document, unless NO
is returned
here.
Sent from within the
[NSApplication -terminate:]
. If NSTerminateNow
is returned, termination
will proceed. If NSTerminateCancel
is
returned, termination will NOT proceed. If
NSTerminateLater
is returned,
termination will be halted, but the application
should call
[NSApplication -replyToApplicationShouldTerminate:]
with a YES
or NO
. (Used if confirmation windows, etc. need to be put up.)
Invoked when the last window is closed in an
application. If YES
is returned,
-applicationShouldTerminate:
is invoked.
Invoked on notification that application will become active.
Invoked on notification that application will become active.
Invoked on notification that application will be hidden.
Invoked on notification just before application resigns active status.
Invoked on notification just before application terminates. (There is no opportunity to avert it now.)
Invoked on notification that application will be unhidden.
Invoked on notification that application will now update its windows. (See [NSApplication -updateWindows] .