diff --git a/kivy/clock.py b/kivy/clock.py index e3a8bf9d1..6e9dd538a 100644 --- a/kivy/clock.py +++ b/kivy/clock.py @@ -3,7 +3,7 @@ Clock object ============ The :class:`Clock` object allows you to schedule a function call in the -future; once or on interval:: +future; once or repeatedly at specified intervals:: def my_callback(dt): pass @@ -22,7 +22,7 @@ future; once or on interval:: 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 +the `functools.partial `_ python module:: @@ -34,9 +34,9 @@ module:: Clock.schedule_interval(partial(my_callback, 'my value', 'my key'), 0.5) Conversely, if you want to schedule a function that doesn't accept the dt -argument, you can use `lambda +argument, you can use a `lambda `_ expression -to write a short function that does accept dt. For Example:: +to write a short function that does accept dt. For Example:: def no_args_func(): print("I accept no arguments, so don't schedule me in the clock") @@ -47,13 +47,13 @@ to write a short function that does accept dt. For Example:: You cannot unschedule an anonymous function unless you keep a reference to it. It's better to add \*args to your function definition so that it can be - called with or without the clock. + called with an arbitrary number of parameters. .. 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:: + The callback is weak-referenced: you are responsible for keeping a reference + to your original object/callback. If you don't keep a reference, the ClockBase + will never execute your callback. For example:: class Foo(object): def start(self): @@ -62,18 +62,17 @@ to write a short function that does accept dt. For Example:: 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. + # A Foo object is created and the method start is called. + # Because no reference is kept to the instance returned from Foo(), + # the object will be collected by the Python Garbage Collector and + # your callback will be never called. Foo().start() - # So you must do: + # So you should do the following and keep a reference to the instance + # of foo until you don't need it anymore! foo = Foo() foo.start() - # and keep the instance of foo, until you don't need it anymore! .. _schedule-before-frame: @@ -89,8 +88,8 @@ from 1.0.5, you can use a timeout of -1:: 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, :class:`Clock` has an iteration limit for these callbacks, it defaults +the next frame even if you add a new callback with -1 from a running callback. +However, :class:`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 @@ -112,7 +111,7 @@ Triggered Events 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 +frame even if you call the trigger twice (or more). This is not the case with :func:`Clock.schedule_once`:: # will run the callback twice before the next frame @@ -150,8 +149,8 @@ Even if x and y changes within one frame, the callback is only run once. .. note:: - :func:`Clock.create_trigger` also has a timeout parameter that behaves - exactly like :func:`Clock.schedule_once`. + :func:`ClockBase.create_trigger` also has a timeout parameter that behaves + exactly like :func:`ClockBase.schedule_once`. ''' @@ -321,7 +320,7 @@ class ClockEvent(object): class ClockBase(_ClockBase): - '''A clock object with event support + '''A clock object with event support. ''' __slots__ = ('_dt', '_last_fps_tick', '_last_tick', '_fps', '_rfps', '_start_tick', '_fps_counter', '_rfps_counter', '_events', @@ -350,13 +349,15 @@ class ClockBase(_ClockBase): @property def frametime(self): - '''Time spent between last frame and current frame (in seconds) + '''Time spent between the last frame and the current frame + (in seconds). ''' return self._dt def tick(self): - '''Advance clock to the next step. Must be called every frame. - The default clock have the tick() function called by Kivy''' + '''Advance the clock to the next step. Must be called every frame. + The default clock has a tick() function called by the core Kivy + framework.''' self._release_references() if self._fps_counter % 100 == 0: @@ -397,13 +398,13 @@ class ClockBase(_ClockBase): return self._dt def tick_draw(self): - '''Tick the drawing counter + '''Tick the drawing counter. ''' self._process_events_before_frame() self._rfps_counter += 1 def get_fps(self): - '''Get the current average FPS calculated by the clock + '''Get the current average FPS calculated by the clock. ''' return self._fps @@ -412,16 +413,16 @@ class ClockBase(_ClockBase): 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 + of frames, not the average of frames per second. ''' return self._rfps def get_time(self): - '''Get the last tick made by the clock''' + '''Get the last tick made by the clock.''' return self._last_tick def get_boottime(self): - '''Get time in seconds from the application start''' + '''Get the time in seconds from the application start.''' return self._last_tick - self._start_tick def create_trigger(self, callback, timeout=0): @@ -454,7 +455,7 @@ class ClockBase(_ClockBase): return event def schedule_interval(self, callback, timeout): - '''Schedule an event to be called every seconds''' + '''Schedule an event to be called every seconds.''' if not callable(callback): raise ValueError('callback must be a callable, got %s' % callback) cid = _hash(callback) @@ -535,12 +536,12 @@ class ClockBase(_ClockBase): def mainthread(func): '''Decorator that will schedule the call of the function in the mainthread. - It can be useful when you use :class:`~kivy.network.urlrequest.UrlRequest`, + It can be useful when you use :class:`~kivy.network.urlrequest.UrlRequest` or when you do Thread programming: you cannot do any OpenGL-related work in a thread. - Please note that this method will return directly, and no result can be - fetched:: + Please note that this method will return directly and no result can be + returned:: @mainthread def callback(self, *args): @@ -558,7 +559,7 @@ def mainthread(func): return delayed_func if 'KIVY_DOC_INCLUDE' in environ: - #: Instance of the ClockBase, available for everybody + #: Instance of :class:`ClockBase`. Clock = None else: Clock = register_context('Clock', ClockBase)