Clock object¶
The Clock object allows you to schedule a function call in the future; once or on interval:
def my_callback(dt):
pass
# call my_callback every 0.5 seconds
Clock.schedule_interval(my_callback, 0.5)
# call my_callback in 5 seconds
Clock.schedule_once(my_callback, 5)
# call my_callback as soon as possible (usually next frame.)
Clock.schedule_once(my_callback)
Note
If the callback returns False, the schedule will be removed.
If you want to schedule a function to call with default arguments, you can use functools.partial python module:
from functools import partial
def my_callback(value, key, *largs):
pass
Clock.schedule_interval(partial(my_callback, 'my value', 'my key'), 0.5)
Important
The callback is weak-referenced: you are responsible to keep a reference to your original object/callback. If you don’t keep a reference, the Clock will never execute your callback. For example:
class Foo(object):
def start(self):
Clock.schedule_interval(self.callback)
def callback(self, dt):
print 'In callback'
# a Foo object is created, the method start is called,
# and the instance of foo is deleted
# Because nobody keep a reference to the instance returned from Foo(),
# the object will be collected by Python Garbage Collector. And you're
# callback will be never called.
Foo().start()
# So you must do:
foo = Foo()
foo.start()
# and keep the instance of foo, until you don't need it anymore!
Schedule before frame¶
New in version 1.0.5.
Sometimes you need to schedule a callback BEFORE the next frame. Starting from 1.0.5, you can use a timeout of -1:
Clock.schedule_once(my_callback, 0) # call after the next frame
Clock.schedule_once(my_callback, -1) # call before the next frame
The Clock will execute all the callbacks with a timeout of -1 before the next frame, even if you add a new callback with -1 from a running callback. However, Clock has an iteration limit for these callbacks, it defaults to 10.
If you schedule a callback that schedules a callback that schedules a .. etc more than 10 times, it will leave the loop and send a warning to the console, then continue after the next frame. This is implemented to prevent bugs from hanging or crashing the application.
If you need to increase the limit, set the max_iteration property:
from kivy.clock import Clock
Clock.max_iteration = 20
Triggered Events¶
New in version 1.0.5.
A triggered event is a way to defer a callback exactly like schedule_once(), but with some added convenience. The callback will only be scheduled once per frame, even if you call the trigger twice (or more). This is not the case with Clock.schedule_once():
# will run the callback twice before the next frame
Clock.schedule_once(my_callback)
Clock.schedule_once(my_callback)
# will run the callback once before the next frame
t = Clock.create_trigger(my_callback)
t()
t()
Before triggered events, you may have used this approach in a widget:
def trigger_callback(self, *largs):
Clock.unschedule(self.callback)
Clock.schedule_once(self.callback)
As soon as you call trigger_callback(), it will correctly schedule the callback once in the next frame. It is more convenient to create and bind to the triggered event than using Clock.schedule_once() in a function:
from kivy.clock import Clock
from kivy.uix.widget import Widget
class Sample(Widget):
def __init__(self, **kwargs):
self._trigger = Clock.create_trigger(self.cb)
super(Sample, self).__init__(**kwargs)
self.bind(x=self._trigger, y=self._trigger)
def cb(self, *largs):
pass
Even if x and y changes within one frame, the callback is only run once.
Note
Clock.create_trigger() also has a timeout parameter that behaves exactly like Clock.schedule_once().
- kivy.clock.Clock = None¶
Instance of the ClockBase, available for everybody
- class kivy.clock.ClockBase¶
Bases: object
A clock object with event support
- create_trigger(callback, timeout=0)¶
Create a Trigger event. Check module documentation for more information.
New in version 1.0.5.
- frametime¶
Time spent between last frame and current frame (in seconds)
- get_boottime()¶
Get time in seconds from the application start
- get_fps()¶
Get the current average FPS calculated by the clock
- get_rfps()¶
Get the current “real” FPS calculated by the clock. This counter reflects the real framerate displayed on the screen.
In contrast to get_fps(), this function returns a counter of the number of frames, not an average of frames per second
- get_time()¶
Get the last tick made by the clock
- max_iteration¶
New in version 1.0.5: When a schedule_once is used with -1, you can add a limit on how iteration will be allowed. That is here to prevent too much relayout.
- schedule_interval(callback, timeout)¶
Schedule an event to be called every <timeout> seconds
- schedule_once(callback, timeout=0)¶
Schedule an event in <timeout> seconds.
Changed in version 1.0.5: If the timeout is -1, the callback will be called before the next frame (at tick_draw()).
- tick()¶
Advance clock to the next step. Must be called every frame. The default clock have the tick() function called by Kivy
- tick_draw()¶
Tick the drawing counter
- unschedule(callback)¶
Remove a previously scheduled event.