Table Of Contents

• Clock object(翻訳ずみ)
  • Schedule before frame(フレーム前のスケジュール)
  • Triggered Events(トリガーイベント)
  • Unscheduling(スケジュール解除)
  • Threading and Callback Order(スレッディングとコールバックの順序)
  • Advanced Clock Details(高度なクロックの詳細)
    • Default Clock(デフォルトクロック)
    • Interruptible Clock(割り込み可能なクロック)
    • Free Clock（フリークロック）
    • Free Only Clock(フリークロックのみ)
    • Summary(概要)

Clock object(翻訳ずみ)

Clock オブジェクトを使用すると未来の関数呼び出しをスケジュールできます。 指定された間隔で1回または繰り返しを 引数 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の場合はスケジュールはキャンセルされて繰り返されません。

デフォルトの引数で呼び出す関数をスケジュールする場合は、 functools.partial のpythonモジュールを使用できます。

from functools import partial

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

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

逆にdt引き数を受け入れない関数をスケジュールする場合はラムダ式を使用して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)

注釈

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 an arbitrary number of parameters.

重要

コールバックは弱い参照です。元のオブジェクト/コールバックへの参照を保持する責任があります。 参照を保持しないと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()

Schedule before frame(フレーム前のスケジュール)

バージョン 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

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.

...などをスケジュールするコールバックをスケジュールするコールバックをスケジュールが10より多いと、ループが終了してコンソールに警告が送信されて次のフレームの後に続きます。 これはバグがアプリケーションを停止またはクラッシュするのを防ぐために実装されています。

制限を増やす必要がある場合は、 max_iteration プロパティを設定します。

from kivy.clock import Clock
Clock.max_iteration = 20

Triggered Events(トリガーイベント)

バージョン 1.0.5 で追加.

トリガイベントはコールバックを延期する方法です。これはすぐにコールバックをスケジュールしないことを除いて、schedule_once() およびchedule_interval() とまったく同じように機能します。代わりに返された ClockEvent を使用してコールバックをスケジュールします。これにより、イベントを複数回呼び出すことができますが、複数回スケジュールされることはありません。 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
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()

くわえて関数内で Clock.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

1フレーム内でxとyが変化してもコールバックは1回だけ実行されます。

CyClockBase.create_trigger() は、CyClockBase.schedule_once() とまったく同じように動作するタイムアウトパラメータを持っています。

バージョン 1.10.0 で変更: CyClockBase.create_trigger() にパラメータ「interval」が追加されました。 デフォルトのFalseの場合、 CyClockBase.schedule_once() と同様のイベントが作成されます。 それ以外の場合は、 CyClockBase.schedule_interval() と同様のイベントが作成されます。

Unscheduling(スケジュール解除)

CyClockBase.schedule_once() 、CyClockBase.schedule_interval() 、または:meth: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() に渡された場合はそのコールバックのすべてのインスタンスのスケジューリングが解除されます（すべてTrue、デフォルト、最初の一致のみが削除されている場合）。

元のコールバックで CyClockBase.unschedule() を呼び出すことは、イベントを使用する場合よりも大幅に遅いために避けてください。

Threading and Callback Order(スレッディングとコールバックの順序)

1.10.0から同じフレームに対して予定されているすべてのイベントが実行されます。 例えば「タイムアウト」が「0」の同じフレームでスケジュールされたすべてのイベントは、スケジュールされた順に実行されます。

またスケジューリングとキャンセルのメソッドはすべてスレッドセーフになり外部スレッドから安全に使用できます。

その結果、元のコールバックを使用して CyClockBase.unschedule() を呼び出すとかなり遅くなり非常にがっかりします。 代わりに返されたイベントを使用して取り消す必要があります。 トレードオフとして他のすべての方法は以前よりも大幅に高速になりました。

Advanced Clock Details(高度なクロックの詳細)

次のセクションでは内部のKivy Clockの詳細とさまざまなClock オプションについて説明します。これは上級ユーザーのみを対象としています。

基本的に、Kivyのクロックは、指定されたfps（1秒あたりのフレーム数、 config の maxfps を参照）で決定される予定のコールバックをリズミカルに実行しようとします。すなわち、理想的には例えば以下のように与えられます。希望のfpsが30の場合、クロックは1/30秒間隔で、または33.33 ms間隔でコールバックを実行します。フレーム内のすべてのコールバックには同じタイムスタンプが与えられます。つまりコールバックに渡された「dt」はすべて同じで、dtと前のフレームの開始時刻の差です。

固有の非確定性のために、フレームは実際にはfpsの間隔で正確には発生せず、「dt」は所望のfpsの下または上にいることもあります。また内部的に決定されるようにタイムアウトが希望のタイムアウトに「十分近い」と「実際の時間」がタイムアウト時間を経過していなくても、現在のフレームでコールバックを実行します。

