Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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 NSRunLoopÐsend 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. 

Firing the Timer 

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

Stopping the Timer 

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

Getting Information About the NSTimer

- (NSDate *)fireDate	Returns the date that the NSTimer will next fire.

- userInfo	Additional data that the object receiving NSTimer's message can use.