NSTimer

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSTimer.h

Class Description

NSTimer creates timer objects. A timer object waits until a certain time interval has elapsed and then fires, sending a specified message to a specified object. For example, you could create an NSTimer that sends a message to a window, telling it to update itself, after a certain time interval.

NSTimer objects work in conjunction with NSRunLoop objects. NSRunLoops control loops that wait for input, and they use NSTimers to help determine the maximum amount of time they should wait. When the NSTimer's time limit has elapsed, the NSRunLoop fires the NSTimer (causing its message to be sent), then checks for new input.

There are several ways to create an NSTimer object. The scheduledTimerWithTimeInterval... class methods automatically register the new NSTimer with the current NSRunLoop object in default mode. The timerWithTimeInterval... class methods create NSTimers that the user may register at a later time by sending the message addTimer:forMode: to the NSRunLoop. If you specify that the NSTimer should repeat, it will automatically reschedule itself after it fires. If a delay occurs when a timer is scheduled to fire, the timer will not fire. For example, suppose you used the following statement to create a timer:

timer = [NSTimer scheduledTimerWithTimeInterval:0.5 invocation:anInvocation repeats:YES];

This statement creates a timer will schedule itself to fire after 0.5 seconds, 1 second, 1.5 seconds, and so on from the time this statement is executed. Suppose there was a 2 second delay because NSRunLoop was busy processing input. The timer takes this delay into consideration and will skip intervals that were already missed when computing the next scheduled fire date.

There is no method that removes the association of an NSTimer from an NSRunLoopsend the NSTimer the invalidate message instead. invalidate disables the NSTimer, so it will no longer affect the NSRunLoop.

See the NSRunLoop class description for more information on NSRunLoops.

As a consequence of being a subclass of NSObject, NSTimer conforms to the NSCoding protocol. In practice, however, NSTimers are not encoded nor archived.

Creating a Timer Object

• + (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)anInvocation Returns a new NSTimer object and registers it with the repeats:(BOOL)repeats current NSRunLoop in the default mode. After seconds seconds have elapsed, the NSTimer fires, sending anInvocation's message to its target. If repeats is YES, the NSTimer will repeatedly reschedule itself.
• + (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds target:(id)anObject Returns a new NSTimer object and registers it with the selector:(SEL)aSelector current NSRunLoop in the default mode. After seconds userInfo:(id)anArgument seconds have elapsed, the NSTimer fires, sending the repeats:(BOOL)repeats message [anObject aSelector:self]. If anObject needs more information, it can send the NSTimer a userData message to retrieve anArgument. If repeats is YES, the NSTimer will repeatedly reschedule itself.
• + (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)anInvocation Returns a new NSTimer that, if registered, will fire after repeats:(BOOL)repeats seconds seconds. Upon firing, the NSTimer sends anInvocation's message to its target. If repeats is YES, the NSTimer will repeatedly reschedule itself.
• + (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds target:(id)anObject Returns a new NSTimer that, if registered, will fire after selector:(SEL)aSelector seconds seconds. Upon firing, the NSTimer sends the userInfo:(id)anArgument message [anObject aSelector:self]. If anObject needs repeats:(BOOL)repeats more information, it can send the NSTimer a userData message to retrieve anArgument. If repeats is YES, the NSTimer will repeatedly reschedule itself.

• - (void)fire Causes the NSTimer's message to be dispatched to its target.

• - (void)invalidate Stops the NSTimer from ever firing again.

• - (NSDate *)fireDate Returns the date that the NSTimer will next fire.
• - userInfo Additional data that the object receiving NSTimer's message can use.