目录

时钟对象

Clock 对象允许您在未来安排函数调用；可以是一次性的，也可以按指定间隔重复执行。您可以通过 dt 参数获取从调度到回调调用之间经过的时间:

# dt means delta-time
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)

备注

如果回调返回 False，则计划将被取消，不会重复执行。

如果你想使用默认参数调度一个函数调用，可以使用 Python 的 functools.partial 模块：：

from functools import partial

def my_callback(value, key, *largs):
    pass

Clock.schedule_interval(partial(my_callback, 'my value', 'my key'), 0.5)

相反，如果你想要调度一个不接受 dt 参数的函数，你可以使用 lambda 表达式来编写一个接受 dt 的简短函数。例如：：

def no_args_func():
    print("I accept no arguments, so don't schedule me in the clock")

Clock.schedule_once(lambda dt: no_args_func(), 0.5)

备注

无法取消调度匿名函数，除非你保留对它的引用。最好在函数定义中添加 *args，以便它能接受任意数量的参数调用。

重要

类方法回调是弱引用的：你需要负责保持对原始对象/回调的引用。如果不保持引用，ClockBase将永远不会执行你的回调。例如:

class Foo(object):
    def start(self):
        Clock.schedule_interval(self.callback, 0.5)

    def callback(self, dt):
        print('In callback')

# 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 should do the following and keep a reference to the instance
# of foo until you don't need it anymore!
foo = Foo()
foo.start()

在帧之前调度

在 1.0.5 版本加入.

有时您需要在下一帧之前安排一个回调。从1.0.5版本开始，您可以使用超时时间-1：：

Clock.schedule_once(my_callback, 0) # call after the next frame
Clock.schedule_once(my_callback, -1) # call before the next frame

Clock会在下一帧之前执行所有超时为-1的回调，即使你在运行中的回调里添加了新的-1超时回调也是如此。然而，Clock 对这些回调有一个迭代限制：默认值为10。

如果你安排了一个回调，该回调又安排了另一个回调，如此循环超过10次，它将退出循环并向控制台发送警告，然后在下一帧后继续执行。此实现旨在防止因挂起或崩溃应用程序而导致的错误。

如果需要提高限制，请设置 max_iteration 属性:

from kivy.clock import Clock
Clock.max_iteration = 20

触发事件

在 1.0.5 版本加入.

CyClockBase.create_trigger() 是一种延迟回调的高级方法。它的功能与 CyClockBase.schedule_once() 和 CyClockBase.schedule_interval() 完全相同，区别在于它不会立即调度回调。相反，您可以使用它返回的 ClockEvent 来调度回调。这确保了您可以多次调用该事件，但不会多次调度它。而 CyClockBase.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
event = Clock.create_trigger(my_callback)
event()
event()

# will also run the callback only once before the next frame
event = Clock.schedule_once(my_callback)  # now it's already scheduled
event()  # won't be scheduled again
event()

此外，与在函数中使用 CyClockBase.schedule_once() 相比，创建并绑定到触发事件更为便捷。

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

即使x和y在同一帧内发生变化，回调也只会执行一次。

取消调度

使用 CyClockBase.schedule_once()、CyClockBase.schedule_interval() 或 CyClockBase.create_trigger() 调度的事件，在触发后可以通过多种方式取消调度。例如:

def my_callback(dt):
    pass

# call my_callback every 0.5 seconds
event = Clock.schedule_interval(my_callback, 0.5)

# call my_callback in 5 seconds
event2 = Clock.schedule_once(my_callback, 5)

event_trig = Clock.create_trigger(my_callback, 5)
event_trig()

# unschedule using cancel
event.cancel()

# unschedule using Clock.unschedule
Clock.unschedule(event2)

# unschedule using Clock.unschedule with the callback
# NOT RECOMMENDED
Clock.unschedule(my_callback)

取消回调的最佳方式是使用 ClockEvent.cancel()。CyClockBase.unschedule() 主要是该函数的一个别名。然而，如果原始回调本身被传递给 CyClockBase.unschedule()，它将取消该回调的所有实例（前提是 all 为 True，即默认值；否则仅移除第一个匹配项）。

