Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

NSTimer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in Mac OS X v10.0 and later.
Declared in
NSTimer.h
Companion guides

Overview

NSTimer creates timer objects or, more simply, timers. A timer 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 object that sends a message to a window, telling it to update itself after a certain time interval.

Timers work in conjunction with run loops. To use a timer effectively, you should be aware of how run loops operate—see NSRunLoop and Run Loops. Note in particular that run loops retain their timers, so you can release a timer after you have added it to a run loop. Moreover, timers may not fire exactly when scheduled.

There are three ways to create a timer. The scheduledTimerWithTimeInterval:invocation:repeats: and scheduledTimerWithTimeInterval:target:selector:userInfo:repeats: class methods automatically add the new timer to the current NSRunLoop object in the default mode (NSDefaultRunLoopMode). The timerWithTimeInterval:invocation:repeats: and timerWithTimeInterval:target:selector:userInfo:repeats: class methods create timers that you may add to a run loop at a later time by sending the message addTimer:forMode: to the NSRunLoop object. Finally, you can allocate the timer directly and initialize it with initWithFireDate:interval:target:selector:userInfo:repeats:, which allows you to specify both an initial fire date and a repeating interval. If you specify that the timer should repeat, it automatically reschedules itself after it fires. If you specify that the timer should not repeat, it is automatically invalidated after it fires.

To request the removal of a timer from an NSRunLoop object, send the timer the invalidate message from the same thread on which the timer was installed. This message immediately disables the timer, so it no longer affects the NSRunLoop object. The run loop removes and releases the timer, either just before the invalidate method returns or at some later point.

NSTimer is “toll-free bridged” with its Core Foundation counterpart, CFRunLoopTimer. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSTimer * parameter, you can pass a CFRunLoopTimerRef, and in a function where you see a CFRunLoopTimerRef parameter, you can pass an NSTimer instance (you cast one type to the other to suppress compiler warnings). See Interchangeable Data Types for more information on toll-free bridging.

Tasks

Creating a Timer

Firing a Timer

Stopping a Timer

Information About a Timer

Class Methods

scheduledTimerWithTimeInterval:invocation:repeats:

Returns a new NSTimer object and adds it to the current NSRunLoop object in the default mode.

+ (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)invocation repeats:(BOOL)repeats

Discussion

After seconds have elapsed, the timer fires, sending the message in invocation to its target. If seconds is less than or equal to 0.0, this method chooses a nonnegative interval. If repeats is YES, the timer will repeatedly reschedule itself until invalidated. If repeats is NO, the timer will be invalidated after it fires.

Availability
Declared In
NSTimer.h

scheduledTimerWithTimeInterval:target:selector:userInfo:repeats:

Returns a new NSTimer object and adds it to the current NSRunLoop object in the default mode.

+ (NSTimer *)scheduledTimerWithTimeInterval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats

Discussion

After seconds have elapsed, the timer fires, sending the message aSelector to target. The aSelector method has the following syntax:

- (void)myTimerFireMethod:(NSTimer*)theTimer

The timer passes itself as the argument to aSelector. To pass more information to the target, use userInfo. The target gets userInfo by sending userInfo to the timer.

If seconds is less than or equal to 0.0, this method chooses a nonnegative interval. If repeats is YES, the timer will repeatedly reschedule itself until invalidated. If repeats is NO, the timer will be invalidated after it fires.

Availability
Declared In
NSTimer.h

timerWithTimeInterval:invocation:repeats:

Returns a new NSTimer that, when added to a run loop, will fire after seconds.