Kivyは、1.10.0から、異なる動作の複数のクロックを提供しています。

Default Clock(デフォルトクロック)

デフォルトのクロック（「default」）は、上記のように動作します。タイムアウトが0または非ゼロのコールバックがスケジュールされるとタイムアウトに近いフレームで実行されます。これはfpsの関数です。そのためタイムアウトが0になると、1フレームまたは約1 / fpsの遅延が発生します。通常はそのフレームに対してスケジュールされた他のイベントのCPU使用率に応じて、通常は少し下がります。

30のfpsを使用するテストでは0、0.001、および0.05のタイムアウトを伴うコールバックにより、それぞれ平均で0.02487秒、0.02488秒および0.05011秒のコールバック遅延が発生しました。 600fpsでテストした場合も標準偏差が減少して全体的により良い精度が得られることを除いては0.05の遅延は同様でした。

Interruptible Clock(割り込み可能なクロック)

デフォルトクロックはフレームがインターバル上でのみ発生しインターバル中にスケジュールされたタイムアウトが発生しないために量子化の問題をもっています。たとえば、タイムアウトが0.05の場合は平均値は0.05011でしたが、その値は0.02548〜0.07348の範囲で、標準偏差は0.002の範囲でした。また最小タイムアウトは約0.02487です。

割り込み可能なClock（「interrupt」）は、フレーム中であってもタイムアウトを実行します。したがってゼロのタイムアウトは可能な限り迅速に実行されて、同様にその間にもゼロ以外のタイムアウトが実行されます。

This clock, and all the clocks described after this have an option, ClockBaseInterruptBehavior.interupt_next_only. When True, any of the behavior new behavior will only apply to the callbacks with a timeout of zero. Non-zero timeouts will behave like in the default clock. E.g. for this clock when True, only zero timeouts will execute during the the interval.

30fpsを使用するテストでは ClockBaseInterruptBehavior.interupt_next_only`がFalseの場合は、0、0.001、および0.05のタイムアウトを持つコールバックにより、それぞれ0.00013秒、0.00013秒および0.04120秒の平均コールバック遅延が発生しました。またデフォルトクロックと比較して、標準偏差が減少しました。 :attr:`ClockBaseInterruptBehavior.interupt_next_only がTrueの場合、値はそれぞれ0.00010,0.02414,0.05034でした。

Free Clock（フリークロック）

割り込み可能なクロックはすべてのイベントがインターバル中に実行され、イベントがフェイズの倍数としてリズミカルに実行されないため理想的でない可能性があります。たとえばサブインターバルでグラフィックスを更新するメリットがない可能性があるため、追加の精度でCPUを浪費します。

フリー・クロック（「free_all」）は、すべてのクロック・スケジューリング方式の「Clock.xxx_free」バージョンを使用することでこれを解決します。フリーだとfpsが制限されていないためイベントにfpsがないことを意味します。例えば、 CyClockBaseFree.create_trigger_free() は CyClockBase.create_trigger() に対応します。 「Clock.xxx_free」メソッドを使用してスケジュールされたイベントが存在する場合のみ、clock interruptが発生してその間にイベントが実行されます。したがって、「free」イベントが存在しない場合、クロックは「default」クロックのように動作し、それ以外の場合は「interrupt」クロックのように動作します。

30fpsを使用するテストでは、0秒、0.001秒、および0.05秒のタイムアウトを持つコールバックにより、フリーイベントであったときにそれぞれ0.00012秒、0.00017秒、0.04121秒の平均コールバック遅延が発生して 0.02403秒、0.02405秒、および0.04829秒でした。

Free Only Clock(フリークロックのみ)

フリー・クロックは、フリー・イベントがスケジュールされたときにすべてのイベントを実行します。 この結果、通常のイベントが、空きイベントがスケジュールされている期間の途中で実行されます。 例えば、上記のフリーイベントがなかった場合、0.001秒のタイムアウトを伴う通常のイベントは0.02405秒遅れました。 しかし、フリーイベントが予定されていた場合、通常のイベントは0.00014秒遅れてしまい望ましくない可能性があります。

Free onlyクロック（「free_only」）はその間にフリーイベントを実行するだけで解決して通常のイベントは常にデフォルトクロックのように実行されます。例えばフリーイベントが存在する場合、0.001秒のタイムアウトを伴う通常のイベントは、0.02406の遅延が存在していましいた。したがって、この時計は、freeイベントと通常イベントを独立して扱います。通常イベントは常にfpsに制限されていますがフリーイベントでは決してありません。

Summary(概要)

