iOS Developer Library

Developer

Foundation Framework Reference NSTimer Class Reference

Options
Deployment Target:

On This Page
Language:

NSTimer

You use the NSTimer class to create 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 target 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. More...

Inheritance


Conforms To


Import Statement


import Foundation @import Foundation;

Availability


Available in iOS 2.0 and later.
  • Creates and returns a new NSTimer object and schedules it on the current run loop in the default mode.

    Declaration

    Swift

    class func scheduledTimerWithTimeInterval(_ seconds: NSTimeInterval, invocation invocation: NSInvocation, repeats repeats: Bool) -> NSTimer

    Objective-C

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

    Parameters

    seconds

    The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

    invocation

    The invocation to use when the timer fires. The invocation object maintains a strong reference to its arguments until the timer is invalidated.

    repeats

    If YEStrue, the timer will repeatedly reschedule itself until invalidated. If NOfalse, the timer will be invalidated after it fires.

    Return Value

    A new NSTimer object, configured according to the specified parameters.

    Discussion

    After seconds seconds have elapsed, the timer fires, invoking invocation.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a new NSTimer object and schedules it on the current run loop in the default mode.

    Declaration

    Swift

    class func scheduledTimerWithTimeInterval(_ seconds: NSTimeInterval, target target: AnyObject, selector aSelector: Selector, userInfo userInfo: AnyObject?, repeats repeats: Bool) -> NSTimer

    Objective-C

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

    Parameters

    seconds

    The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

    target

    The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to target until it (the timer) is invalidated.

    aSelector

    The message to send to target when the timer fires.

    The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

    • - (void)timerFireMethod:(NSTimer *)timer
    userInfo

    The user info for the timer. The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

    repeats

    If YEStrue, the timer will repeatedly reschedule itself until invalidated. If NOfalse, the timer will be invalidated after it fires.

    Return Value

    A new NSTimer object, configured according to the specified parameters.

    Discussion

    After seconds seconds have elapsed, the timer fires, sending the message aSelector to target.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a new NSTimer object initialized with the specified invocation object.

    Declaration

    Swift

    init(timeInterval seconds: NSTimeInterval, invocation invocation: NSInvocation, repeats repeats: Bool) -> NSTimer

    Objective-C

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

    Parameters

    seconds

    The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead

    invocation

    The invocation to use when the timer fires. The timer instructs the invocation object to maintain a strong reference to its arguments.

    repeats

    If YEStrue, the timer will repeatedly reschedule itself until invalidated. If NOfalse, the timer will be invalidated after it fires.

    Return Value

    A new NSTimer object, configured according to the specified parameters.

    Discussion

    You must add the new timer to a run loop, using addTimer:forMode:. Then, after seconds have elapsed, the timer fires, invoking invocation. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Creates and returns a new NSTimer object initialized with the specified object and selector.

    Declaration

    Swift

    init(timeInterval seconds: NSTimeInterval, target target: AnyObject, selector aSelector: Selector, userInfo userInfo: AnyObject?, repeats repeats: Bool) -> NSTimer

    Objective-C

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

    Parameters

    seconds

    The number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

    target

    The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to this object until it (the timer) is invalidated.

    aSelector

    The message to send to target when the timer fires.

    The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

    • - (void)timerFireMethod:(NSTimer *)timer
    userInfo

    Custom user info for the timer.

    The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

    repeats

    If YEStrue, the timer will repeatedly reschedule itself until invalidated. If NOfalse, the timer will be invalidated after it fires.

    Return Value

    A new NSTimer object, configured according to the specified parameters.

    Discussion

    You must add the new timer to a run loop, using addTimer:forMode:. Then, after seconds seconds have elapsed, the timer fires, sending the message aSelector to target. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Initializes a new NSTimer object using the specified object and selector.

    Declaration

    Swift

    init(fireDate date: NSDate, interval seconds: NSTimeInterval, target target: AnyObject, selector aSelector: Selector, userInfo userInfo: AnyObject?, repeats repeats: Bool)

    Objective-C

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

    Parameters

    date

    The time at which the timer should first fire.

    seconds

    For a repeating timer, this parameter contains the number of seconds between firings of the timer. If seconds is less than or equal to 0.0, this method chooses the nonnegative value of 0.1 milliseconds instead.

    target

    The object to which to send the message specified by aSelector when the timer fires. The timer maintains a strong reference to this object until it (the timer) is invalidated.

    aSelector

    The message to send to target when the timer fires.

    The selector should have the following signature: timerFireMethod: (including a colon to indicate that the method takes an argument). The timer passes itself as the argument, thus the method would adopt the following pattern:

    • - (void)timerFireMethod:(NSTimer *)timer
    userInfo

    Custom user info for the timer. The timer maintains a strong reference to this object until it (the timer) is invalidated. This parameter may be nil.

    repeats

    If YEStrue, the timer will repeatedly reschedule itself until invalidated. If NOfalse, the timer will be invalidated after it fires.

    Return Value

    The receiver, initialized such that, when added to a run loop, it will fire at date and then, if repeats is YEStrue, every seconds after that.

    Discussion

    You must add the new timer to a run loop, using addTimer:forMode:. Upon firing, the timer sends the message aSelector to target. (If the timer is configured to repeat, there is no need to subsequently re-add the timer to the run loop.)

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func fire()

    Objective-C

    - (void)fire

    Discussion

    You can use this method to fire a repeating timer without interrupting its regular firing schedule. If the timer is non-repeating, it is automatically invalidated after firing, even if its scheduled fire date has not arrived.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – invalidate

  • Stops the receiver from ever firing again and requests its removal from its run loop.

    Declaration

    Swift

    func invalidate()

    Objective-C

    - (void)invalidate

    Discussion

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

    If it was configured with target and user info objects, the receiver removes its strong references to those objects as well.

    Special Considerations

    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.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

    See Also

    – fire

  • valid valid Property

    A Boolean value that indicates whether the receiver is currently valid. (read-only)

    Declaration

    Swift

    var valid: Bool { get }

    Objective-C

    @property(readonly, getter=isValid) BOOL valid

    Discussion

    YEStrue if the receiver is still capable of firing or NOfalse if the timer has been invalidated and is no longer capable of firing.

    Import Statement

    import Foundation

    Availability

    Available in iOS 8.0 and later.

  • fireDate fireDate Property

    The date at which the timer will fire.

    Declaration

    Swift

    @NSCopying var fireDate: NSDate

    Objective-C

    @property(copy) NSDate *fireDate

    Discussion

    If the timer is no longer valid, the last date at which the timer fired.

    You can set this property to adjust the firing time of a repeating timer. Although resetting a timer’s next firing time is a relatively expensive operation, it may be more efficient in some situations. For example, you could use it in situations where you want to repeat an action multiple times in the future, but at irregular time intervals. Adjusting the firing time of a single timer would likely incur less expense than creating multiple timer objects, scheduling each one on a run loop, and then destroying them.

    You should not change the fire date of a timer that has been invalidated, which includes non-repeating timers that have already fired. You could potentially change the fire date of a non-repeating timer that had not yet fired, although you should always do so from the thread to which the timer is attached to avoid potential race conditions.

    Use the isValid method to verify that the timer is valid.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • The timer’s time interval. (read-only)

    Declaration

    Swift

    var timeInterval: NSTimeInterval { get }

    Objective-C

    @property(readonly) NSTimeInterval timeInterval

    Discussion

    If the receiver is a non-repeating timer, returns 0 even if a time interval was set.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • userInfo userInfo Property

    The receiver's userInfo object. (read-only)

    Declaration

    Swift

    var userInfo: AnyObject? { get }

    Objective-C

    @property(readonly, retain) id userInfo

    Discussion

    Do not access this property after the timer is invalidated. Use isValid to test whether the timer is valid.

    Import Statement

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • tolerance tolerance Property

    The amount of time after the scheduled fire date that the timer may fire.

    Declaration

    Swift

    var tolerance: NSTimeInterval

    Objective-C

    @property NSTimeInterval tolerance

    Discussion

    The default value is zero, which means no additional tolerance is applied.

    Setting a tolerance for a timer allows it to fire later than the scheduled fire date. Allowing the system flexibility in when a timer fires increases the ability of the system to optimize for increased power savings and responsiveness.

    The timer may fire at any time between its scheduled fire date and the scheduled fire date plus the tolerance. The timer will not fire before the scheduled fire date. For repeating timers, the next fire date is calculated from the original fire date regardless of tolerance applied at individual fire times, to avoid drift. The system reserves the right to apply a small amount of tolerance to certain timers regardless of the value of this property.

    Import Statement

    import Foundation

    Availability

    Available in iOS 7.0 and later.