强烈不建议对原始回调调用 CyClockBase.unschedule()，因为与使用事件相比，其速度明显较慢。

时钟生命周期

Kivy 的时钟具有生命周期。默认情况下，在时钟结束后安排回调不会引发错误，即使该回调可能永远不会被调用。这是因为大多数回调类似于服务，例如响应用户按钮按下——如果应用正在运行，回调需要服务于应用并响应输入，但一旦应用已停止或正在停止，我们可以安全地不处理这些事件。

其他事件始终需要被处理。例如，另一个线程可能在Kivy的线程中请求一个回调，然后处理某些结果。如果由于应用停止而未在Kivy的线程中处理该事件，第二个线程可能会永久阻塞，导致应用在退出时挂起。

因此，我们提供了一个API（CyClockBase.create_lifecycle_aware_trigger()），用于调度那些在时钟停止时会引发:class:ClockNotRunningError`异常的回调。如果调度成功，则保证其回调之一会被调用。即，新的:meth:`CyClockBase.create_lifecycle_aware_trigger`接受一个额外的``clock_ended_callback``参数。通常情况下，当事件被处理时会调用``callback`。但是，如果在事件被处理之前时钟已停止，且应用程序正常退出（并且应用已启动）、事件未被取消，并且回调未被垃圾回收，那么当时钟停止时，将改为调用``clock_ended_callback``。

也就是说，在满足这些条件的情况下，如果事件被调度时未引发 ClockNotRunningError，那么这些回调之一将被调用——如果事件正常执行，则调用 callback；如果在事件被调度期间时钟停止，则调用 clock_ended_callback。

默认情况下，事件可以在时钟启动之前被调度，因为假定时钟最终会在应用启动时启动。也就是说，在时钟和应用启动之前调用 CyClockBase.create_lifecycle_aware_trigger() 将会成功。但如果应用实际上从未启动，那么这两个回调可能都不会被执行。

在 2.0.0 版本加入: 生命周期功能自2.0.0版本起加入。

异常处理

Kivy 提供了一个异常处理管理器，ExceptionManager，用于处理其内部异常，包括由时钟回调引发的异常，而不会导致应用程序崩溃。默认情况下，当异常被引发时，应用程序会崩溃。但是，如果向异常管理器注册了一个处理器，并且该处理器处理了该异常，应用程序将不会崩溃，并会像平常一样继续运行。:

from kivy.base import ExceptionHandler, ExceptionManager
class MyHandler(ExceptionHandler):
    def handle_exception(self, inst):
        if isinstance(inst, ValueError):
            Logger.exception('ValueError caught by MyHandler')
            return ExceptionManager.PASS
        return ExceptionManager.RAISE

ExceptionManager.add_handler(MyHandler())

然后，所有 ValueError 异常将被记录到控制台并忽略。同样，如果计划中的时钟回调引发 ValueError，其他时钟事件仍将正常处理。

如果事件的回调函数抛出异常，在执行异常处理器之前，该回调会立即被取消。

即使Kivy本身是异常的来源，应用程序仍有可能被损坏。也就是说，即使有一个忽略异常且不会崩溃的处理程序，如果错误源自Kivy内部，应用程序也可能处于损坏状态。然而，异常处理程序可以帮助保护应用程序免于崩溃，并有助于防止用户回调导致应用程序崩溃。

在 2.0.0 版本发生变更: 在Kivy 2.0.0之前，事件回调中引发的异常会导致时钟崩溃，后续事件可能执行也可能不执行。即使异常由:class:`~kivy.base.ExceptionHandler`处理，也无法保证某些预定事件不会被跳过。

从2.0.0版本开始，如果某个事件的异常由:class:`~kivy.base.ExceptionHandler`处理，其他事件将免受该异常影响，并正常执行。

从 __del__ 中调度

从对象的``__del__``或``__dealloc__``方法中调度Clock事件是不安全的。如果必须在此方法中调度Clock调用，请改用:meth:CyClockBase.schedule_del_safe`或:meth:`CyClockBase.schedule_lifecycle_aware_del_safe。

线程与回调顺序

从1.10.0版本开始，所有在同一帧内安排的事件，例如在同一帧内以``timeout``为``0``安排的所有事件，将按照它们被安排的顺序执行。

