Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
NSRunLoop
Overview
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 does not need to either create or explicitly manage NSRunLoop objects. Each NSThread, including the application’s main thread, has an NSRunLoop object automatically created for it. If you need to access the current thread’s default run loop, you do so with the class method currentRunLoop.
Warning: The NSRunLoop class is generally not considered to be thread-safe and its methods should only be called within the context of the current thread. You should never try to call the methods of an NSRunLoop object running in a different thread, as doing so might cause unexpected results.
Tasks
Constructors
Accessing the Current Run Loop
Managing Timers
Managing Ports
Running a Loop
Sending Messages
Constructors
NSRunLoop
Creates and returns a new NSRunLoop instance.
public NSRunLoop()
Discussion
Only one run loop is allowed per thread, so if a run loop already exists in the current thread, this method returns null. Use currentRunLoop instead.
Static Methods
currentRunLoop
Returns the NSRunLoop for the current thread.
public static NSRunLoop currentRunLoop()
Discussion
If a run loop does not exist in the thread, one is created and returned.
See Also
Instance Methods
acceptInputForMode
Runs the loop once, blocking for input in mode mode until limitDate.
public void acceptInputForMode(String mode, NSDate limitDate)
See Also
addPortForMode
Adds aPort to be monitored by the receiver in the input mode mode.
public void addPortForMode(NSPort aPort, String mode)
Discussion
The receiver maintains a count of the number of ports added, and the same number must be removed.
See Also
addTimerForMode
Registers the timer aTimer with input mode mode.
public void addTimerForMode(NSTimer aTimer, String mode)
Discussion
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
Returns an array of strings of all the modes defined in the current run loop.
public NSArray allModes()
cancelPerformSelectorWithOrder
Cancels the sending of a message previously scheduled using performSelectorWithOrder.
public void cancelPerformSelectorWithOrder(NSSelector aSelector, Object target, Object anArgument)
Discussion
The aSelector message with argument anArgument will not be sent to target.
containsPortForMode
Returns true if aPort is a member of input mode mode.
public boolean containsPortForMode(NSPort aPort, String mode)
Discussion
Returns false otherwise.
containsTimerForMode
Returns true if aTimer is a member of input mode mode.
public boolean containsTimerForMode(NSTimer aTimer, String mode)
Discussion
Returns false otherwise.
currentMode
Returns the current input mode.
public String currentMode()
Discussion
The current mode is set by the methods that run the run loop, such as acceptInputForMode and runModeBeforeDate.
The currentMode method returns the current input mode ONLY while the receiver is running. Otherwise, currentMode returns null.
See Also
limitDateForMode
Performs one pass through the run loop in mode mode and returns the date at which the next timer is scheduled to fire.
public NSDate limitDateForMode(String mode)
Discussion
Returns null if there are no input sources for this mode. The run loop is entered with an immediate timeout, so the run loop does not block, waiting for input, if no input sources need processing.
performSelectorWithOrder
Schedules the sending of an aSelector message.
public void performSelectorWithOrder(NSSelector aSelector, Object target, Object anArgument, int order, NSArray modes)
Discussion
The aSelector message is sent to target with argument anArgument at the start of the next run loop iteration in any of the input modes specified in modes. order assigns a priority to the messages. If multiple messages are scheduled to be sent, the messages with a lower order value are sent before messages with a higher order value.
This method returns before the aSelector message is sent. The aSelector method should not have a significant return value and should take a single argument of type Object.
Use this method if you want multiple messages to be sent after the current event has been processed and you want to make sure these messages are sent in a certain order.
See Also
portsForMode
Returns an empty array.
public NSArray portsForMode(String aString)
removePortForMode
Removes aPort from the list of ports being monitored by the receiver in input mode mode.
public void removePortForMode(NSPort aPort, String mode)
Discussion
The receiver maintains a count of the ports added, and the same number of ports must be removed. Ports are automatically removed from input modes if they are detected to be invalid.
See Also
removeTimerForMode
Removes aTimer from input mode mode.
public void removeTimerForMode(NSTimer aTimer, String mode)
See Also
run
Runs the loop in DefaultRunLoopMode by repeatedly invoking runModeBeforeDate until all input sources have been removed.
public void run()
Discussion
If there are no input sources in the run loop, it exits immediately.
See Also
runModeBeforeDate
Runs the loop once, blocking for input in mode mode until limitDate.
public boolean runModeBeforeDate(String mode, NSDate limitDate)
Discussion
The method returns after either the first input is processed or limitDate is reached. Returns false without starting the run loop if there are no input sources in mode; otherwise returns true.
See Also
runModeUntilDate
Runs the loop in mode mode by repeatedly invoking runModeBeforeDate until limitDate or until all input sources have been removed.
public boolean runModeUntilDate(String mode, NSDate limitDate)
Discussion
If there are no input sources in the run loop, it exits immediately, returning false.
See Also
timersForMode
Returns an empty array.
public NSArray timersForMode(String mode)
Constants
Cocoa defines the following run loop modes:
Input mode |
Description |
|---|---|
Use this mode to deal with input sources other than NSConnections. This mode is the most commonly used run-loop mode. |
|
|
Use this mode when waiting for input from a modal panel, such as NSSavePanel or NSOpenPanel. |
|
Use this mode for event-tracking loops. |
© 1997, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-07-24)