PATH  Documentation > Mac OS X > Foundation Reference: Java



Table of Contents

NSRunLoop


Inherits from:
NSObject
Package:
com.apple.yellow.foundation


Class Description


The NSRunLoop class declares the programmatic interface to objects that manage input sources. An NSRunLoop processes input for sources such as mouse and keyboard events from the window system, NSPorts, NSTimers, and NSConnections.

In general, your application won't need to either create or explicitly manage NSRunLoop objects. Each thread has an NSRunLoop object automatically created for it. Each process begins with a default thread and therefore has a default run loop.

If you do want to perform your own explicit run loop management, you do so by accessing the current thread's run loop (returned by the class method currentRunLoop). You must specify two things: the input sources, which are the objects from which the run loop will receive information, and an input mode, which specifies the type of input to be received. NSRunLoop defines this input mode:


Input mode Description
DefaultRunLoopMode Use this mode to deal with input sources other than NSConnections. This is the most commonly used run loop mode.

In addition, the Application Kit defines these modes:


Additional input modes Description
NSApplication.ModalPanelRunLoopMode Use this mode when waiting for input from a modal panel, such as NSSavePanel or NSOpenPanel.
NSApplication.EventTrackingRunLoopMode Use this mode for event tracking loops.

You associate a list of input sources with each input mode. There are two general types of input sources to a run loop: asynchronous (input arrives at unpredictable intervals) and synchronous (input arrives at regular intervals). NSPort objects represent asynchronous input sources, and NSTimer objects represent synchronous input sources. Each input source has a limit date associated with it. For NSPorts, the limit date is a timeout value, after which input from that port is no longer timely. For NSTimers, the limit date specifies when the timer should fire. (When a timer fires, it sends a specified message to a specified object, and it may be scheduled to fire again later. See the NSTimer class specification for more information.)

When an NSRunLoop runs, it polls each of the sources for the input mode to determine which one has the earliest limit date. During this polling, the input sources may process any input they have queued. Once the NSRunLoop determines the earliest limit date for this input mode, it waits for input from the operating system until that limit date. If input arrives, it is processed. At that point, the NSRunLoop may either return or it may continue, depending on which method was used to run the loop.

For example:

NSRunLoop theLoop = NSRunLoop.currentRunLoop();
theLoop.acceptInputForMode(NSRunLoopMode,      theLoop.limitDateForMode(NSDefaultRunLoopMode));

The method limitDateForMode returns the earliest limit date of all the input sources for the mode DefaultRunLoopMode. acceptInputForMode runs the loop until that date, processing any input it receives until that time. As a convenience, you can use runModeBeforeDate instead. It invokes acceptInputForMode and limitDateForMode with the mode you supply.

To continuously run in DefaultRunLoopMode, you can use either of the methods run or runModeUntilDate. To run another mode continuously, invoke runModeBeforeDate in a loop with a date far in the future.




Method Types


Constructors
NSRunLoop
Accessing the current run loop
allModes
currentRunLoop
currentMode
limitDateForMode
Managing timers
addTimerForMode
containsTimerForMode
removeTimerForMode
timersForMode
Managing ports
addPortForMode
containsPortForMode
portsForMode
removePortForMode
Running a loop
run
runModeUntilDate
runModeBeforeDate
acceptInputForMode


Constructors



NSRunLoop

public NSRunLoop()

Description forthcoming.


Static Methods



currentRunLoop

public static NSRunLoop currentRunLoop()

Returns the NSRunLoop for the current thread.

See Also: currentMode




Instance Methods



acceptInputForMode

public void acceptInputForMode( String mode, NSDate limitDate)

Blocks awaiting input from the ports in the port list for the input mode mode until the time specified by limitDate. Use the limitDateForMode method to calculate limitDate. If input arrives, it is processed using the NSPort delegates. This method does not check the timers associated with mode, thus it does not fire timers even if their scheduled fire dates have passed.

addPortForMode

public void addPortForMode( NSPort aPort, String mode)

Adds aPort to be monitored by the receiver in the input mode mode. The receiver maintains a count of the number of ports added, and the same number must be removed.

See Also: removePortForMode



addTimerForMode

public void addTimerForMode( NSTimer aTimer, String aString)

Registers the timer aTimer with input mode mode. The run loop causes the timer to fire on or after its scheduled fire date. Timers have a message associated with them. When a timer fires, it sends its message to the appropriate object. To remove a timer from a mode, send the invalidate message to the timer.

allModes

public NSArray allModes()

Description forthcoming.

containsPortForMode

public boolean containsPortForMode( NSPort aPort, String mode)

Description forthcoming.

containsTimerForMode

public boolean containsTimerForMode( NSTimer aTimer, String mode)

Description forthcoming.

currentMode

public String currentMode()

Returns the current input mode. The current mode is set by limitDateForMode and acceptInputForMode. currentMode returns the current input mode ONLY while the receiver is running. Otherwise, currentMode returns null.

See Also: currentRunLoop



limitDateForMode

public NSDate limitDateForMode(String mode)

Polls mode's input sources for their limit date (if any) and returns the earliest limit date for this mode. Fires timers if their limit dates have passed. Polls ports for activities appropriate for mode. Returns null if there are no input sources for this mode.

portsForMode

public NSArray portsForMode(String aString)

Description forthcoming.

removePortForMode

public void removePortForMode( NSPort aPort, String mode)

Removes aPort from the list of ports being monitored by the receiver in input mode mode. The receiver maintains a count of the ports added, and the same number of ports must be removed. Ports are automatically removed from modes if they are detected to be invalid.

See Also: addPortForMode



removeTimerForMode

public void removeTimerForMode( NSTimer aTimer, String mode)

Description forthcoming.

run

public void run()

Runs the loop in NSDefaultRunLoopMode by repeatedly invoking runModeBeforeDate until the limit dates for all input sources have passed.

See Also: runModeUntilDate



runModeBeforeDate

public boolean runModeBeforeDate( String mode, NSDate limitDate)

Runs the loop once by invoking acceptInputForMode, accepting input for mode mode until a limit date. The limit date is determined by using the earliest of limitDate and the limit dates set for all input sources in this mode. Returns false without starting the run loop if the limit dates for all of mode's input sources have passed; otherwise returns true.

runModeUntilDate

public boolean runModeUntilDate( String mode, NSDate limitDate)

Runs the loop in DefaultRunLoopMode by repeatedly invoking runModeBeforeDateuntil limitDate or until the limit dates for all of the input sources have passed.

See Also: run



timersForMode

public NSArray timersForMode(String aString)

Description forthcoming.


Table of Contents