Next: , Previous: ClutterAnimator, Up: Top

8 Implicit Animations

Simple implicit animations

8.1 Overview

<clutter-animation> is an object providing simple, implicit animations for <gobject>s.

<clutter-animation> instances will bind one or more <gobject> properties belonging to a <gobject> to a <clutter-interval>, and will then use a <clutter-alpha> to interpolate the property between the initial and final values of the interval.

The duration of the animation is set using clutter-animation-set-duration. The easing mode of the animation is set using clutter-animation-set-mode.

If you want to control the animation you should retrieve the <clutter-timeline> using clutter-animation-get-timeline and then use <clutter-timeline> functions like clutter-timeline-start, clutter-timeline-pause or clutter-timeline-stop.

A <clutter-animation> will emit the <"completed"> signal when the <clutter-timeline> used by the animation is completed; unlike <clutter-timeline>, though, the <"completed"> will not be emitted if <"loop"> is set to ‘#t’ - that is, a looping animation never completes.

If your animation depends on user control you can force its completion using clutter-animation-completed.

If the <gobject> instance bound to a <clutter-animation> implements the <clutter-animatable> interface it is possible for that instance to control the way the initial and final states are interpolated.

<clutter-animation>s are distinguished from <clutter-behaviour>s because the former can only control <gobject> properties of a single <gobject> instance, while the latter can control multiple properties using accessor functions inside the <clutter-behaviour>alpha-notify virtual function, and can control multiple <clutter-actor>s as well.

For convenience, it is possible to use the clutter-actor-animate function call which will take care of setting up and tearing down a <clutter-animation> instance and animate an actor between its current state and the specified final state.

8.2 Defining ClutterAnimationMode inside ClutterScript

When defining a <clutter-animation> inside a ClutterScript file or string the <"mode"> can be defined either using the <clutter-animation-mode> enumeration values through their "nick" (the short string used inside <g-enum-value>), their numeric id, or using the following strings:

easeInCubic, easeOutCubic, easeInOutCubic

easeInQuart, easeOutQuart, easeInOutQuart

easeInQuint, easeOutQuint, easeInOutQuint

easeInSine, easeOutSine, easeInOutSine

easeInExpo, easeOutExpo, easeInOutExpo

easeInCirc, easeOutCirc, easeInOutCirc

easeInElastic, easeOutElastic, easeInOutElastic

easeInBack, easeOutBack, easeInOutBack

easeInBounce, easeOutBounce, easeInOutBounce

Corresponding to the quadratic easing modes

Corresponding to the cubic easing modes

Corresponding to the quartic easing modes

Corresponding to the quintic easing modes

Corresponding to the sine easing modes

Corresponding to the exponential easing modes

Corresponding to the circular easing modes

Corresponding to the overshooting elastic easing modes

Corresponding to the overshooting cubic easing modes

Corresponding to the bouncing easing modes

<clutter-animation> is available since Clutter 1.0

8.3 Usage

— Function: clutter-animation-new ⇒  (ret <clutter-animation>)

Creates a new <clutter-animation> instance. You should set the <gobject> to be animated using clutter-animation-set-object, set the duration with clutter-animation-set-duration and the easing mode using clutter-animation-set-mode.

Use clutter-animation-bind or clutter-animation-bind-interval to define the properties to be animated. The interval and the animated properties can be updated at runtime.

The clutter-actor-animate and relative family of functions provide an easy way to animate a <clutter-actor> and automatically manage the lifetime of a <clutter-animation> instance, so you should consider using those functions instead of manually creating an animation.

ret
the newly created <clutter-animation>. Use g-object-unref to release the associated resources

Since 1.0

— Function: clutter-animation-set-object (self <clutter-animation>) (object <gobject>)
— Method: set-object

Attaches animation to object. The <clutter-animation> will take a reference on object.

animation
a <clutter-animation>
object
a <gobject>

Since 1.0

— Function: clutter-animation-get-object (self <clutter-animation>) ⇒  (ret <gobject>)
— Method: get-object

Retrieves the <gobject> attached to animation.

animation
a <clutter-animation>
ret
a <gobject>.

Since 1.0

— Function: clutter-animation-set-mode (self <clutter-animation>) (mode unsigned-long)
— Method: set-mode

Sets the animation mode of animation. The animation mode is a logical id, either coming from the <clutter-animation-mode> enumeration or the return value of clutter-alpha-register-func.

This function will also set <"alpha"> if needed.

animation
a <clutter-animation>
mode
an animation mode logical id

Since 1.0

— Function: clutter-animation-get-mode (self <clutter-animation>) ⇒  (ret unsigned-long)
— Method: get-mode

Retrieves the animation mode of animation, as set by clutter-animation-set-mode.

animation
a <clutter-animation>
ret
the mode for the animation

Since 1.0

— Function: clutter-animation-set-duration (self <clutter-animation>) (msecs unsigned-int)
— Method: set-duration

Sets the duration of animation in milliseconds.

This function will set <"alpha"> and <"timeline"> if needed.

animation
a <clutter-animation>
msecs
the duration in milliseconds

Since 1.0

— Function: clutter-animation-get-duration (self <clutter-animation>) ⇒  (ret unsigned-int)
— Method: get-duration

