SpringAnimation

class SpringAnimation(**properties: Any)

Superclasses: Animation, Object

A spring-based Animation.

AdwSpringAnimation implements an animation driven by a physical model of a spring described by SpringParams, with a resting position in value_to, stretched to value_from.

Since the animation is physically simulated, spring animations don’t have a fixed duration. The animation will stop when the simulated spring comes to a rest - when the amplitude of the oscillations becomes smaller than epsilon, or immediately when it reaches value_to if clamp is set to TRUE. The estimated duration can be obtained with estimated_duration.

Due to the nature of spring-driven motion the animation can overshoot value_to before coming to a rest. Whether the animation will overshoot or not depends on the damping ratio of the spring. See SpringParams for more information about specific damping ratio values.

If clamp is TRUE, the animation will abruptly end as soon as it reaches the final value, preventing overshooting.

Animations can have an initial velocity value, set via initial_velocity, which adjusts the curve without changing the duration. This makes spring animations useful for deceleration at the end of gestures.

If the initial and final values are equal, and the initial velocity is not 0, the animation value will bounce and return to its resting position.

Constructors

class SpringAnimation

classmethod new(widget: Widget, from_: float, to: float, spring_params: SpringParams, target: AnimationTarget) → Animation

Creates a new AdwSpringAnimation on widget.

The animation will animate target from from to to with the dynamics of a spring described by spring_params.

Parameters:

• widget – a widget to create animation on

• from

• to – a value to animate to

• spring_params – physical parameters of the spring

• target – a target value to animate

Methods

class SpringAnimation

calculate_value(time: int) → float

Calculates the value self will have at time.

The time starts at 0 and ends at estimated_duration.

See also calculate_velocity.

Added in version 1.3.

Parameters:

time – elapsed time, in milliseconds

calculate_velocity(time: int) → float

Calculates the velocity self will have at time.

The time starts at 0 and ends at estimated_duration.

See also calculate_value.

Added in version 1.3.

Parameters:

time – elapsed time, in milliseconds

get_clamp() → bool

Gets whether self should be clamped.

get_epsilon() → float

Gets the precision of the spring.

get_estimated_duration() → int

Gets the estimated duration of self, in milliseconds.

Can be DURATION_INFINITE if the spring damping is set to 0.

get_initial_velocity() → float

Gets the initial velocity of self.

get_spring_params() → SpringParams

Gets the physical parameters of the spring of self.

get_value_from() → float

Gets the value self will animate from.

get_value_to() → float

Gets the value self will animate to.

get_velocity() → float

Gets the current velocity of self.

set_clamp(clamp: bool) → None

Sets whether self should be clamped.

If set to TRUE, the animation will abruptly end as soon as it reaches the final value, preventing overshooting.

It won’t prevent overshooting value_from if a relative negative initial_velocity is set.

Parameters:

clamp – the new value

set_epsilon(epsilon: float) → None

Sets the precision of the spring.

The level of precision used to determine when the animation has come to a rest, that is, when the amplitude of the oscillations becomes smaller than this value.

If the epsilon value is too small, the animation will take a long time to stop after the animated value has stopped visibly changing.

If the epsilon value is too large, the animation will end prematurely.

The default value is 0.001.

Parameters:

epsilon – the new value

set_initial_velocity(velocity: float) → None

Sets the initial velocity of self.

Initial velocity affects only the animation curve, but not its duration.

Parameters:

velocity – the initial velocity

set_spring_params(spring_params: SpringParams) → None

Sets the physical parameters of the spring of self.

Parameters:

spring_params – the new spring parameters

set_value_from(value: float) → None

Sets the value self will animate from.

The animation will start at this value and end at value_to.

Parameters:

value – the value to animate from

set_value_to(value: float) → None

Sets the value self will animate to.

The animation will start at value_from and end at this value.

Parameters:

value – the value to animate to

Properties

class SpringAnimation

props.clamp: bool

Whether the animation should be clamped.

If set to TRUE, the animation will abruptly end as soon as it reaches the final value, preventing overshooting.

It won’t prevent overshooting value_from if a relative negative initial_velocity is set.

props.epsilon: float

Precision of the spring.

The level of precision used to determine when the animation has come to a rest, that is, when the amplitude of the oscillations becomes smaller than this value.

If the epsilon value is too small, the animation will take a long time to stop after the animated value has stopped visibly changing.

If the epsilon value is too large, the animation will end prematurely.

The default value is 0.001.

props.estimated_duration: int

Estimated duration of the animation, in milliseconds.

Can be DURATION_INFINITE if the spring damping is set to 0.

props.initial_velocity: float

The initial velocity to start the animation with.

Initial velocity affects only the animation curve, but not its duration.

props.spring_params: SpringParams

Physical parameters describing the spring.

props.value_from: float

The value to animate from.

The animation will start at this value and end at value_to.

props.value_to: float

The value to animate to.

The animation will start at value_from and end at this value.

props.velocity: float

Current velocity of the animation.