此外，所有调度和取消方法都是完全线程安全的，可以安全地从外部线程使用。

因此，使用原始回调调用 CyClockBase.unschedule() 现在会显著变慢，且强烈不建议这样做。相反，应使用返回的事件对象来进行取消操作。作为权衡，所有其他方法现在都比以前快得多。

高级时钟详细信息

以下部分深入探讨了Kivy内部时钟的细节以及各种时钟选项。此内容仅面向高级用户。

从根本上说，Kivy 时钟尝试按照指定的帧率（每秒帧数，参见 config 中的 maxfps）有节奏地执行任何已调度的回调。也就是说，理想情况下，例如期望的帧率为 30，时钟将以 1/30 秒或每 33.33 毫秒的间隔执行回调。一帧中的所有回调都被赋予相同的时间戳，即传递给回调的 dt 都是相同的，并且它是这一帧开始与上一帧开始之间的时间差。

由于固有的不确定性，帧实际上并不会严格按fps间隔发生，dt 可能低于或高于期望的fps。此外，一旦超时在内部判定为“足够接近”目标超时时间，Kivy 将在当前帧执行回调，即使“实际时间”尚未达到 timeout 的时长。

自 1.10.0 版本起，Kivy 提供了多种具有不同行为的时钟。

默认时钟

默认时钟（default）的行为如上所述。当调度一个超时时间为零或非零的回调时，它们会在接近超时时间的帧上执行，这取决于帧率（fps）。因此，超时时间为零仍会导致一帧或大约1/fps的延迟，通常略少，但有时更多，这取决于该帧上其他已调度事件的CPU使用情况。

在帧率为30的测试中，超时时间为0、0.001和0.05的回调，其平均回调延迟分别为0.02487、0.02488和0.05011秒。当以帧率600进行测试时，0.05秒超时的延迟相似，但标准差减小，从而整体精度更高。

可中断时钟

默认时钟存在量化问题，因为帧仅按间隔发生，任何计划中的超时都无法在间隔期间触发。例如，当超时设置为0.05时，虽然平均值为0.05011，但其值范围在0.02548至0.07348之间，标准差为0.002。此外，还存在约0.02487的最小超时限制。

可中断时钟（interrupt）即使在帧期间也会执行超时。因此，超时为零将尽可能快地执行，同样，非零超时也会在间隔期间执行。

此时钟以及之后描述的所有时钟都有一个选项，ClockBaseInterruptBehavior.interupt_next_only。当为True时，任何新的行为仅适用于超时为零的回调。非零超时的回调将像默认时钟一样运行。例如，对于此时钟，当为True时，只有零超时的回调会在间隔期间执行。

在帧率为30的测试中，当 ClockBaseInterruptBehavior.interupt_next_only 为 False 时，超时分别为0、0.001和0.05秒的回调，其平均回调延迟分别为0.00013、0.00013和0.04120秒。此外，与默认时钟相比，标准差有所降低。当 ClockBaseInterruptBehavior.interupt_next_only 为 True 时，这些值分别为0.00010、0.02414和0.05034秒。

自由时钟

可中断时钟可能并非适用于所有情况，因为在间隔期间所有事件都会被执行，而事件不再按照fps的倍数节奏性地执行。例如，在子间隔内更新图形可能没有任何益处，因此额外的精确度会浪费CPU资源。

自由时钟（free_all）通过提供所有时钟调度方法的``Clock.xxx_free``版本来解决这个问题。这里的“自由”指的是事件不受帧率限制，因为它不基于fps。例如，CyClockBaseFree.create_trigger_free`对应于:meth:`CyClockBase.create_trigger()。只有当使用``Clock.xxx_free``方法调度的事件存在时，时钟才会在间隔期间中断并执行这些事件。因此，如果没有``free``事件存在，时钟行为与``default``时钟相同；否则，其行为类似于``interrupt``时钟。

在帧率为30的测试中，当回调超时时间分别为0秒、0.001秒和0.05秒时，若为自由事件，平均回调延迟分别为0.00012秒、0.00017秒和0.04121秒；若非自由事件，则分别为0.02403秒、0.02405秒和0.04829秒。

仅限时钟。

