This document pertains to the NeXTSTEP operating system, which is no longer a supported product of Apple Computer. This information is provided only as a convenience to our customers who have not yet upgraded their systems, and may not apply to OPENSTEP, WebObjects, or any other product of Apple Enterprise Software.
Q: On NeXTSTEP 3.3, where can I find the class reference for the Application object?
A: The class reference for Application was mistakenly left out of the NeXTSTEP 3.3 developer distribution. Here is the 3.2 version for your convenience:
Release 3.2 Copyright
1993 by NeXT Computer, Inc. All Rights Reserved.
Application
Inherits From: Responder : Object
Declared In: appkit/Application.h
Class Description
The Application class provides the central framework of your application's execution. Every application must have exactly one object that is an instance of Application (or of a custom subclass of Application). Project Builder automatically inserts into the main file (the file that contains the main() function) code that creates that object and stores it as the global variable NXApp. The automatically generated code then loads your application's nib file, and starts the event loop by sending a run message to NXApp.
Creating the Application object connects the program to the Window Server and initializes its PostScript environment. The Application object maintains a list of all the Windows that the application uses, so it can retrieve any of the application's Views.
The Application object's main task is to receive events from the Window Server and distribute them to the proper Responders. The Application object handles a system event itself. It translates a Window event into a message forwarded to the affected Window object. A key-down event that occurs while the Command key is pressed is translated into a commandKey: message, and every Window has an opportunity to respond to it. Other keyboard and mouse events are sent to the Window associated with the event; the Window then distributes them to the objects in its View hierarchy.
In general, it's neater and cleaner to separate the code that embodies your program's functionality into a number of custom objects. Usually those custom objects are subclasses of Object. Methods defined in your custom objects can be invoked from a small dispatcher object without being closely tied to the Application object. It is rarely necessary to create a custom subclass of Application. You will need to do so only if you need to provide your own special response to messages that are routinely sent to the Application object. If you do create a custom subclass of Application, it's the object representing your custom class that gets the name NXApp and receives the run message.
The Application object can be assigned a delegate that responds on its behalf to notification messages addressed to the Application object. For a few of these notification methods, if you have created a subclass of Application and it implements the method but the delegate doesn't, that message is sent to self (and thus to a subclass method). Where that is true, it's noted in the method's description in ``Methods Implemented by the Delegate,'' below.
Since an application must have one and only one Application object, you must use new to create it. You can't use alloc, allocFromZone:, or init to create or initialize an Application object.
When your application is launched, its main nib file (if it has one) is loaded; the objects stored in the nib file are unarchived. When unarchived, each gets an awake message and then a finishUnarchiving message. Note that some objects in the nib file--for example, objects represented by the proxy CustomView object--are simply referenced, not archived. Those objects don't get the awake or finishUnarchiving messages. Instead, they're instantiated through the alloc and init mechanism.
Instance Variables
char *appName;
NXEvent currentEvent;
id windowList;
id keyWindow;
id mainWindow;
id delegate;
int *hiddenList;
int hiddenCount;
const char *hostName;
DPSContext context;
int contextNum;
id appListener;
id appSpeaker;
port_t replyPort;
NXSize screenSize;
short running;
struct __appFlags {
unsigned int hidden:1;
unsigned int autoupdate:1;
unsigned int active:1;
} appFlags;
appName The name of your application; used by the defaults system and the application's Listener object
currentEvent The event most recently retrieved from the event queue
windowList A List containing all the Windows to which the Application has access
keyWindow The Window that receives keyboard events
mainWindow The Window that receives menu commands and action messages from a Panel
delegate The object that responds to notification messages
hiddenList The List of Windows belonging to the Application at the time the Application was hidden
hiddenCount The number of Windows referred to by hiddenList
hostName The name of the machine running the Window Server
context The Display PostScript context connected to the Window Server
contextNum A number identifying the application's Display PostScript context
appListener The Application object's Listener
appSpeaker The Application object's Speaker
replyPort A general purpose reply port for the Application object's Speakers
screenSize The size of the screen that this application is running on
running The nested level of run and runModalFor:
appFlags.hidden YES if the Application's Windows are currently hidden
appFlags.autoupdate YES if the Application object is to send an update message to each Window after an event has been processed
appFlags.active YES if the Application is the active application
Method Types
Initializing the class + initialize
+ alloc
+ allocFromZone:
Color - orderFrontColorPanel:
- setImportAlpha:
- doesImportAlpha
Terminating the application - terminate:
Assigning a delegate - setDelegate:
- delegate
Class Methods
alloc
This method cannot be used to create an Application object. Use new instead. The method is implemented only to prevent you from using it; if you do use it, it generates an error message.
See also: + new
allocFromZone:
This method cannot be used to create an Application object. Use new instead. The method is implemented only to prevent you from using it; if you do use it, it generates an error message.
See also: + new
initialize + initialize
Registers defaults used by the Application class. You never send this message directly; it's sent for you when your application starts. Returns self.
new + new
Creates a new Application object and assigns it to the global variable NXApp. A program can have only one Application object, so this method just returns NXApp if the Application object already exists. This method also makes a connection to the Window Server, loads the PostScript procedures the application needs, and completes other initialization. Your program should generally invoke this method as one of the first statements in main(); this is done for you if you create your application with Interface Builder. Returns the Application object.
See also: - run
workspace + (id <NXWorkspaceRequestProtocol>)workspace
Returns an object representing the Workspace Manager. Your code can send it a message asking it to do such things as open a file. The Workspace Manager responds to the NXWorkspaceRequest protocol. Here's an example of asking the Workspace Manager for the icon for the file x.draw:
Aborts the modal event loop by raising the NX_abortModal exception, which is caught by runModalFor:, the method that started the modal loop. Since this method raises an exception, it never returns; runModalFor:, when stopped with this method, returns NX_RUNABORTED. This method is typically invoked from procedures registered with DPSAddTimedEntry(), DPSAddPort(), or DPSAddFD(). Note that you can't use this method to abort modal sessions, where you control the modal loop and periodically invoke runModalSession:.
Makes the application identified by contextNumber the active application. The argument contextNumber is the PostScript context number of the application to be activated. Normally, you shouldn't invoke this method; the Application Kit is responsible for proper activation. Returns the PostScript context number of application that was previously active.
See also: - isActive, - activateSelf:, - deactivateSelf
activateSelf: - (int)activateSelf:(BOOL)flag
Makes the receiving application the active application. If flag is NO, the application is activated only if no other application is currently active. Normally, this method is invoked with flag set to NO. When the Workspace Manager launches an application, it deactivates itself, so activateSelf:NO allows the application to become active if the user waits for it to launch, but the application remains unobtrusive if the user activates another application. If flag is YES, the application will always activate. Regardless of the setting of flag, there may be a time lag before the application activates; you should not assume that the application will be active immediately after sending this message.
Note that you can make one of your Windows the key window without changing the active application; when you send a makeKeyWindow message to a Window, you simply ensure that the Window will be the key window when the application is active.
You should rarely need to invoke this method. Under most circumstances the Application Kit takes care of proper activation. However, you might find this method useful if you implement your own methods for interapplication communication. This method returns the PostScript context number of the previously active application.
Adds an item to the Windows menu corresponding to the Window aWindow. If isFilename is NO, aString appears literally in the menu. If isFilename is YES, aString is assumed to be a converted name with the name of the file preceding the path (the way Window's setTitleAsFilename: method shows a title). If an item for aWindow already exists in the Windows menu, this method has no effect. You rarely invoke this method because an item is placed in the Windows menu for you whenever a Window's title is set. Returns self.
See also: - changeWindowsItem:title:filename:, - setTitle: (Window), - setTitleAsFilename: (Window)
appIcon - appIcon
Returns the Window object that represents the application in the Workspace Manager (containing the application's title and icon).
Invoked when the application receives an application-defined (NX_APPDEFINED) event. This is a vehicle in which you provide whatever response you want, by overriding the default definition in a subclass or defining this method in the delegate. Returns self.
Notification from the Workspace Manager that the application whose name is appName has launched. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
If the delegate implements the method app:applicationDidLaunch:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
Notification from the Workspace Manager that the application whose name is appName has terminated. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
If the delegate implements the method app:applicationDidTerminate:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
Notification from the Workspace Manager that the application whose name is appName is about to launch. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
If the delegate implements the method app:applicationWillLaunch:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
Returns the Application object's Listener--the object that will receive messages sent to the port that's registered for the application's name. If you don't send a setAppListener: message before your application starts running, an instance of Listener is created for you. (Note, however, that to communicate with the Workspace Manager to do such things as open files, you should send messages to the object that represents the Workspace Manager, returned by the workspace class method; it responds to the NXWorkspaceRequest protocol.)
See also: - setAppListener:, - appListenerPortName, - run, + workspace
Returns the name used to register the Application object's Listener. The default is the same name that's returned by the Application object's appName method. If a different name is desired, this method should be overridden. Messages sent by name to appListenerPortName will be received by your Application object.
See also: - checkInAs: (Listener), - appName, NXPortFromName()
appName - (const char *)appName
Returns the name under which the Application object has been registered for defaults. This name is also used for messaging unless the messaging name was changed by overriding appListenerPortName.
See also: - appListenerPortName
appSpeaker - appSpeaker
Returns the Application object's Speaker. You can use this object to send messages to other applications.
See also: - setSendPort: (Speaker)
arrangeInFront: - arrangeInFront:sender
Arranges all of the windows listed in the Windows menu in front of all other windows. Windows associated with the application but not listed in the Windows menu are not ordered to the front. Returns self.
See also: - removeWindowsItem:, - makeKeyAndOrderFront: (Window)
becomeActiveApp - becomeActiveApp
Sends the appDidBecomeActive: message to the Application object's delegate. This method is invoked when the application is activated. You never send a becomeActiveApp message directly, but you can override this method in a subclass. Returns self.
See also: - activateSelf:, - appDidBecomeActive: (delegate method)
Prepares the application for a modal session with theWindow. In other words, prepares the application so that mouse events get to it only if they occur in theWindow. If session is NULL, an NXModalSession is allocated; otherwise the given storage is used. (The sender could declare a local NXModalSession variable for this purpose.) theWindow is made the key window and ordered to the front.
beginModalSession:for: should be balanced by endModalSession:. If an exception is raised, beginModalSession:for: arranges for proper cleanup. Do not use NX_DURING constructs to send an endModalSession: message in the event of an exception. Returns the NXModalSession pointer that's used to refer to this session.
Returns the first object in the responder chain that responds to the message theAction. The message isn't actually dispatched. Note that this method doesn't test the value that the responding object would return should the message be sent; specifically, it doesn't test to see if the responder would return nil. Returns nil if no responder is found.
Changes the item for aWindow in the Windows menu to aString. If aWindow doesn't have an item in the Windows menu, this method adds the item. If isFilename is NO, aString appears literally in the menu. If isFilename is YES, aString is assumed to be a converted name with the file's name preceding the path (the way Window's setTitleAsFilename: places a title). Returns self.
See also: - addWindowsItem:title:filename:, - setTitle: (Window), - setTitleAsFilename: (Window)
colorScreen - (const NXScreen *)colorScreen
Returns the screen that can best represent color. This method will always return a screen, even if no color screen is present.
See also: NXBPSFromDepth()
context - (DPSContext)context
Returns the Application object's Display PostScript context.
currentEvent - (NXEvent *)currentEvent
Returns a pointer to the last event the Application object retrieved from the event queue. A pointer to the current event is also passed with every event message.
See also: - getNextEvent:waitFor:threshold:, - peekNextEvent:waitFor:threshold:
deactivateSelf - deactivateSelf
Deactivates the application if it's active. Normally, you shouldn't invoke this method; the Application Kit is responsible for proper deactivation. Returns self.
See also: - activeApp, - activate:, - activateSelf:
delayedFree: - delayedFree:theObject
Frees theObject by sending it the free message after the application finishes responding to the current event and before it gets the next event. If this method is performed during a modal loop, theObject is freed after the modal loop ends. Returns self.
See also: - perform:with:afterDelay:cancelPrevious: (DelayedPerform informal protocol)
delegate - delegate
Returns the Application object's delegate.
See also: - setDelegate:
doesImportAlpha - (BOOL)doesImportAlpha
Reports whether the application imports colors that include a value for alpha (opacity), and includes an opacity slider in its ColorPanel. The default is YES.
Notification from the Workspace Manager that the file operation identified by operation has completed. The argument is the integer returned by the method that requested the file operation, to wit performFileOperation:source:destination:files:options: (part of NXWorkspaceRequest protocol).
If the delegate implements the method app:fileOperationCompleted:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
findWindow: - findWindow:(int)windowNum
Returns the Window object that corresponds to the window number windowNum. This method is of primary use in finding the Window object associated with a particular event.
See also: - windowNum (Window)
focusView - focusView
Returns the View whose focus is currently locked, or nil if no View's focus is locked.
See also: - lockFocus (View)
free - free
Closes all the Application object's windows, breaks the connection to the Window Server, and frees the Application object.
getNextEvent: - (NXEvent *)getNextEvent:(int)mask
Gets the next event from the Window Server and returns a pointer to its event record. This method is similar to getNextEvent:waitFor:threshold: with an infinite timeout and a threshold of NX_MODALRESPTHRESHOLD.
See also: - getNextEvent:waitFor:threshold, - run, - runModalFor:, - currentEvent
Gets the next event from the Window Server and returns a pointer to its event record. Only events that match mask are returned; getNextEvent:waitFor:threshold: goes through the event queue, starting from the head, until it finds an event matching mask. (Event Type Mask constants are described in the ``Types and Constants'' section of the ``Display PostScript'' chapter.) Events that are skipped are left in the queue. Note that getNextEvent:waitFor:threshold: doesn't alter the window event masks that determine which events the Window Server will send to the application.
If an event matching the mask doesn't arrive within timeout seconds, this method returns a NULL pointer.
You can use this method to short circuit normal event dispatching and get your own events. For example, you may want to do this in response to a mouse-down event in order to track the mouse while it's down. In this case, you would set mask to accept mouse-dragged, mouse-entered, mouse-exited, or mouse-up events.
level determines what other procedures should be performed when the event queue is examined. These might include procedures to deal with timed-entries, procedures to handle messages received on ports, or procedures to read new data from files. Any such procedure that needs to be called will be called if its priority (specified when the procedure is registered) is equal to or higher than level.
In general, modal responders should pass NX_MODALRESPTHRESHOLD for level. The main run loop uses a threshold of NX_BASETHRESHOLD, allowing all procedures (except those registered with priority 0) to be checked and invoked if needed.
See also: - peekNextEvent:waitFor:threshold:, - run, - runModalFor:
Gets screen information for every screen connected to the system. A pointer to an array of NXScreen structures is placed in the variable indicated by list, and the number of NXScreen structures in that array is placed in the variable indicated by numScreens. The list of NXScreen structures belongs to the Application object; it should not be altered or freed. Returns self.
getScreenSize: - getScreenSize:(NXSize *)theSize
Gets the size of the main screen, in units of the screen coordinate system, and places it in the structure pointed to by theSize. Returns self.
Gets the window numbers for all the Application object's Windows. A pointer to a non-NULL-terminated array of ints is placed in the variable indicated by list. The number of entries in this array is placed in the integer indicated by numWindows. The order of window numbers in the array is the same as their order in the Window Server's screen list, which is their front-to-back order on the screen. The application is responsible for freeing the list array when done. Returns self.
See also: NXWindowList()
hide: - hide:sender
Collapses the application's graphics--including all its windows, menus, and panels--into a single small window. The hide: message is usually sent using the Hide command in the application's main Menu. Returns self.
See also: - unhide:
hostName - (const char *)hostName
Returns the name of the host machine on which the Window Server that serves the Application object is running. This method returns the name that was passed to the receiving Application object through the NXHost default; this name is set either from its value in the defaults database or by providing a value for NXHost through the command line. If a value for NXHost isn't specified, NULL is returned.
isActive - (BOOL)isActive
Returns YES if the application is currently active, and NO if it isn't.
See also: - activateSelf:, - activate:
isHidden - (BOOL)isHidden
Returns YES if the application is currently hidden, and NO if it isn't.
isJournalable - (BOOL)isJournalable
Returns YES if the application can be journaled, and NO if it can't. By default, applications can be journaled. Journaling is handled by the NXJournaler class.
See also: - setJournalable:
isRunning - (BOOL)isRunning
Returns YES if the application is running, and NO if the stop: method has ended the main event loop.
See also: - run, - stop:, - terminate:
keyWindow - keyWindow
Returns the key Window, that is, the Window that receives keyboard events. If there is no key Window, or if the key Window belongs to another application, this method returns nil.
Loads interface objects from a NeXT Interface Builder (nib) file. The argument anOwner is the object that appears as the ``File's Owner'' in Interface Builder's File window. The objects and their names are read from the specified nib file into storage allocated from the default zone.
Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the file filename is successfully opened and read, and nil otherwise.
Invoking loadNibFile:owner: is equivalent to invoking loadNibFile:owner:withNames:fromZone: when the additional argument values indicate that names should also be loaded and that memory should be allocated from the default zone.
Loads interface objects from a NeXT Interface Builder (nib) file. The argument anOwner is the object that appears as the ``File's Owner'' in Interface Builder's File window. The objects are read from the specified interface file into storage allocated from the default zone. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required.
Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the file filename is successfully opened and read.
Invoking loadNibFile:owner:withNames: is equivalent to invoking loadNibFile:owner:withNames:fromZone: when zone specifies that memory should be allocated from the default zone.
Loads interface objects from a NeXT Interface Builder (nib) file. The argument anOwner is the object that appears as the ``File's Owner'' in Interface Builder's File window. The objects are read into memory allocated from zone. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required. Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the file filename is successfully opened and read.
Loads interface objects and their names from the source identified by name. To find the source, the method searches as follows:
* First, for a section named name within the _ _NIB segment of the application's executable file. (This is where earlier versions of Interface Builder routinely put nib sections, but not where Project Builder puts them now, so the section will be here only if the applications was compiled by an earlier version of Interface Builder.)
* Second, if no such section exists, the method searches certain language directories within the main bundle for a file with name name and type ``nib,'' and--if it finds one--loads the interface objects from there. It searches the language directories that the user specified for this application, or (if none) those specified by the user's default language preferences (see systemLanguages).
* Third, if there's no file named name in the main bundle's relevant language directories, it looks for a file with name name and type ``nib'' in the main bundle (but outside the ``.lproj'' directories).
The argument anOwner is the object that corresponds to the ``File's Owner'' object in Interface Builder's File window. The loaded objects are allocated memory from the default zone.
Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the section or file is successfully opened and read.
Invoking loadNibSection:owner: is equivalent to invoking loadNibSection:owner:withNames:fromZone: when the additional arguments indicate that names should also be loaded and that memory should be allocated from the default zone.
Loads interface objects and their names from the source identified by name. The source may be a section within the executable file, or a file within the application bundle, as described above for the loadNibSection:owner: instance method.
The argument anOwner is the object that corresponds to the ``File's Owner'' object in Interface Builder's File window. The loaded objects are allocated memory from the default zone. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required.
Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the section or file is successfully opened and read.
Invoking loadNibSection:owner:withNames is equivalent to invoking loadNibSection:owner:withNames:fromZone: when the additional argument indicates that memory should be allocated from the default zone.
See also: NXDefaultMallocZone(), - awake (Object), - init (Object)
Loads interface objects from a section within a dynamically loaded object file--that is, from a file other than those in the application's main bundle. The argument header identifies the file, as returned by the function objc_loadModule(). The argument name identifies a named section within the file's _ _NIB segment. When no such file exists, the method searches the executable file's bundle, first within its language subdirectories, as described above for the loadNibSection:owner: instance method.
The argument anOwner is the object that corresponds to the ``File's Owner'' object in Interface Builder's File window. Memory for the loaded objects is allocated from the default zone. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required.
Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
A class can use this method in its finishLoading class method to load interface data objects required by the class but stored separately (for example, because the same interface objects are also used by other classes).
Returns non-nil if the section or file is successfully opened and read.
Invoking loadNibSection:owner:withNames:fromHeader: is equivalent to invoking loadNibSection:owner:withNames:fromHeader:fromZone: when the additional arguments indicate that names should also be loaded and that memory should be allocated from the default zone.
See also: NXDefaultMallocZone(), - awake (Object), - init (Object)
Loads interface objects from a section within a dynamically loaded object file--that is, from a file other than those in the application's main bundle. The argument header identifies the file, as returned by the function objc_loadModule(). The argument name identifies a named section within the file's _ _NIB segment. When no such file exists, the method searches the executable file's bundle, first within its language subdirectories, as described above for the loadNibSection:owner: instance method.
The argument anOwner is the object that corresponds to the ``File's Owner'' object in Interface Builder's File window. Memory for the loaded objects is allocated from the zone specified by zone. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required. Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
A class can use this method in its finishLoading class method to load interface data objects required by the class but stored separately (for example, because the same interface objects are also used by other classes).
Returns non-nil if the section is successfully opened and read.
See also: - loadNibSection:owner:withNames:fromZone:, - awake (Object), - init (Object)
Loads interface objects and their names from the source identified by name. The source may be a section within the executable file, or a file within the application bundle, as described above for the loadNibSection:owner: instance method.
The argument anOwner is the object that corresponds to the ``File's Owner'' object in Interface Builder's File window. When flag is YES, the objects' names are also loaded. Names must be loaded if you use NXGetNamedObject() to get at the objects, but are not otherwise required. Memory for the loaded objects is allocated from the zone specified by zone. Objects that were archived in the nib file (standard objects from an Interface Builder palette) are sent finishUnarchiving and awake messages; other objects are instantiated and are sent an init message.
Returns non-nil if the section or file is successfully opened and read, and nil otherwise.
See also: - loadNibSection:owner:withNames:fromHeader:fromZone:, - awake (Object), - init (Object)
mainMenu - mainMenu
Returns the Application object's main Menu.
mainScreen - (const NXScreen *)mainScreen
Returns the main screen. If there is only one screen, that screen is returned. Otherwise, this method attempts to return the key window's screen. If there is no key window, it attempts to return the main menu's screen. If there is no main menu, this method returns the screen that contains the screen coordinate system origin.
See also: - screen (Window)
mainWindow - mainWindow
Returns the main Window. This method returns nil if there is no main window, if the main window belongs to another application, or if the application is hidden.
Sends the Application object's Windows a message to perform the aSelector method. The message is sent to each Window in turn until one of them returns YES; this method then returns that Window. If no Window returns YES, this method returns nil.
If flag is YES, the Application object's Windows receive the aSelector message in the front-to-back order in which they appear in the Window Server's window list. If flag is NO, Windows receive the message in the order they appear in the Application object's window list. This order generally reflects the order in which the Windows were created.
The method designated by aSelector can't take any arguments.
masterJournaler - masterJournaler
Returns the Application object's master journaler. Journaling is handled by the NXJournaler class.
See also: - slaveJournalar:
miniaturizeAll: - miniaturizeAll:sender
This method miniaturizes all of the receiver's application windows. Returns self.
mounted: - (int)mounted:(const char *)fullPath
Invoked by the Workspace Manager when the device identified by fullPath has completed mounting. You shouldn't directly send a mounted: message. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForDeviceStatusChanges.
If the delegate implements the method app:mounted:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return value is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
Responds to a remote message requesting the application to open a file. openFile:ok: is typically sent to the application from the Workspace Manager, although an application can send it directly to another application. The Application object's delegate is queried with appAcceptsAnotherFile: and if the result is YES, it's sent an app:openFile:type: message. If the delegate doesn't respond to either of these messages, they're sent to the Application object (if it implements them).
The variable pointed to by flag is set to YES if the file is successfully opened, NO if the file is not successfully opened, and -1 if the application does not accept another file. Returns zero.
Displays the data link panel. It does this by sending an orderFront: message to the shared instance of NXDataLinkPanel (if need be, creating a new one). Returns self.
This method is similar to getNextEvent:waitFor:threshold: except the matching event isn't removed from the event queue nor is it placed in currentEvent; instead, it's copied into storage pointed to by eventPtr.
If no matching event is found, NULL is returned; otherwise, eventPtr is returned.
See also: - getNextEvent:waitFor:threshold:, - run, - runModalFor:, - currentEvent
powerOff: - powerOff:(NXEvent *)theEvent
A powerOff: message is generated when a power-off event is sent from the Window Server. As a general rule, only the Workspace Manager and login window should respond to this event. If the application was launched by the Workspace Manager, this method does nothing; instead, the Application object will wait for the powerOffIn:andSave: message from the Workspace Manager. If the application wasn't launched from the Workspace Manager, this method sends the delegate a powerOff: message, assuming there's a delegate and it implements the method. Applications that are not launched from the Workspace Manager are not fully supported, and are not guaranteed any amount of time after receiving this message. However, applications launched from the Workspace Manager can request additional time before shutdown from within the app:powerOffIn:andSave method. Returns self.
See also: - app:powerOffIn:andSave: (delegate method), - powerOffIn:andSave:
You never invoke this method directly; it's sent from the Workspace Manager. The delegate or your subclass of Application will be given the chance to receive the app:powerOffIn:andSave message. The aFlag parameter has no particular meaning and can be ignored. This method raises an exception, so it never returns.
See also: - app:powerOffIn:andSave: (delegate method)
preventWindowOrdering - preventWindowOrdering
Suppresses the usual window ordering behavior entirely. Most applications will not need to use this method since the Application Kit support for dragging will call it when dragging is initiated.
printInfo - printInfo
Returns the Application object's global PrintInfo object. If none exists, a default one is created.
Registers pasteboard types that the application can send and receive in response to service requests. If the application has a Services menu, a menu item is added for each service provider that can accept one of the specified send types or return one of the specified return types. This method should typically be invoked at application startup time or when an object that can use services is created. It can be invoked more than once; its purpose is to ensure that there is a menu item for every service that the application may use. The individual items will be dynamically enabled and disabled by the event handling mechanism to indicate which services are currently appropriate. An application (or object instance that can cut or paste) should register every possible type that it can send and receive. Returns self.
Removes the item for aWindow in the Windows menu. Note that this method doesn't prevent the item from being automatically added again, so you must use Window's setExcludedFromWindowsMenu: method if you want the item to remain excluded from the Windows menu. Returns self.
See also: - changeWindowsItem:title:filename:, - setExcludedFromWindowsMenu: (Window)
replyPort - (port_t)replyPort
Returns the Application object's reply port. This port is allocated for you automatically by the run method, and is the default reply port which can be shared by all the Application object's Speakers.
See also: - setReplyPort: (Speaker)
resignActiveApp - resignActiveApp
This method is invoked immediately after the application is deactivated. You never send resignActiveApp messages directly, but you could override this method in your Application object to notice when your application is deactivated. Alternatively, your delegate could implement appDidResignActive:. Returns self.
See also: - deactivateSelf:, - appDidResignActive: (delegate method)
Initiates the Application object's main event loop. The loop continues until a stop: or terminate: message is received. Each iteration through the loop, the next available event from the Window Server is stored, and is then dispatched by sending the event to the Application object using sendEvent:
A run message should be sent as the last statement from main(), after the application's objects have been initialized. Returns self if terminated by stop:, but never returns if terminated by terminate:.
Establishes a modal event loop for theWindow. Until the loop is broken by a stopModal, stopModal:, or abortModal message, the application won't respond to any mouse, keyboard, or window-close events unless they're associated with theWindow. If stopModal: is used to stop the modal event loop, this method returns the argument passed to stopModal:. If stopModal is used, it returns the constant NX_RUNSTOPPED. If abortModal is used, it returns the constant NX_RUNABORTED. This method is functionally similar to the following:
NXModalSession session;
[NXApp beginModalSession:&session for:theWindow];
for (;;) {
if ([NXApp runModalSession:&session] != NX_RUNCONTINUES)
break;
}
[NXApp endModalSession:&session];
See also: - stopModal, - stopModal:, - abortModal, - runModalSession:
Runs a modal session represented by session, as defined in a previous invocation of beginModalSession:for:. A loop using this method is similar to a modal event loop run with runModalFor:, except that with this method the application can continue processing between method invocations. When you invoke this method, events for the Window of this session are dispatched as normal; this method returns when there are no more events. You must invoke this method frequently enough that the window remains responsive to events.
If the modal session was not stopped, this method returns NX_RUNCONTINUES. If stopModal was invoked as the result of event procession, NX_RUNSTOPPED is returned. If stopModal: was invoked, this method returns the value passed to stopModal:. The NX_abortModal exception raised by abortModal isn't caught.
Sends an action message to an object. If aTarget is nil, the Application object looks for an object that can respond to the message--that is, for an object that implements a method matching aSelector. It begins with the first responder of the key window. If the first responder can't respond, it tries the first responder's next responder and continues following next responder links up the Responder chain. If none of the objects in the key window's responder chain can handle the message, the Application object attempts to send the message to the key Window's delegate.
If the delegate doesn't respond and the main window is different from the key window, NXApp begins again with the first responder in the main window. If objects in the main window can't respond, the Application object attempts to send the message to the main window's delegate. If still no object has responded, NXApp tries to handle the message itself. If NXApp can't respond, it attempts to send the message to its own delegate.
Returns YES if the action is applied; otherwise returns NO.
sendEvent: - sendEvent:(NXEvent *)theEvent
Sends an event to the Application object. You rarely send sendEvent: messages directly although you might want to override this method to perform some action on every event. sendEvent: messages are sent from the main event loop (the run method). sendEvent is the method that dispatches events to the appropriate responders; the Application object handles application events, the Window indicated in the event record handles window related events, and mouse and key events are forwarded to the appropriate Window for further dispatching. Returns self.
See also: - setAutoupdate:
servicesMenu - servicesMenu
Returns the Application object's Services menu. Returns nil if no Services menu has been created.
See also: - setServicesMenu:
setAppListener: - setAppListener:aListener
Sets the Listener that will receive messages sent to the port that's registered for the application. If you want to have a special Listener reply to these messages, you must either send a setAppListener: message before the run message is sent to the Application object, or send this message from the delegate method appWillInit:, so that aListener is properly registered. This method doesn't free the Application object's previous Listener object. Returns self.
See also: - appListenerPortName, - appWillInit: (delegate method)
setAppSpeaker: - setAppSpeaker:aSpeaker
Sets the Application object's Speaker. If you don't send a setAppSpeaker: message before the Application object initializes, a default Speaker is created for you. This method doesn't free the Application object's previous Speaker object.
See also: - appWillInit: (delegate method)
setAutoupdate: - setAutoupdate:(BOOL)flag
Turns on or off automatic updating of the application's windows. (Until this message is sent, automatic updating is not enabled.) When automatic updating is on, an update message is sent to each of the application's Windows after each event has been processed. This can be used to keep the appearance of menus and panels synchronized with your application. Returns self.
See also: - updateWindows
setDelegate: - setDelegate:anObject
Sets the Application object's delegate. The notification messages that a delegate can expect to receive are listed at the end of the Application class specification. The delegate doesn't need to implement all the methods. Returns self.
See also: - delegate
setImportAlpha: - setImportAlpha:(BOOL)flag
Determines whether your application will accept translucent colors in objects it receives. This affects colors imported by the View method acceptsColor:atPoint:, or by NXColorPanel's dragColor:withEvent:fromView:. It has no effect on internal programmatic manipulations of colors.
A pixel may be described by its color (values for red, blue, and green) and also by its opacity, measured by a coefficient called alpha. When alpha is 1.0, a color is completely opaque and thus hides anything beneath it. When alpha is less then 1, the effective color is derived partly from the color of the object itself and partly from the color of whatever is beneath it. When flag is YES, the application accepts a color that includes an alpha coefficient, and forces an alpha value of 1.0 for a source where alpha was not specified. In addition, when flag is YES, a ColorPanel opened within the application includes an opacity slider.
When the Application has received a setImportAlpha: message with flag set to NO, all imported colors are forced to have an alpha value of NX_NOALPHA, and there's no opacity slider in the ColorPanel. The default state is NO, do not import alpha.
This method has the same effect as the NXColorPanel method setShowAlpha:. The only difference is that you can invoke setImportAlpha: even before an NXColorPanel has been instantiated. Since the two methods set the same internal flag, each can reverse the effect of the other.
Returns self.
See also: - doesImportAlpha, - doesShowAlpha (NXColorPanel), - setShowAlpha: (NXColorPanel)
setJournalable: - setJournalable:(BOOL)flag
Sets whether the application is journalable. Returns self. See the class specification for NXJournaler for more information on journaling.
See also: - isJournalable
setMainMenu: - setMainMenu:aMenu
Makes aMenu the Application object's main menu. Returns self.
See also: - mainMenu
setPrintInfo: - setPrintInfo:info
Sets the Application object's global PrintInfo object. Returns the previous PrintInfo object, or nil if there was none.
See also: - printInfo
setServicesMenu: - setServicesMenu:aMenu
Makes aMenu the Application object's Services menu. Returns self.
See also: - servicesMenu
setWindowsMenu: - setWindowsMenu:aMenu
Makes aMenu the Application object's Windows menu. Returns self.
See also: - windowsMenu
showHelpPanel: - showHelpPanel:sender
Shows the application's Help panel. If no Help panel yet exists, the method first creates a default Help panel. If the delegate implements app:willShowHelpPanel:, notifies it. Returns self.
slaveJournaler - slaveJournaler
Returns the Application object's slave journaler if one exists, or nil if not. The slave journaler is created automatically in your application if these two conditions are met:
* Your application allows journaling (see setJournalable:)
* Some application running concurrently with yours (or your application itself) starts a journaling session
See the NXJournaler class specification for more information.
See also: - masterJournalar:
stop: - stop:sender
Stops the main event loop. This method will break the flow of control out of the run method, thereby returning to the main() function. A subsequent run message will restart the loop.
If this method is applied during a modal event loop, it will break that loop but not the main event loop. Returns self.
See also: - terminate:, - run, - runModalFor:, - runModalSession:
stopModal - stopModal
Stops a modal event loop. This method should always be paired with a previous runModalFor: or beginModalSession:for: message. When runModalFor: is stopped with this method, it returns NX_RUNSTOPPED. This method will stop the loop only if it's executed by code responding to an event. If you need to stop a runModalFor: loop from a procedure registered with DPSAddTimedEntry(), DPSAddPort(), or DPSAddFD(), use the abortModal method. Returns self.
See also: - stopModal:, - runModalFor:, - runModalSession:, - abortModal
stopModal: - stopModal:(int)returnCode
Just like stopModal except argument returnCode allows you to specify the value that runModalFor: will return. Returns self.
See also: - stopModal, - runModalFor:, - abortModal
Returns a list of the names of languages in order of the user's preference. If your application will respond to the user's language preference, this method is the way to discover what the preferences are. The return is a NULL-terminated list of pointers to NULL-terminated strings.
If the user has recorded preferences specific to the application now in use, the method returns them. If the user has recorded no preferences for the application, but has recorded a global preference, the method returns the list of global preferences. (Note that just because the user has recorded a preference doesn't mean than the language files are in fact installed on the host that is executing the application.) If this method returns NULL, the user has no language preference.
terminate: - terminate:sender
Terminates the application. (This is the default action method for the application's Quit menu item.) Each use of terminate: invokes appWillTerminate: to notify the delegate that the application will terminate. If appWillTerminate: returns nil, terminate: returns self; control is returned to the main event loop, and the application isn't terminated. Otherwise, this method frees the Application object and calls exit() to terminate the application. Note that you should not put final cleanup code in your application's main() function; it will never be executed.
See also: - stop, - appWillTerminate: (delegate method), exit()
Aids in dispatching action messages. The Application object tries to perform the method aSelector using its inherited Responder method tryToPerform:with:. If the Application object doesn't perform aSelector, the delegate is given the opportunity to perform it using its inherited Object method perform:with:. If either the Application object or the Application object's delegate accept aSelector, this method returns YES; otherwise it returns NO.
Responds to an unhide message sent from Workspace Manager. You shouldn't invoke this method; invoke unhide: instead. Returns zero.
See also: - unhide:
unhide: - unhide:sender
Restores a hidden application to its former state (all of the windows, menus, and panels visible), and makes it the active application. This method is usually invoked as the result of double-clicking the icon for the hidden application. Returns self.
See also: - hide:, - unhideWithoutActivation:, - activateSelf:
Unhides the application but doesn't make it the active application. You might want to invoke activateSelf:NO after invoking this method to make the receiving application active if there is no active application. Returns self.
Invoked by the Workspace Manager when it has completed unmounting the device identified by fullPath. You shouldn't directly send an unmounted: message. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForDeviceStatusChanges.
If the delegate implements the method app:unmounted:, that message is sent to it. If the delegate doesn't implement it, the method is handled by the Application subclass object (if you created one). The return is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
Invoked and sent to all active applications when the Workspace Manager has received a request to unmount the device identified by fullPath. This serves to warn applications that may be making use of the device. You shouldn't directly send unmounting:ok: messages.
The method sets flag to point to YES to indicate that the Application assents to unmounting, and NO if it objects.
If the delegate implements the method app:unmounting:, that message is sent to it, and flag is set to whatever the delegate returns. If the delegate doesn't implement app:unmounting:, the method is handled by the Application subclass object (if you created one). The default behavior is to close all files on the device, and if the current working directory is on the device, to change the current working directory to the user's home directory.
The return value is an arbitrary integer; your application defines and interprets it. If you neither provide a delegate method nor override in a subclass, the default definition simply returns 0.
updateWindows - updateWindows
Sends an update message to the Application object's visible Windows. When automatic updating has been enabled, this method is invoked automatically in the main event loop after each event. An application can also send updateWindows messages at other times to have Windows update themselves.
If the delegate implements appWillUpdate:, that message is sent to the delegate before the windows are updated. Similarly, if the delegate implements appDidUpdate:, that message is sent to the delegate after the windows are updated. Returns self.
Updates the item for aWindow in the Windows menu to reflect the edited status of aWindow. You rarely need to invoke this method because it is invoked automatically when the edited status of a Window is set. Returns self.
See also: - changeWindowsItem:title:filename:, - setDocEdited: (Window)
Passes this message on to the Application object's delegate, if the delegate can respond (and isn't a Responder with its own next responder). If the delegate can't respond or returns nil, this method returns nil, indicating that no object was found that could supply typeSent data for a remote message from the Services menu and accept back typeReturned data. If such an object was found, it is returned.
Messages to perform this method are initiated by the Services menu.
Returns the List object used to keep track of all the Application object's Windows, including Menus, Panels, and the like. In the current implementation, this list also contains global (shared) Windows.
windowsMenu - windowsMenu
Returns the Application object's Windows menu. Returns nil if no Windows menu has been created.
Implement this method to respond to an applicationDidLaunch: message sent from the Workspace Manager to sender (an Application object), informing it that an application named appName has launched. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
Implement this method to respond to an applicationDidTerminate: message sent from the Workspace Manager to sender (an Application object), informing it that an application named appName has terminated. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
Implement this method to respond to an applicationWillLaunch: message sent from the Workspace Manager to sender (an Application object), informing it that an application named appName is about to launch. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForApplicationStatusChanges.
Invoked when the Workspace Manager completes an asynchronous file operation requested by the application. The operation argument is a tag identifying the particular operation requested. It's the same as the integer returned by the method that initiated the request, performFileOperation:source:destination:files:options:.
See also: - performFileOperation:source:destination:files:options: (NXWorkspaceRequestProtocol)
Implement this method to respond to a mounted: message sent from the Workspace Manager to sender (an Application object), informing it that a device (for example a floppy disk or an optical disk) has been mounted. This is one of the messages the Application will receive if it has previously sent the Workspace Manager the message beginListeningForDeviceStatusChanges.
Invoked from within openFile:ok: after it has been determined that the application can open another file. The method should attempt to open the file of type type and name filename, returning YES if the file is successfully opened, and NO otherwise. (Although a file's type may by convention be reflected in its name, type is not a synonym for extension. filename should not exclude part of the name just because it can sometimes be inferred from type.)
This method is also invoked from within openTempFile:ok: if neither the delegate nor the Application subclass responds to app:openTempFile:type:
See also: - openFile:ok:, - openTempFile:ok:, -app:openFileWithoutUI:type:, - app:openTempFile:type:
Sent to the delegate when sender (an Application) requests that the file of type type and name filename be opened as a linked file. The file is to be opened without bringing up its application's user interface; that is, work with the file will be under programmatic control of sender, rather than under keyboard control of the user.
Returns a pointer to the NXDataLinkManager that will coordinate data flow between the two applications.
Invoked from within openTempFile:ok: after it has been determined that the application can open another file. The method should attempt to open the file filename with the extension aType, returning YES if the file is successfully opened, and NO otherwise.
By design, a file opened through this method is assumed to be temporary; it's the application's responsibility to remove the file at the appropriate time.
Invoked from the powerOffIn:andSave: method after the Workspace Manager receives a power-off event. This method is invoked only if the application was launched from the Workspace Manager. The argument ms is the number of milliseconds to wait before powering down or logging out. The argument aFlag has no particular meaning at this time, and can be ignored. You can ask for additional time by sending the extendPowerOffBy:actual: message to the Workspace Manager from within your implementation of this method. The Workspace Manager will power the machine down (or log out the user) as soon as all applications terminate, even if there's time remaining on the time extension.
Implement this method to respond to an unmounted: message sent from the Workspace Manager to sender (an Application object), informing it that the device identified by fullPath has been unmounted. This is one of the messages the Application will receive if it has previously sent the Workspace Manager a beginListeningForDeviceStatusChanges message.
Invoked when the device mounted at fullPath is about to be unmounted. This method is invoked from unmounting:ok: and is invoked only if the application was launched from the Workspace Manager. The Application object or its delegate should do whatever is necessary to allow the device to be unmounted. Specifically, all files on the device should be closed and the current working directory should be changed if it's on the device.
Implement this to respond to notice that sender (an Application) has received a showHelpPanel: message and is about to put up the Help panel identified by panel. The return value doesn't matter.
Invoked from within Application's openFile:ok: and openTempFile:ok: methods, this method should return YES if it's okay for the application to open another file, and NO if isn't. If neither the delegate nor the Application object responds to the message, then the file shouldn't be opened.
See also: - openFile:ok:, - openTempFile:ok:
appDidBecomeActive: - appDidBecomeActive:sender
Implement to respond to notification sent from the Workspace Manager immediately after the Application becomes active.
See also: - applicationDidLaunch:
appDidHide: - appDidHide:sender
Invoked immediately after the application is hidden.
See also: - hide:, - unhide:, - appDidUnhide: (delegate method)
appDidInit: - appDidInit:sender
Invoked after the application has been launched and initialized, but before it has received its first event. The delegate or the Application subclass can implement this method to perform further initialization.
See also: - appWillInit: (delegate method)
appDidResignActive: - appDidResignActive:sender
Invoked immediately after the application is deactivated.
See also: - becomeActiveApp, - resignActiveApp
appDidUnhide: - appDidUnhide:sender
Invoked immediately after the application is unhidden.
See also: - hide:, - unhide:, - appDidHide: (delegate method)
appDidUpdate: - appDidUpdate:sender
Invoked immediately after the Application object updates its Windows.
See also: - updateWindows, - updateWindowsItem:, - appWillUpdate: (delegate method)
Invoked when the application receives an application-defined (NX_APPDEFINED) event. See the description of this method under ``Instance Methods,'' above.
appWillInit: - appWillInit:sender
Invoked before the Application object is initialized. This method is invoked before the Application object has initialized its Listener and Speaker objects and before any app:openFile:type: messages are sent to your delegate. The Application object's Listener and Speaker objects will be created for you immediately after invoking this method if they have not been previously created.
See also: - appDidInit: (delegate method), - appListener, - appSpeaker
appWillTerminate: - appWillTerminate:sender
Invoked from within the terminate: method immediately before the application terminates. If this method returns nil, the application is not terminated, and control is returned to the main event loop. If you want to allow the application to terminate, you should put your clean up code in this method and return non-nil.
See also: - terminate:
appWillUpdate: - appWillUpdate:sender
Invoked immediately before the Application object updates its Windows.
See also: - updateWindows, - updateWindowsItem:, - appDidUpdate: (delegate method)
powerOff: - powerOff:(NXEvent *)theEvent
Invoked from the powerOff: Application method only if the application wasn't launched from the Workspace Manager. Only applications launched from the Workspace Manager are fully supported, so your application isn't guaranteed any amount of processing time after this message is received. This notification is provided mainly for the use of alternate login window programs.
![[Index]](http://enterprise.apple.com/NeXTanswers/images/index.gif)
![[Download]](http://enterprise.apple.com/NeXTanswers/images/Download.gif)
