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.
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:
.
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.
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 modalDelegatedidEndSelector is called if both
non-nil.
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 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
).
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.
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.
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.
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 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 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).
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.
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.
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.
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.
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
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.
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.
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.
- (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).
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:
.
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.
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.
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.
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.
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.
- (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.
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.
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.
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.
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.
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.
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 method indicates that it is private, for
internal use only, and you should not use the
method in your code.
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.
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.
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.
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.
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.