The timer library supports scheduling tasks (e.g., animation) through Timer objects.

Timer objects schedule how often to perform a task (i.e., how often to call a function), and specify if the execution will be done once or repeatedly (using a time interval).

For example, the following:

from timer import *

def test():
   print "It's ticking..."
   
t = Timer(500, test)
t.start()

will print “It’s ticking…” continuously, every half second. 

To create a Timer use the following:

Function

Description

Timer(delay, function, parameters, repeat)

Creates a new Timer to execute function after delay time interval (in milliseconds).   Parameter parameters is an optional list of parameters to pass to the function when called (default is [] – i.e., no parameters). Parameter repeat is also optional (a boolean) to indicate if the timer will repeat indefinitely (default – True), or go only once (False). NOTE:  Provided function should expect as many parameters, as the length of the parameters list (default is no parameters). CAUTION:  The list of parameters is evaluated only at timer creation, so even if their values change later, only the original values will be used.

Here is another example:

from timer import *
from music import *

t = Timer(500, Play.noteOn, [A4], True)
t.start()

This creates a Timer t, which every 500 milliseconds (i.e., half second) calls function Play.noteOn(A4) repeatedly.  Notice that the parameters to the function as provided as a separate list (i.e., [A4] above).

Remember that, for a timer to begin ticking, it needs to get started:

t.start()

---

Here is one more example, involving graphics animation:

from gui import *
from timer import *

d = Display()

# create a circle to move
c = Circle(50, 50, 30, Color.RED, True)
d.add(c)

# function to move circle a number of pixels on the diagonal,
# when called
def moveCircle(incrementX, incrementY):
   
   global d, c
   
   x = c.getX()
   y = c.getY()
   
   d.move(c, x + incrementX, y + incrementY)
   
# create timer to call move function every 0.5 sec
parameters = [5, 5]
t = Timer(500, moveCircle, parameters, True)
t.start()   # and start it!!

NOTE: If you wish to change the values being passed to function moveCircle(), while the Timer is running… you may change the contents of list parameters, i.e., parameters[0] = 3, and parameters[1] = 12.

However, if you redefine the variable parameters, i.e., parameters = [3, 12], the Timer will keep sending the original values, i.e., [5, 5].

Explanation: The Timer object only stores the location of the original list parameters, so you may change its contents, and get the desired result. This is known as shallow-copy (which is what the Timer does) vs. deep-copy – an advanced topic.

---

Once a Timer t has been created, the following functions are available:

Function	Description
t.start()	Starts timer t.
t.stop()	Stops timer t.
t.getDelay()	Returns the delay time interval of timer t (in milliseconds).
t.setDelay(delay)	Sets a new delay time interval for timer t (in milliseconds).  This allows to change the speed of the animation, after some event occurs.
t.isRunning()	Returns True if timer t is running (has been started), False otherwise.
t.setFunction(function, parameters)	Sets the function to execute.  The optional parameter parameters is a list of parameters to pass to the function (when called).
t.getRepeat()	Returns True if timer t is set to repeat, False otherwise.
t.setRepeat(flag)	If flag is True, timer t is set to repeat (this also starts the timer, if stopped).  Otherwise, if flag is False, timer t is set to not repeat (this stops the timer, if running).