自由时钟在调度自由事件时会执行所有事件。这导致当调度自由事件时，普通事件也会在间隔中间被执行。例如，上述情况中，在没有自由事件时，一个超时时间为0.001秒的普通事件被延迟了0.02405秒。然而，如果恰好也调度了一个自由事件，该普通事件仅被延迟了0.00014秒，这可能是不希望的。

仅自由时钟（free_only）通过仅在间隔期间执行自由事件来解决此问题，而普通事件则始终像使用默认时钟一样执行。例如，在存在自由事件的情况下，一个超时时间为0.001秒的普通事件仍然有0.02406秒的延迟。因此，该时钟独立处理自由事件和普通事件，普通事件始终受帧率限制，但自由事件则不受此限制。

总结

可通过 config 中的 kivy_clock 选项来设置使用的 Kivy 时钟类型。如果环境中存在 KIVY_CLOCK，它将覆盖配置选择。其可能的值如下：

  • 当 kivy_clock 设置为 default 时，使用普通时钟 ClockBase，该时钟将回调限制在 maxfps 量化范围内。

  • 当 kivy_clock 设置为 interrupt 时，会使用一个可中断的时钟，即 ClockBaseInterrupt，它不会将任何回调限制在最大帧率（maxfps）内。回调将在任意时间被执行。

  • 当 kivy_clock 设置为 free_all 时，会使用一个可中断的时钟，即 ClockBaseFreeInterruptAll。该时钟在存在自由事件时不限制任何回调到最大帧率，但在没有自由事件时，会将事件限制在帧率量化间隔内。

  • 当 kivy_clock 设置为 free_only 时，会使用一个可中断的时钟，即 ClockBaseFreeInterruptAll，它独立处理自由事件和普通事件；普通事件受帧率限制，而自由事件则不受限制。

异步时钟支持

在 2.0.0 版本加入.

2.0.0 版本中已添加实验性异步支持。现在，Clock 拥有 ClockBaseBehavior.async_tick() 和 ClockBaseBehavior.async_idle() 协程方法，当 kivy EventLoop 以异步方式执行时，这些方法会被 kivy EventLoop 使用。使用时，kivy 时钟在空闲时不会阻塞。

使用的异步库通过`KIVY_EVENTLOOP`环境变量选择，或直接调用:meth:~kivy.clock.ClockBaseBehavior.init_async_lib。该库可以是标准库`asyncio`（当应使用`asyncio`时），或`trio`（如果应使用trio库）。若未设置，则默认为`"asyncio"`。

参见 app 获取使用示例。

kivy.clock.Clock: ClockBase = None

kivy Clock 实例。详见模块文档。

class kivy.clock.ClockBase(**kwargs)[源代码]

基类：ClockBaseBehavior, CyClockBase

default Kivy 时钟。详见模块。

usleep(microseconds)[源代码]

休眠指定的微秒数。

class kivy.clock.ClockBaseBehavior(async_lib='asyncio', **kwargs)[源代码]

基类：object

kivy时钟的基础。

参数:
async_lib：字符串

当时钟以异步方式运行时使用的异步库。可以是 `"asyncio"`（使用标准库 asyncio）或 `"trio"`（使用 trio 库）。

默认值为 'asyncio'，或者如果设置了环境变量 KIVY_EVENTLOOP，则使用该值。也可以直接调用 init_async_lib() 来设置库。

MIN_SLEEP = 0.005

最小睡眠时间。如果剩余时间小于此值，事件循环将继续运行。

async async_idle()[源代码]

（内部）:meth:idle 的异步版本。

async async_tick()[源代码]

tick() 的异步版本。

property frames

自时钟启动以来的内部帧数（不一定绘制）。

在 1.8.0 版本加入.

property frames_displayed

从时钟启动以来显示的帧数。

property frametime

上一帧与当前帧之间所花费的时间（以秒为单位）。

在 1.8.0 版本加入.

get_boottime()[源代码]

获取自应用程序启动以来的时间（以秒为单位）。

get_fps()[源代码]

获取时钟计算出的当前平均FPS。

get_rfps()[源代码]

获取时钟计算出的当前“实际”FPS。此计数器反映屏幕上显示的真实帧率。