使用するkivyのクロックタイプは、「kivy_clock」オプションの config で設定できます。 「KIVY_CLOCK」が環境内に存在する場合は、configの設定を上書きします。可能な値は次のとおりです:

• 「kivy_clock」が「default」の場合はコールバックをmaxfps の量子化に限定する通常のクロック ClockBase が使用されます。

• 「kivy_clock」が「interrupt」の場合はmaxfpsへのコールバックを制限しない割り込み可能なクロック ClockBaseInterrupt が使用されます。コールバックはいつでも実行されます。

• 「kivy_clock」が「free_all」の場合は割り込み可能なクロック ClockBaseFreeInterruptAll は、フリーイベントの存在下ではmaxfpsへのコールバックを制限しませんが、フリーイベントが存在していない場合にはイベントをfpsの量子化間隔に制限します。

• When kivy_clock is free_only, a interruptible clock, ClockBaseFreeInterruptAll, which treats free and normal events independently; normal events are fps limited while free events are not - is used.

kivy.clock.Clock = None

kivy Clockインスタンスです。詳細についてはモジュールのドキュメントを参照してください。

class kivy.clock.ClockEvent

ベースクラス: builtins.object

Kivy’s Clock でスケジュールされたコールバックを記述するクラス。このクラスはユーザーによって決して作成されません。代わりに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.

cancel()

コールバックがスケジュールされている場合は、コールバックをキャンセルします。スケジュールされていない場合は何も起こりません。

clock

イベントに関連付けられた CyClockBase インスタンス。

get_callback()

イベントに関連付けられたコールバックを返します。コールバックはオブジェクトを生き残らないように間接参照と一緒に格納されます。コールバックが停止している場合は、Noneが返却されます。

is_triggered

イベントがkivyスレッドによってコールバックが実行されるようにスケジュールされているかどうかを返却します。

loop

このイベントが timeout の間隔で繰り返されるかどうか。

next

次の ClockEvent がスケジュールされた順番で返されます。

prev

前の ClockEvent がスケジュールされた順番で返されます。

release()

(内部メソッド)コールバックを間接参照に変換します。

tick()

(内部メソッド)Kivyスレッドのイベントを処理します。

timeout

コールバックを実行する予定の時間。

class kivy.clock.FreeClockEvent

ベースクラス: kivy._clock.ClockEvent

CyClockBaseFree の Clock.XXX_free メソッドによって返されたイベント。イベントがフリーイベントとしてスケジュールされたかどうかを格納します。

free

このイベントがフリーイベントとしてスケジュールされたかどうか。

class kivy.clock.CyClockBase

ベースクラス: builtins.object

イベントをサポートするベースクロックオブジェクト。

clock_resolution

イベントタイムアウトまでの残りの時間が clock_resolution より小さい場合、クロックは正確にタイムアウトしていなくてもコールバックを実行します

デフォルトの-1の場合、解像度はconfigのmaxfpsから計算されます。それ以外の場合は、指定された値が使用されます。デフォルトは-1です。

create_trigger()

トリガーイベントを作成します。詳細は、モジュールのマニュアルを参照してください。

戻り値:ClockEvent インスタンス。このインスタンスのコールバックをスケジュールすると呼び出すことができます。

バージョン 1.0.5 で追加.

バージョン 1.10.0 で変更: 「interval」が追加されました。 Trueの場合はschedule_interval()と同様の<timeout>秒ごとに呼び出されるイベントが作成されます。デフォルトはFalseです。

get_events()

現在スケジュールされている ClockEvent インスタンスのリストを返却します。

get_min_timeout()

タイムアウトが最も小さいイベントの現在のフレームの開始からの残りの時間を返却します。

get_resolution()

クロックが持つ最小解像度を返します。これはconfigで提供される clock_resolution と「maxfps」の関数です。

max_iteration

フレームの最後、次のフレームの前のコールバックのイテレーションの最大回数。より多くのイテレーションが発生すると警告が発行されます。

on_schedule()

クロックでイベントがトリガされるたびに内部的に呼び出される関数。このイベントはパラメータとして使用されます。

schedule_interval()

<timeout>秒ごとに呼び出されるようにイベントをスケジュールします。

戻り値:ClockEvent インスタンストリガイベントのみを作成する create_trigger() とは対照的に、このメソッドはそれをスケジュールします。

schedule_once()

<timeout>秒でイベントをスケジュールします。 <timeout>が指定されていないか0の場合は次のフレームがレンダリングされた後にコールバックが呼び出されます。

戻り値:ClockEvent インスタンストリガイベントのみを作成する create_trigger() とは対照的に、このメソッドはそれをスケジュールします。

バージョン 1.0.5 で変更: タイムアウトが-1の場合、コールバックは次のフレームの前に呼び出されます( tick_draw())。

