public class
Timer

extends Object

Inheritance

Class Overview

This class provides a very simple API for calling methods either once or repeatedly after a delay. Instead of creating objects of this class using the new keyword, you can use the following static "factory" methods to queue up delayed method calls in the background:

callOnce(Object receiver, String methodName, long delay)
Requests that an object's method be called once after a number of milliseconds has passed.
callRepeatedly(Object receiver, String methodName, long delay)
Requests that an object's method be called repeatedly after a number of milliseconds has passed.
callRepeatedly(Object receiver, String methodName, long initialDelay, long repeatDelay)
Requests that an object's method be called repeatedly, with separate controls over the initial delay (before the first call) and the repeat delay (between subsequent calls).

Each of these methods returns a Timer object, which can be stored and used later if necessary. For example, you may want to keep the timer in a field so that you can stop the repetition in response to a user action (like a button click) or some other external event.

Methods the timer can call

The method whose name is passed to these factory methods must be public, take no arguments, and return either void or boolean. Be careful: if a method with the correct name is found but the arguments do not match, then no error will be produced at runtime, and the method will simply not be called.

The version of the method that returns boolean is useful for timers created by callRepeatedly. In this case, returning true will cause the timer to stop (and the method will not be called again), or returning true will cause the timer to continue processing and fire again after the delay. If the method returns void instead, then the timer will run indefinitely, until it is stopped by calling stop().

Automatic lifecycle management

If the receiver for the timed method call is a Screen, then the timer will be automatically managed as part of the screen's lifecycle; the timer will be paused and resumed automatically during the screen's onPause and onResume methods, respectively.

If the method receiver is another object, then you will manually pause and resume the timer. Backing out of an activity or leaving the application does not automatically stop the timer, in most cases.

Threading concerns

Timed methods are always called on the main GUI thread, regardless of which thread they are started on. This is to avoid problems when users might want to start timed method calls on the physics thread (for example, in reaction to a collision between shapes).

Summary

Public Methods
static Timer callOnce(Object receiver, String methodName, long delay)
Calls a method once after the specified delay.
static Timer callRepeatedly(Object receiver, String methodName, long initialDelay, long repeatDelay)
Calls a method repeatedly, providing separate control over the initial delay (time before the first call) and the repetition delay (time between subsequent calls).
static Timer callRepeatedly(Object receiver, String methodName, long delay)
Calls a method repeatedly, waiting the specified amount of time between each call (and before the first call).
boolean isRunning()
Gets a value indicating whether or not the timer is currently running.
void start()

Starts the timer if it has been previously stopped.

void stop()
Stops the timer, preventing it from firing in the future.
Methods inherited from class java.lang.Object
Object clone()
boolean equals(Object arg0)
void finalize()
final Class<?> getClass()
int hashCode()
final void notify()
final void notifyAll()
String toString()
final void wait()
final void wait(long arg0, int arg1)
final void wait(long arg0)

Public Methods

public static Timer callOnce (Object receiver, String methodName, long delay)

Calls a method once after the specified delay.

Parameters
receiver
the object on which the method will be called
methodName
the name of the method to call
delay
the delay, in milliseconds
Returns

the Timer object, which you can use to execute finer grained control over the timer if needed

public static Timer callRepeatedly (Object receiver, String methodName, long initialDelay, long repeatDelay)

Calls a method repeatedly, providing separate control over the initial delay (time before the first call) and the repetition delay (time between subsequent calls).

Parameters
receiver
the object on which the method will be called
methodName
the name of the method to call
initialDelay
the delay, in milliseconds, before the first call
repeatDelay
the delay, in milliseconds, between subsequent calls to the method
Returns

the Timer object, which you can use to execute finer grained control over the timer if needed

public static Timer callRepeatedly (Object receiver, String methodName, long delay)

Calls a method repeatedly, waiting the specified amount of time between each call (and before the first call).

Parameters
receiver
the object on which the method will be called
methodName
the name of the method to call
delay
the delay, in milliseconds, before the first call and between subsequent calls
Returns

the Timer object, which you can use to execute finer grained control over the timer if needed

public boolean isRunning ()

Gets a value indicating whether or not the timer is currently running.

Returns

true if the timer is running, or false if it is not

public void start ()

Starts the timer if it has been previously stopped.

Calling one of the factory methods (#callDelayed(Object, String, long), callRepeatedly(Object, String, long), or callRepeatedly(Object, String, long, long) will create a timer that is started immediately, so you do not need to call the start method on it. This method exists so that you can restart a timer that you have previously called stop() on.

public void stop ()

Stops the timer, preventing it from firing in the future. To restart the timer, call its start() method.