Version

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
3.1619100231163046

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:

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

Bases: kivy.event.EventDispatcher

Kinetic effect class. See module documentation for more information.

cancel()[source]

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

Friction to apply on the velocity

friction is a NumericProperty and defaults to 0.05.

is_manual

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

is_manual is a BooleanProperty and defaults to False.

max_history

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.

min_distance

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.

min_velocity

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.

Parameters:
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()

std_dt
std_dt

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.

update_velocity(dt)[source]

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

value

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

value is a NumericProperty and defaults to 0.

velocity

Velocity of the movement.

velocity is a NumericProperty and defaults to 0.