unschedule()

以前スケジュールされたイベントを削除します。

Parameters:

「コールバック」: ClockEvent または呼び出し可能です。

ClockEvent インスタンスの場合はこのイベントに関連付けられたコールバックは、スケジュールされている場合はキャンセルされます。

呼び出し可能な場合で、呼び出し可能なものでスケジュールされていればスケジュールされません。

警告

返却された :class:`ClockEvent`ではなくコールバック関数を渡すと、スケジューリングが大幅に遅くなります

「all」: bool

値がTrueで「コールバック」がコール可能な場合、このコール可能なインスタンスはすべてスケジュールされません（つまり、このコール可能オブジェクトが複数回スケジュールされた場合）。デフォルトは「True」です。

バージョン 1.9.0 で変更: allパラメータが追加されました。以前は「all」が「True」であるかのように振る舞いました。

class kivy.clock.CyClockBaseFree

ベースクラス: kivy._clock.CyClockBase

通常のイベントに加えてフリーイベントのスケジューリングをサポートするクロッククラス。

通常のイベントを作成する create_trigger() 、schedule_once() 、および schedule_interval() メソッドにはそれぞれフリーイベントを作成するための対応するメソッドがあります。

create_trigger_free()

 create_trigger() に似ていますが、代わりにフリーイベントを作成します。

get_min_free_timeout()

タイムアウトが最小の フリー イベントで現在のフレームの開始以降の残り時間を返します。

schedule_interval_free()

 :meth:`~CyClockBase.schedule_interval と似ていますが、代わりにフリーイベントを作成します。

schedule_once_free()

schedule_once() に似ていますが、代わりにフリーイベントを作成します。

class kivy.clock.ClockBaseBehavior(**kwargs)

ベースクラス: builtins.object

kivy clockのベースです。

MIN_SLEEP = 0.005

スリーブ時間の最小値です。残りの時間がこれよりも短い場合はイベントループは継続します。

frames

クロックの開始から内部フレームの数（必ずしも描画されていない）です。

バージョン 1.8.0 で追加.

frames_displayed

クロックの開始から表示されるフレーム数です。

frametime

最後のフレームと現在のフレームとの間の時間（単位は秒）です。

バージョン 1.8.0 で追加.

get_boottime()

アプリケーションの開始からの時間を秒単位で取得します。

get_fps()

クロックで計算された現在の平均FPSを取得します。

get_rfps()

クロックで計算された現在の「実際の」FPSを取得します。このカウンタは画面に表示される実際のフレームレートを反映します。

get_fps()とは対照的にこの関数は1秒あたりのフレームの平均ではなくフレーム数のカウンタを返します。

get_time()

時計によって最後に行われたティックを取得します。

idle()

次のフレームまでここで(内部的に)待機します。

tick()

時計を次のステップに進めます。すべてのフレームと呼ばれる必要があります。デフォルトクロックにはコアKivyフレームワークによって呼び出される tick() 関数があります。

tick_draw()

Tickのカウンターにチェックを入れてください。

time = functools.partial(<built-in function perf_counter>)

usleep(microseconds)

マイクロ秒の間スリープします。

class kivy.clock.ClockBaseInterruptBehavior(interupt_next_only=False, **kwargs)

ベースクラス: kivy.clock.ClockBaseBehavior

イベントを実行するためにフレーム中に中断できるkivyクロックです。

class kivy.clock.ClockBaseInterruptFreeBehavior(**kwargs)

ベースクラス: kivy.clock.ClockBaseInterruptBehavior

フリーイベントのスリープ間隔を中断するクロックのベースクラス。

class kivy.clock.ClockBase(**kwargs)

ベースクラス: kivy.clock.ClockBaseBehavior, kivy._clock.CyClockBase

「default」のkivyクロック。詳細については、モジュールを参照してください。

class kivy.clock.ClockBaseInterrupt(interupt_next_only=False, **kwargs)

ベースクラス: kivy.clock.ClockBaseInterruptBehavior, kivy._clock.CyClockBase

「interrupt」のkivyクロック。詳細についてはモジュールを参照してください。

class kivy.clock.ClockBaseFreeInterruptAll(**kwargs)

ベースクラス: kivy.clock.ClockBaseInterruptFreeBehavior, kivy._clock.CyClockBaseFree

undefined

class kivy.clock.ClockBaseFreeInterruptOnly(**kwargs)

ベースクラス: kivy.clock.ClockBaseInterruptFreeBehavior, kivy._clock.CyClockBaseFree

「free_only」 kivyクロックです。 詳細についてはモジュールを参照してください。

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 で追加.

« Cache manager

Compatibility module for Python 2.7 and > 3.3 »