Adw.SpringAnimation¶

Subclasses:: None

Methods¶

Inherited:: Adw.Animation (12), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` (widget, from_, to, spring_params, target)
	`calculate_value` (time)
	`calculate_velocity` (time)
	`get_clamp` ()
	`get_epsilon` ()
	`get_estimated_duration` ()
	`get_initial_velocity` ()
	`get_spring_params` ()
	`get_value_from` ()
	`get_value_to` ()
	`get_velocity` ()
	`set_clamp` (clamp)
	`set_epsilon` (epsilon)
	`set_initial_velocity` (velocity)
	`set_spring_params` (spring_params)
	`set_value_from` (value)
	`set_value_to` (value)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

Inherited:: Adw.Animation (5)

Name	Type	Flags
`clamp`	`bool`	r/w/en
`epsilon`	`float`	r/w/en
`estimated-duration`	`int`	r
`initial-velocity`	`float`	r/w/en
`spring-params`	`Adw.SpringParams`	r/w/c/en
`value-from`	`float`	r/w/c/en
`value-to`	`float`	r/w/c/en
`velocity`	`float`	r

Signals¶

Inherited:: Adw.Animation (1), GObject.Object (1)

Fields¶

Inherited:: Adw.Animation (1), GObject.Object (1)

Class Details¶

class Adw.SpringAnimation(**kwargs)¶

Bases:: Adw.Animation
Abstract:: No
Structure:: Adw.SpringAnimationClass

A spring-based [class`Animation`].

AdwSpringAnimation implements an animation driven by a physical model of a spring described by [struct`SpringParams`], with a resting position in [property`SpringAnimation`:py:data::value-to<Adw.SpringAnimation.props.value_to>], stretched to [property`SpringAnimation`:py:data::value-from<Adw.SpringAnimation.props.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 [property`SpringAnimation`:py:data::epsilon<Adw.SpringAnimation.props.epsilon>], or immediately when it reaches [property`SpringAnimation`:py:data::value-to<Adw.SpringAnimation.props.value_to>] if [property`SpringAnimation`:py:data::clamp<Adw.SpringAnimation.props.clamp>] is set to TRUE. The estimated duration can be obtained with [property`SpringAnimation`:py:data::estimated-duration<Adw.SpringAnimation.props.estimated_duration>].

Due to the nature of spring-driven motion the animation can overshoot [property`SpringAnimation`:py:data::value-to<Adw.SpringAnimation.props.value_to>] before coming to a rest. Whether the animation will overshoot or not depends on the damping ratio of the spring. See [struct`SpringParams`] for more information about specific damping ratio values.

If [property`SpringAnimation`:py:data::clamp<Adw.SpringAnimation.props.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 [property`SpringAnimation`:py:data::initial-velocity<Adw.SpringAnimation.props.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.

classmethod new(widget, from_, to, spring_params, target)¶

Parameters:

widget (Gtk.Widget) – a widget to create animation on
from (float) – a value to animate from
to (float) – a value to animate to
spring_params (Adw.SpringParams) – physical parameters of the spring
target (Adw.AnimationTarget) – a target value to animate

Returns:

the newly created animation

Return type:

Adw.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.

calculate_value(time)¶

Parameters:: time (int) – elapsed time, in milliseconds
Returns:: the value at time
Return type:: float

Calculates the value self will have at time.

The time starts at 0 and ends at [property`SpringAnimation`:estimated_duration].

See also [method`SpringAnimation`.calculate_velocity].

New in version 1.3.

calculate_velocity(time)¶

Parameters:: time (int) – elapsed time, in milliseconds
Returns:: the velocity at time
Return type:: float

Calculates the velocity self will have at time.

The time starts at 0 and ends at [property`SpringAnimation`:estimated_duration].

See also [method`SpringAnimation`.calculate_value].

New in version 1.3.

get_clamp()¶

Returns:: whether self is clamped
Return type:: bool

Gets whether self should be clamped.

get_epsilon()¶

Returns:: the epsilon value
Return type:: float

Gets the precision of the spring.

get_estimated_duration()¶

Returns:: the estimated duration
Return type:: int

Gets the estimated duration of self, in milliseconds.

Can be [constDURATION_INFINITE] if the spring damping is set to 0.

get_initial_velocity()¶

Returns:: the initial velocity
Return type:: float

Gets the initial velocity of self.

get_spring_params()¶

Returns:: the spring parameters
Return type:: Adw.SpringParams

Gets the physical parameters of the spring of self.

get_value_from()¶

Returns:: the value to animate from
Return type:: float

Gets the value self will animate from.

get_value_to()¶

Returns:: the value to animate to
Return type:: float

Gets the value self will animate to.

get_velocity()¶

Returns:: the current velocity
Return type:: float

Gets the current velocity of self.

set_clamp(clamp)¶

Parameters:: clamp (bool) – the new value

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 [property`SpringAnimation`:py:data::value-from<Adw.SpringAnimation.props.value_from>] if a relative negative [property`SpringAnimation`:py:data::initial-velocity<Adw.SpringAnimation.props.initial_velocity>] is set.

set_epsilon(epsilon)¶

Parameters:: epsilon (float) – the new value

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.

set_initial_velocity(velocity)¶

Parameters:: velocity (float) – the initial velocity

Sets the initial velocity of self.

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

set_spring_params(spring_params)¶

Parameters:: spring_params (Adw.SpringParams) – the new spring parameters

Sets the physical parameters of the spring of self.

set_value_from(value)¶

Parameters:: value (float) – the value to animate from

Sets the value self will animate from.

The animation will start at this value and end at [property`SpringAnimation`:py:data::value-to<Adw.SpringAnimation.props.value_to>].

set_value_to(value)¶

Parameters:: value (float) – the value to animate to

Sets the value self will animate to.

The animation will start at [property`SpringAnimation`:py:data::value-from<Adw.SpringAnimation.props.value_from>] and end at this value.

Property Details¶

Adw.SpringAnimation.props.clamp¶

Name:: clamp
Type:: bool
Default Value:: False
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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 [property`SpringAnimation`:py:data::value-from<Adw.SpringAnimation.props.value_from>] if a relative negative [property`SpringAnimation`:py:data::initial-velocity<Adw.SpringAnimation.props.initial_velocity>] is set.

Adw.SpringAnimation.props.epsilon¶

Name:: epsilon
Type:: float
Default Value:: 0.001
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

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.

Adw.SpringAnimation.props.estimated_duration¶

Name:: estimated-duration
Type:: int
Default Value:: 0
Flags:: READABLE

Estimated duration of the animation, in milliseconds.

Can be [constDURATION_INFINITE] if the spring damping is set to 0.

Adw.SpringAnimation.props.initial_velocity¶

Name:: initial-velocity
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, EXPLICIT_NOTIFY

The initial velocity to start the animation with.

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

Adw.SpringAnimation.props.spring_params¶

Name:: spring-params
Type:: Adw.SpringParams
Default Value:: None
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

Physical parameters describing the spring.

Adw.SpringAnimation.props.value_from¶

Name:: value-from
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The value to animate from.

The animation will start at this value and end at [property`SpringAnimation`:py:data::value-to<Adw.SpringAnimation.props.value_to>].

Adw.SpringAnimation.props.value_to¶

Name:: value-to
Type:: float
Default Value:: 0.0
Flags:: READABLE, WRITABLE, CONSTRUCT, EXPLICIT_NOTIFY

The value to animate to.

The animation will start at [property`SpringAnimation`:py:data::value-from<Adw.SpringAnimation.props.value_from>] and end at this value.

Adw.SpringAnimation.props.velocity¶

Name:: velocity
Type:: float
Default Value:: 0.0
Flags:: READABLE

Current velocity of the animation.