Retrieves the duration of animation, in milliseconds.

animation
a <clutter-animation>
ret
the duration of the animation

Since 1.0

— Function: clutter-animation-set-loop (self <clutter-animation>) (loop bool)
— Method: set-loop

Sets whether animation should loop over itself once finished.

A looping <clutter-animation> will not emit the <"completed"> signal when finished.

This function will set <"alpha"> and <"timeline"> if needed.

animation
a <clutter-animation>
loop
‘#t’ if the animation should loop

Since 1.0

— Function: clutter-animation-get-loop (self <clutter-animation>) ⇒  (ret bool)
— Method: get-loop

Retrieves whether animation is looping.

animation
a <clutter-animation>
ret
‘#t’ if the animation is looping

Since 1.0

— Function: clutter-animation-set-timeline (self <clutter-animation>) (timeline <clutter-timeline>)
— Method: set-timeline

Sets the <clutter-timeline> used by animation.

This function will take a reference on the passed timeline.

animation
a <clutter-animation>
timeline
a <clutter-timeline>, or ‘#f’ to unset the current <clutter-timeline>.

Since 1.0

— Function: clutter-animation-get-timeline (self <clutter-animation>) ⇒  (ret <clutter-timeline>)
— Method: get-timeline

Retrieves the <clutter-timeline> used by animation

animation
a <clutter-animation>
ret
the timeline used by the animation.

Since 1.0

— Function: clutter-animation-completed (self <clutter-animation>)
— Method: completed

Emits the ::completed signal on animation

When using this function with a <clutter-animation> created by the clutter-actor-animate family of functions, animation will be unreferenced and it will not be valid anymore, unless g-object-ref was called before calling this function or unless a reference was taken inside a handler for the <"completed"> signal

animation
a <clutter-animation>

Since 1.0

— Function: clutter-animation-bind (self <clutter-animation>) (property_name mchars) (final <gvalue>) ⇒  (ret <clutter-animation>)
— Method: bind

Adds a single property with name property-name to the animation animation. For more information about animations, see clutter-actor-animate.

This method returns the animation primarily to make chained calls convenient in language bindings.

animation
a <clutter-animation>
property-name
the property to control
final
The final value of the property
ret
The animation itself.

Since 1.0

— Function: clutter-animation-bind-interval (self <clutter-animation>) (property_name mchars) (interval <clutter-interval>) ⇒  (ret <clutter-animation>)
— Method: bind-interval

Binds interval to the property-name of the <gobject> attached to animation. The <clutter-animation> will take ownership of the passed <clutter-interval>. For more information about animations, see clutter-actor-animate.

If you need to update the interval instance use clutter-animation-update-interval instead.

animation
a <clutter-animation>
property-name
the property to control
interval
a <clutter-interval>.
ret
The animation itself.

Since 1.0

— Function: clutter-animation-update (self <clutter-animation>) (property_name mchars) (final <gvalue>) ⇒  (ret <clutter-animation>)
— Method: update

Updates the final value of the interval for property-name

animation
a <clutter-animation>
property-name
name of the property
final
The final value of the property
ret
The animation itself.

Since 1.0

— Function: clutter-animation-update-interval (self <clutter-animation>) (property_name mchars) (interval <clutter-interval>)
— Method: update-interval

Changes the interval for property-name. The <clutter-animation> will take ownership of the passed <clutter-interval>.

animation
a <clutter-animation>
property-name
name of the property
interval
a <clutter-interval>

Since 1.0

— Function: clutter-animation-has-property (self <clutter-animation>) (property_name mchars) ⇒  (ret bool)
— Method: has-property

Checks whether animation is controlling property-name.

animation
a <clutter-animation>
property-name
name of the property
ret
‘#t’ if the property is animated by the <clutter-animation>, ‘#f’ otherwise

Since 1.0

— Function: clutter-animation-unbind-property (self <clutter-animation>) (property_name mchars)
— Method: unbind-property

Removes property-name from the list of animated properties.

animation
a <clutter-animation>
property-name
name of the property

Since 1.0

— Function: clutter-animation-get-interval (self <clutter-animation>) (property_name mchars) ⇒  (ret <clutter-interval>)
— Method: get-interval

Retrieves the <clutter-interval> associated to property-name inside animation.

animation
a <clutter-animation>
property-name
name of the property
ret
a <clutter-interval> or ‘#f’ if no property with the same name was found. The returned interval is owned by the <clutter-animation> and should not be unreferenced.

Since 1.0

— Function: clutter-actor-get-animation (self <clutter-actor>) ⇒  (ret <clutter-animation>)
— Method: get-animation

Retrieves the <clutter-animation> used by actor, if clutter-actor-animate has been called on actor.

actor
a <clutter-actor>
ret
a <clutter-animation>, or ‘#f’.

Since 1.0

— Function: clutter-actor-detach-animation (self <clutter-actor>)
— Method: detach-animation

Detaches the <clutter-animation> used by actor, if clutter-actor-animate has been called on actor.

Once the animation has been detached, it loses a reference. If it was the only reference then the <clutter-animation> becomes invalid.

The <"completed"> signal will not be emitted.

actor
a <clutter-actor>

Since 1.4