与get_fps()不同，此函数返回帧数的计数器，而非每秒帧数的平均值。

get_time()[源代码]

获取时钟最后一次滴答的时间。

idle()[源代码]

（内部）在此处等待，直到下一帧。

init_async_lib(lib)[源代码]

手动设置内部使用的异步库，当以异步方式运行时。

这可以在kivy事件循环启动前的任何时间调用，但一旦kivy应用正在运行，则不能调用。

参数:
lib：字符串

当时钟以异步方式运行时使用的异步库。可以是 `"asyncio"`（使用标准库 asyncio）或 `"trio"`（使用 trio 库）。

post_idle(ts, current)[源代码]

在 tick() 调用 idle() 之后调用。

pre_idle()[源代码]

在 tick() 调用 idle() 之前调用。

tick()[源代码]

将时钟推进到下一步。必须在每一帧调用。默认时钟有一个由 Kivy 核心框架调用的 tick() 函数。

tick_draw()[源代码]

勾选绘图计数器。

static time()

: clock() 的代理方法。

usleep(microseconds)[源代码]

休眠指定的微秒数。

class kivy.clock.ClockBaseFreeInterruptAll(**kwargs)[源代码]

基类：ClockBaseInterruptFreeBehavior, CyClockBaseFree

free_all kivy 时钟。详见模块。

class kivy.clock.ClockBaseFreeInterruptOnly(**kwargs)[源代码]

基类：ClockBaseInterruptFreeBehavior, CyClockBaseFree

free_only Kivy 时钟。详见模块说明。

async async_idle()[源代码]

（内部）:meth:idle 的异步版本。

idle()[源代码]

（内部）在此处等待，直到下一帧。

class kivy.clock.ClockBaseInterrupt(interupt_next_only=False, **kwargs)[源代码]

基类：ClockBaseInterruptBehavior, CyClockBase

中断kivy时钟。详见模块说明。

class kivy.clock.ClockBaseInterruptBehavior(interupt_next_only=False, **kwargs)[源代码]

基类：ClockBaseBehavior

一个Kivy时钟，可在帧期间被中断以执行事件。

async async_idle()[源代码]

（内部）:meth:idle 的异步版本。

idle()[源代码]

（内部）在此处等待，直到下一帧。

init_async_lib(lib)[源代码]

手动设置内部使用的异步库，当以异步方式运行时。

这可以在kivy事件循环启动前的任何时间调用，但一旦kivy应用正在运行，则不能调用。

参数:
lib：字符串

当时钟以异步方式运行时使用的异步库。可以是 `"asyncio"`（使用标准库 asyncio）或 `"trio"`（使用 trio 库）。

usleep(microseconds)[源代码]

休眠指定的微秒数。

class kivy.clock.ClockBaseInterruptFreeBehavior(**kwargs)[源代码]

基类：ClockBaseInterruptBehavior

用于时钟的基类，该时钟会中断睡眠间隔以处理自由事件。

class kivy.clock.ClockEvent(CyClockBase clock, int loop, callback, double timeout, double starttime, cid=None, int trigger=False, clock_ended_callback=None, release_ref=True, **kwargs)

基类：object

该类从不被用户直接创建；相反，kivy 在调度回调时会创建并返回此类的实例。

可以通过调用事件来触发（调度）它。如果事件已经被调度，则不会发生任何操作；否则，它将被调度。例如：：

event = Clock.schedule_once(my_callback, .5)
event()  # nothing will happen since it's already scheduled.
event.cancel()  # cancel it
event()  # now it's scheduled again.
callback

callback：对象

cancel(self)

如果该回调已被安排调用，则取消它。如果未被安排，则不会发生任何操作。

cid

我注意到您的消息中似乎缺少了需要翻译的英文内容。请发送您需要翻译的 Kivy 技术文档内容，我会为您进行专业、准确的简体中文翻译。

clock

clock: kivy._clock.CyClockBase 与该事件关联的 CyClockBase 实例。

clock_ended_callback

clock_ended_callback: object 该事件的可选回调，若提供，则时钟会调用它。

当时钟停止且事件未被触发时。

get_callback(self)

返回与该事件关联的回调。回调以间接引用的方式存储，以免保持对象存活。如果回调已失效，则返回 None。

