Next: , Previous: ClutterAnimatable, Up: Top

9 ClutterAnimator

Multi-actor tweener

9.1 Overview

<clutter-animator> is an object providing declarative animations for <gobject> properties belonging to one or more <gobject>s to <clutter-intervals>.

<clutter-animator> is used to build and describe complex animations in terms of "key frames". <clutter-animator> is meant to be used through the <clutter-script> definition format, but it comes with a convenience C API.

9.2 Key Frames

Every animation handled by a <clutter-animator> can be described in terms of "key frames". For each <gobject> property there can be multiple key frames, each one defined by the end value for the property to be computed starting from the current value to a specific point in time, using a given easing mode.

The point in time is defined using a value representing the progress in the normalized interval of [ 0, 1 ]. This maps the value returned by clutter-timeline-get-duration.

In the image above the duration of the animation is represented by the blue line. Each key frame is the white dot, along with its progress. The red line represents the computed function of time given the easing mode.

9.3 ClutterAnimator description for <clutter-script>

<clutter-animator> defines a custom "properties" property which allows describing the key frames for objects.

The "properties" property has the following syntax: 

     
      {
        "properties" : [
          {
            "object" : &lt;id of an object>,
            "name" : &lt;name of the property>,
            "ease-in" : &lt;boolean>,
            "interpolation" : &lt;#ClutterInterpolation value>,
            "keys" : [
              [ &lt;progress>, &lt;easing mode>, &lt;final value> ]
            ]
        ]
      }

The following JSON fragment defines a <clutter-animator> with the duration of 1 second and operating on the x and y properties of a <clutter-actor> named "rect-01", with two frames for each property. The first frame will linearly move the actor from its current position to the 100, 100 position in 20 percent of the duration of the animation; the second will using a cubic easing to move the actor to the 200, 200 coordinates. 

     
      {
        "type" : "ClutterAnimator",
        "duration" : 1000,
        "properties" : [
          {
            "object" : "rect-01",
            "name" : "x",
            "ease-in" : true,
            "keys" : [
              [ 0.2, "linear",       100.0 ],
              [ 1.0, "easeOutCubic", 200.0 ]
            ]
          },
          {
            "object" : "rect-01",
            "name" : "y",
            "ease-in" : true,
            "keys" : [
              [ 0.2, "linear",       100.0 ],
              [ 1.0, "easeOutCubic", 200.0 ]
            ]
          }
        ]
      }

<clutter-animator> is available since Clutter 1.2

9.4 Usage

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

Creates a new <clutter-animator> instance

ret
a new <clutter-animator>.

Since 1.2

— Function: clutter-animator-set-key (self <clutter-animator>) (object <gobject>) (property_name mchars) (mode unsigned-int) (progress double) (value <gvalue>) ⇒  (ret <clutter-animator>)
— Method: set-key

Sets a single key in the <clutter-animator> for the property-name of object at progress.

See also: clutter-animator-set

animator
a <clutter-animator>
object
a <gobject>
property-name
the property to specify a key for
mode
the id of the alpha function to use
progress
the normalized range at which stage of the animation this value applies
value
the value property_name should have at progress.
ret
The animator instance.

Since 1.2

— Function: clutter-animator-remove-key (self <clutter-animator>) (object <gobject>) (property_name mchars) (progress double)
— Method: remove-key

Removes all keys matching the conditions specificed in the arguments.

animator
a <clutter-animator>
object
a <gobject> to search for, or ‘#f’ for all.
property-name
a specific property name to query for, or ‘#f’ for all.
progress
a specific progress to search for or a negative value for all

Since 1.2

— Function: clutter-animator-get-keys (self <clutter-animator>) (object <gobject>) (property_name mchars) (progress double) ⇒  (ret glist-of)
— Method: get-keys

Returns a list of pointers to opaque structures with accessor functions that describe the keys added to an animator.

animator
a <clutter-animator> instance
object
a <gobject> to search for, or ‘#f’ for all objects.
property-name
a specific property name to query for, or ‘#f’ for all properties.
progress
a specific progress to search for, or a negative value for all progresses
ret
a list of <clutter-animator-key>s; the contents of the list are owned by the <clutter-animator>, but you should free the returned list when done, using g-list-free.

Since 1.2

— Function: clutter-animator-start (self <clutter-animator>) ⇒  (ret <clutter-timeline>)
— Method: start

Start the ClutterAnimator, this is a thin wrapper that rewinds and starts the animators current timeline.

animator
a <clutter-animator>
ret
the <clutter-timeline> that drives the animator. The returned timeline is owned by the <clutter-animator> and it should not be unreferenced.

Since 1.2

— Function: clutter-animator-compute-value (self <clutter-animator>) (object <gobject>) (property_name mchars) (progress double) (value <gvalue>) ⇒  (ret bool)
— Method: compute-value

Compute the value for a managed property at a given progress.

If the property is an ease-in property, the current value of the property on the object will be used as the starting point for computation.

animator
a <clutter-animator>
object
a <gobject>
property-name
the name of the property on object to check
progress
a value between 0.0 and 1.0
value
an initialized value to store the computed result
ret
‘#t’ if the computation yields has a value, otherwise (when an error occurs or the progress is before any of the keys) ‘#f’ is returned and the <gvalue> is left untouched

Since 1.2

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

Sets an external timeline that will be used for driving the animation

animator
a <clutter-animator>
timeline
a <clutter-timeline>

Since 1.2

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

Get the timeline hooked up for driving the <clutter-animator>

animator
a <clutter-animator>
ret
the <clutter-timeline> that drives the animator.

Since 1.2

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

Runs the timeline of the <clutter-animator> with a duration in msecs as specified.

animator
a <clutter-animator>
duration
milliseconds a run of the animator should last.

Since 1.2

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

Retrieves the current duration of an animator

animator
a <clutter-animator>
ret
the duration of the animation, in milliseconds

Since 1.2

— Function: clutter-animator-key-get-object (self <clutter-animator-key>) ⇒  (ret <gobject>)

Retrieves the object a key applies to.

key
a <clutter-animator-key>
ret
the object an animator_key exist for.

Since 1.2

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

Retrieves the mode of a <clutter-animator> key, for the first key of a property for an object this represents the whether the animation is open ended and or curved for the remainding keys for the property it represents the easing mode.

key
a <clutter-animator-key>
ret
the mode of a <clutter-animator-key>

Since 1.2

— Function: clutter-animator-key-get-progress (self <clutter-animator-key>) ⇒  (ret double)

Retrieves the progress of an clutter_animator_key

key
a <clutter-animator-key>
ret
the progress defined for a <clutter-animator> key.

Since 1.2

— Function: clutter-animator-key-get-value (self <clutter-animator-key>) (value <gvalue>) ⇒  (ret bool)

Retrieves a copy of the value for a <clutter-animator-key>.

The passed in <gvalue> needs to be already initialized for the value type of the key or to a type that allow transformation from the value type of the key.

Use g-value-unset when done.

key
a <clutter-animator-key>
value
a <gvalue> initialized with the correct type for the animator key
ret
‘#t’ if the passed <gvalue> was successfully set, and ‘#f’ otherwise

Since 1.2