+ (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds invocation:(NSInvocation *)invocation repeats:(BOOL)repeats

Discussion

If seconds is less than or equal to 0.0, this method chooses a nonnegative interval. Upon firing, the timer sends the message in invocation to its target. If repeats is YES, the timer will repeatedly reschedule itself until invalidated. If repeats is NO, the timer will be invalidated after it fires.

Availability
Declared In
NSTimer.h

timerWithTimeInterval:target:selector:userInfo:repeats:

Returns a new NSTimer that, when added to a run loop, will fire after seconds.

+ (NSTimer *)timerWithTimeInterval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats

Discussion

Upon firing, the timer sends aSelector to target. The aSelector method has the following syntax:

- (void)myTimerFireMethod:(NSTimer*)theTimer

The timer passes itself as the argument to aSelector. To pass more information to the target, use userInfo. The target gets userInfo by sending userInfo to the timer.

If seconds is less than or equal to 0.0, this method chooses a nonnegative interval. If repeats is YES, the timer will repeatedly reschedule itself until invalidated. If repeats is NO, the timer will be invalidated after it fires.

Availability
Declared In
NSTimer.h

Instance Methods

fire

Causes the receiver’s message to be sent to its target.

- (void)fire

Discussion

If the timer is non-repeating, it is automatically invalidated after firing, even if its scheduled fire date has not arrived. A repeating timer can be fired with this method without interrupting its regular firing schedule.

Availability
See Also
Declared In
NSTimer.h

fireDate

Returns the date at which the receiver will fire.

- (NSDate *)fireDate

Return Value

The date at which the receiver will fire. If the timer is no longer valid, this method returns the last date at which the timer fired.

Discussion

Use isValid to verify that the timer is valid.

Availability
See Also
Declared In
NSTimer.h

initWithFireDate:interval:target:selector:userInfo:repeats:

Initializes a new NSTimer that, when added to a run loop, will fire at date and then, if repeats is YES, every seconds after that.

- (id)initWithFireDate:(NSDate *)date interval:(NSTimeInterval)seconds target:(id)target selector:(SEL)aSelector userInfo:(id)userInfo repeats:(BOOL)repeats

Discussion

Upon firing, the timer sends aSelector to target. The aSelector method has the following syntax:

- (void)myTimerFireMethod:(NSTimer*)theTimer

The timer passes itself as the argument to aSelector. To pass more information to the target, use userInfo. The target gets userInfo by sending userInfo to the timer.

Availability
Declared In
NSTimer.h

invalidate

Stops the receiver from ever firing again and requests its removal from its NSRunLoop object.

- (void)invalidate

Discussion

This is the only way to remove a timer from an NSRunLoop object. The NSRunLoop object removes and releases the timer, either just before the invalidate method returns or at some later point.

You must send this message from the thread on which the timer was installed. If you send this message from another thread, the input source associated with the timer may not be removed from its run loop, which could prevent the thread from exiting properly.

The receiver releases its references to the target and userInfo objects at the point of invalidation.

Availability
See Also
Declared In
NSTimer.h

isValid

Returns a Boolean value that indicates whether the receiver is currently valid.

- (BOOL)isValid

Return Value

YES if the receiver is currently valid, otherwise NO.

Availability
Declared In
NSTimer.h

setFireDate:

Resets the receiver to fire next at a given date.

- (void)setFireDate:(NSDate *)date

Parameters
date

The date at which to fire the receiver.

Availability
See Also
Declared In
NSTimer.h

timeInterval

Returns the receiver’s time interval.

- (NSTimeInterval)timeInterval

Return Value

The receiver’s time interval. If the receiver is a non-repeating timer, returns 0 (even if a time interval was set).

Availability
Declared In
NSTimer.h

userInfo

Returns the receiver's userInfo object.

- (id)userInfo

Return Value

The receiver's userInfo object, containing additional data the target may use when the receiver is fired.

Discussion

Do not invoke this method after the timer is invalidated. Use isValid to test whether the timer is valid.

Availability
See Also
Declared In
NSTimer.h

Next Page > Hide TOC

Last updated: 2006-09-20

Did this document help you?
Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.
Get information on Apple products.
Visit the Apple Store online or at retail locations.
1-800-MY-APPLE

Copyright © 2007 Apple Inc.
All rights reserved. | Terms of use | Privacy Notice