get_clock_ended_callback(self)

返回与该事件关联的clock_ended_callback。回调以间接引用的方式存储，以免保持对象存活。如果回调已失效或未提供，则返回None。

is_triggered

返回该事件是否已计划由kivy线程执行其回调。

loop

loop: 'int' 此事件是否以 timeout 的时间间隔重复触发。

next

next: kivy._clock.ClockEvent 按调度顺序排列的下一个 ClockEvent。

prev

prev: kivy._clock.ClockEvent 前一个 ClockEvent，按照它们被调度的顺序排列。

release(self)

（内部方法）将回调转换为间接引用。

release_ref

release_ref: 'int' 如果为True，事件将永远不会释放对回调的引用。

如果为 False，则可能改为创建弱引用。

tick(self, double curtime)

（内部方法）处理kivy线程的事件。

timeout

timeout: 'double' 调度后回调应执行的持续时间。

weak_callback

weak_callback: 对象

weak_clock_ended_callback

weak_clock_ended_callback：对象

exception kivy.clock.ClockNotRunningError

基类：RuntimeError

当Kivy时钟已经完成调度（即调用了:class:~CyClockBase.stop_clock）后，若再尝试调度事件，Kivy时钟会引发此异常。

class kivy.clock.CyClockBase(**kwargs)

基类：object

clock_resolution

clock_resolution: 'double' 如果距离事件超时的剩余时间小于 clock_resolution，

即使尚未完全超时，时钟也会执行回调。

如果为-1（默认值），分辨率将根据配置中的``maxfps``计算。否则，将使用提供的值。默认值为-1。

create_lifecycle_aware_trigger(self, callback, clock_ended_callback, timeout=0, interval=False, release_ref=True) → ClockEvent

创建触发器事件的方式与 create_trigger() 类似，但该事件对时钟的状态敏感。

如果此事件在时钟停止（stop_clock()）后被触发，则会引发一个 ClockNotRunningError。若未引发错误，则要么调用 callback，要么调用 clock_ended_callback。当事件正常执行时，将调用 callback。如果在事件执行前时钟被停止，且应用正常退出未崩溃、事件未被手动取消，并且回调未被垃圾回收，则在时钟停止时将改为调用 clock_ended_callback。

参数:
callback：可调用对象

从kivy执行的回调函数。它接受一个参数——当前经过的kivy时间。

clock_ended_callback：可调用对象

如果时钟在事件仍计划调用时被停止，将调用此回调。该回调接受一个参数——事件对象。当事件成功调度后，如果应用正常退出且事件未被取消，并且回调未被垃圾回收，则保证会调用 callback 或 clock_ended_callback 其中之一。

timeout：浮点数

调用回调前需要等待的时间。

interval：布尔值

回调是否应仅调用一次（False），还是像 schedule_interval() 那样以 timeout 为周期重复调用（True）。

release_ref: 布尔值

如果为True（默认值），那么当``callback``或``clock_ended_callback``是类方法且对象没有其他引用时，该对象可能会被垃圾回收，导致回调不会被调用。如果为False，时钟会保留对对象的引用，防止其被垃圾回收，从而确保回调会被调用。

返回:

一个 ClockEvent 实例。要调度此实例的回调，您可以调用它。

在 2.0.0 版本加入.

create_trigger(self, callback, timeout=0, interval=False, release_ref=True) → ClockEvent

创建一个触发事件。它是线程安全的，但不适用于 __del__ 或 __dealloc__ 安全场景（参见 schedule_del_safe()）。更多信息请查阅模块文档。

要在事件执行前取消它，请对返回的事件调用 ClockEvent.cancel()。若要重新安排它，只需调用该事件（event()），如果它尚未被安排，它将被安全地重新安排。

参数:
callback：可调用对象

从kivy执行的回调函数。它接受一个参数——当前经过的kivy时间。

timeout：浮点数

调用回调前需要等待的时间。

interval：布尔值

回调是否应仅调用一次（False），还是像 schedule_interval() 那样以 timeout 为周期重复调用（True）。

release_ref: 布尔值

