Quick search

Kinetic effect

New in version 1.7.0.

The KineticEffect is the base class that is used to compute the velocity out of a movement. When the movement is finished, the effect will compute the position of the movement according to the velocity, and reduce the velocity with a friction. The movement stop until the velocity is 0.

Conceptually, the usage could be:

>>> effect = KineticEffect()
>>> effect.start(10)
>>> effect.update(15)
>>> effect.update(30)
>>> effect.stop(48)

Over the time, you will start a movement of a value, update it, and stop the movement. At this time, you’ll get the movement value into KineticEffect.value. On the example i’ve typed manually, the computed velocity will be:

>>> effect.velocity

After multiple clock interaction, the velocity will decrease according to KineticEffect.friction. The computed value will be stored in KineticEffect.value. The output of this value could be:

# ...
class kivy.effects.kinetic.KineticEffect(**kwargs)[source]

Bases: kivy.event.EventDispatcher

Kinetic effect class. See module documentation for more information.


Cancel a movement. This can be used in case stop() cannot be called. It will reset is_manual to False, and compute the movement if the velocity is > 0.


Friction to apply on the velocity

friction is a NumericProperty and defaults to 0.05.


Indicate if a movement is in progress (True) or not (False).

is_manual is a BooleanProperty and defaults to False.


Save up to max_history movement value into the history. This is used for correctly calculating the velocity according to the movement.

max_history is a NumericProperty and defaults to 5.


The minimal distance for a movement to have nonzero velocity.

New in version 1.8.0.

min_distance is NumericProperty and defaults to 0.1.


Velocity below this quantity is normalized to 0. In other words, any motion whose velocity falls below this number is stopped.

New in version 1.8.0.

min_velocity is a NumericProperty and defaults to 0.5.

start(val, t=None)[source]

Start the movement.

val: float or int

Value of the movement

t: float, defaults to None

Time when the movement happen. If no time is set, it will use time.time()


correction update_velocity if dt is not constant

New in version 2.0.0.

std_dt is a NumericProperty and defaults to 0.017.

stop(val, t=None)[source]

Stop the movement.

See start() for the arguments.

update(val, t=None)[source]

Update the movement.

See start() for the arguments.


(internal) Update the velocity according to the frametime and friction.


Value (during the movement and computed) of the effect.

value is a NumericProperty and defaults to 0.


Velocity of the movement.

velocity is a NumericProperty and defaults to 0.