如果为 True（默认值），那么当 callback 是一个类方法且该对象没有其他引用时，该对象可能会被垃圾回收，回调将不会被调用。如果为 False，时钟会持有对该对象的引用，防止其被垃圾回收，因此回调将会被调用。

返回:

一个 ClockEvent 实例。要调度此实例的回调，您可以调用它。

在 1.0.5 版本加入.

在 1.10.0 版本发生变更: 已添加``interval``。

在 2.0.0 版本发生变更: release_ref 已添加。

get_before_frame_events(self)

返回计划在下一帧（``-1``超时）之前调用的 ClockEvent 实例列表。

在 2.1.0 版本加入.

get_events(self)

返回当前已调度的 ClockEvent 实例列表。

get_min_timeout(self)

返回自当前帧开始以来，具有最小超时事件所剩余的时间。

get_resolution(self)

返回时钟所拥有的最小分辨率。它是配置中提供的 clock_resolution 和 maxfps 的函数。

handle_exception(self, e)

提供处理事件异常的机会。

如果需要，可以处理该异常，否则应再次抛出。默认情况下，它会再次抛出。

参数:

e -- 要处理的异常。

在 2.0.0 版本加入.

has_ended

has_ended: 'int'

has_started

has_started: 'int'

max_iteration

max_iteration: 'int' 在帧结束前，回调迭代的最大次数。

如果发生更多迭代，则会发出警告。

on_schedule(self, event)

每次该时钟触发事件时，内部调用的函数。它以事件作为参数。

on_schedule 调用的顺序不保证与事件被调度的顺序一致。同样地，被调度的事件有可能在调用此方法之前已被取消。这是因为 on_schedule() 可能从不同的线程中被调用。

schedule_del_safe(self, callback)

安排一个线程安全且对``__del__``或``__dealloc__``安全的回调。

在``__del__``或``__dealloc__``方法中调用各种代码是不安全的，因为这些方法可能在任何时候被执行。Kivy的大多数Clock方法在这些方法中调用是不安全的。相反，应使用此方法，它是线程安全的，并且对``__del__``或``__dealloc__``安全，用于在Kivy线程中调度回调。它将在正常事件处理之后按顺序执行。

参数:
callback：可调用对象

该回调由Kivy执行，不接受任何参数，且无法被取消。

在 1.11.0 版本加入.

schedule_interval(self, callback, timeout) → ClockEvent

安排一个事件，每隔<timeout>秒调用一次。关于高级调度及更多细节，请参阅:meth:create_trigger。

要取消尚未执行的事件，请对返回的事件调用 ClockEvent.cancel()。如果回调是类方法，则会创建对象的弱引用，若没有其他对该对象的引用，该对象可能会被垃圾回收。

返回:

一个 ClockEvent 实例。与 create_trigger() 仅创建触发事件不同，此方法还会安排其执行。

schedule_lifecycle_aware_del_safe(self, callback, clock_ended_callback)

调度一个线程安全且与 __del__ 或 __dealloc__ 安全的回调，类似于 schedule_del_safe()，但该回调对时钟的状态敏感。

如果此事件在时钟停止（stop_clock()）后被触发，则会引发一个 ClockNotRunningError 异常。若未引发该异常，则 callback 或 clock_ended_callback 其中之一将被调用。当回调正常执行时，会调用 callback。如果在回调执行前时钟被停止，且应用正常退出未崩溃，则在时钟停止时将转而调用 clock_ended_callback。

参数:
callback：可调用对象

该回调由Kivy执行，不接受任何参数，且无法被取消。

clock_ended_callback：可调用对象

如果时钟在回调仍被安排调用时停止，将调用此回调。该回调接受一个参数——即回调本身。如果应用正常退出，则保证要么调用 callback，要么调用 clock_ended_callback。

在 2.0.0 版本加入.

schedule_once(self, callback, timeout=0) → ClockEvent

在<timeout>秒后调度一个事件。如果<timeout>未指定或为0，回调将在下一帧渲染后被调用。有关高级调度和更多详细信息，请参阅:meth:create_trigger。

要取消尚未执行的事件，请对返回的事件调用 ClockEvent.cancel()。如果回调是类方法，则会创建对象的弱引用，若没有其他对该对象的引用，该对象可能会被垃圾回收。

返回:

一个 ClockEvent 实例。与 create_trigger() 仅创建触发事件不同，此方法还会安排其执行。

在 1.0.5 版本发生变更: 如果超时时间为-1，回调将在下一帧之前（在 tick_draw() 时）被调用。

start_clock(self)

必须调用以启动时钟。

一旦调用 stop_clock()，时钟便无法再次启动。

stop_clock(self)

停止时钟并进行清理。

必须调用此方法以处理生命周期感知回调等。

unschedule(self, callback, all=True)

移除之前已计划的事件。

一个 ClockEvent 也可以通过调用 ClockEvent.cancel() 直接取消。

参数:
callback: ClockEvent 或可调用对象。

如果它是一个 ClockEvent 实例，那么与该事件关联的回调如果已安排，将被取消。

如果是可调用的，那么如果它已被调度，该可调用将被取消调度。

警告

传递回调函数而非返回的 ClockEvent 将导致取消调度速度显著变慢。

all：布尔值

如果为 True 且 callback 是可调用的，则该可调用对象的所有实例都将被取消调度（即，如果该可调用对象被多次调度）。默认为 True。

在 1.9.0 版本发生变更: all 参数已添加。此前，其行为等同于 all 为 True。

class kivy.clock.CyClockBaseFree

基类：CyClockBase

一个时钟类，除了支持常规事件外，还支持调度自由事件。

每个创建普通事件的 create_trigger()、schedule_once() 和 schedule_interval() 方法，都有对应的用于创建自由事件的方法。

create_lifecycle_aware_trigger(self, callback, clock_ended_callback, timeout=0, interval=False, release_ref=True) → FreeClockEvent
create_lifecycle_aware_trigger_free(self, callback, clock_ended_callback, timeout=0, interval=False, release_ref=True) → FreeClockEvent

类似于 create_lifecycle_aware_trigger()，但创建的是一个自由事件。

create_trigger(self, callback, timeout=0, interval=False, release_ref=True) → FreeClockEvent
create_trigger_free(self, callback, timeout=0, interval=False, release_ref=True) → FreeClockEvent

类似于 create_trigger()，但不同的是，它创建的是一个自由事件。

get_min_free_timeout(self)

返回自当前帧开始以来，对于具有最小超时时间的*空闲*事件所剩余的时间。

schedule_interval(self, callback, timeout) → FreeClockEvent
schedule_interval_free(self, callback, timeout) → FreeClockEvent

类似于 schedule_interval()，但创建的是一个自由事件。

schedule_once(self, callback, timeout=0) → FreeClockEvent
schedule_once_free(self, callback, timeout=0) → FreeClockEvent

类似于 schedule_once()，但不同的是，它创建的是一个自由事件。

class kivy.clock.FreeClockEvent(free, *largs, **kwargs)

基类：ClockEvent

CyClockBaseFree。它存储了该事件是否被安排为自由事件。

free

free: 'int' 该事件是否被安排为自由事件。

kivy.clock.mainthread(func)[源代码]

装饰器，用于将函数的调用安排在主线程的下一个可用帧中。当您使用 UrlRequest 或进行线程编程时，这会非常有用：您无法在线程中执行任何与 OpenGL 相关的工作。

请注意，此方法将直接返回，无法返回任何结果。

@mainthread
def callback(self, *args):
    print('The request succeeded!',
          'This callback is called in the main thread.')


self.req = UrlRequest(url='http://...', on_success=callback)

在 1.8.0 版本加入.

kivy.clock.triggered(timeout=0, interval=False)[源代码]

装饰器，用于在指定超时后通过 CyClockBase.create_trigger() 方法触发函数的调用。在超时激活期间，对装饰函数的后续调用将被忽略。

当某个昂贵的函数（例如调用服务器）可能由不同方法触发时，设置适当的超时时间将延迟调用，并且只会触发其中一个。

@triggered(timeout, interval=False) def callback(id):

print('回调已被调用，id=%d' % id)

>> callback(id=1) >> callback(id=2) 回调已使用id=2被调用

被装饰的回调也可以使用以下方式取消调度：

>> callback.cancel()

在 1.10.1 版本加入.

« 缓存管理器 Python 2.7 和 >= 3.4 的兼容性模块。 »