ClutterAnimator

ClutterAnimator — Multi-actor tweener

Synopsis

                    ClutterAnimator;
struct              ClutterAnimatorClass;
ClutterAnimator *   clutter_animator_new                (void);
void                clutter_animator_set                (ClutterAnimator *animator,
                                                         gpointer first_object,
                                                         const gchar *first_property_name,
                                                         guint first_mode,
                                                         gdouble first_progress,
                                                         ...);
ClutterAnimator *   clutter_animator_set_key            (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         guint mode,
                                                         gdouble progress,
                                                         const GValue *value);
void                clutter_animator_remove_key         (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress);
GList *             clutter_animator_get_keys           (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress);
ClutterTimeline *   clutter_animator_start              (ClutterAnimator *animator);
gboolean            clutter_animator_compute_value      (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress,
                                                         GValue *value);

void                clutter_animator_set_timeline       (ClutterAnimator *animator,
                                                         ClutterTimeline *timeline);
ClutterTimeline *   clutter_animator_get_timeline       (ClutterAnimator *animator);
void                clutter_animator_set_duration       (ClutterAnimator *animator,
                                                         guint duration);
guint               clutter_animator_get_duration       (ClutterAnimator *animator);

void                clutter_animator_property_set_ease_in
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gboolean ease_in);
gboolean            clutter_animator_property_get_ease_in
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name);
enum                ClutterInterpolation;
void                clutter_animator_property_set_interpolation
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         ClutterInterpolation interpolation);
ClutterInterpolation clutter_animator_property_get_interpolation
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name);

                    ClutterAnimatorKey;
GObject *           clutter_animator_key_get_object     (const ClutterAnimatorKey *key);
const gchar *       clutter_animator_key_get_property_name
                                                        (const ClutterAnimatorKey *key);
GType               clutter_animator_key_get_property_type
                                                        (const ClutterAnimatorKey *key);
gulong              clutter_animator_key_get_mode       (const ClutterAnimatorKey *key);
gdouble             clutter_animator_key_get_progress   (const ClutterAnimatorKey *key);
gboolean            clutter_animator_key_get_value      (const ClutterAnimatorKey *key,
                                                         GValue *value);

Object Hierarchy

  GObject
   +----ClutterAnimator

Implemented Interfaces

ClutterAnimator implements ClutterScriptable.

Properties

  "duration"                 guint                 : Read / Write
  "timeline"                 ClutterTimeline*      : Read / Write

Description

ClutterAnimator is an object providing declarative animations for GObject properties belonging to one or more GObjects to ClutterIntervals.

ClutterAnimator is used to build and describe complex animations in terms of "key frames". ClutterAnimator is meant to be used through the ClutterScript definition format, but it comes with a convenience C API.

Key Frames

Every animation handled by a ClutterAnimator 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().

Figure 9. Key Frames

Key Frames

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.

ClutterAnimator description for ClutterScript

ClutterAnimator defines a custom "properties" property which allows describing the key frames for objects.

The "properties" property has the following syntax:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "properties" : [
    {
      "object" : <id of an object>,
      "name" : <name of the property>,
      "ease-in" : <boolean>,
      "interpolation" : <#ClutterInterpolation value>,
      "keys" : [
        [ <progress>, <easing mode>, <final value> ]
      ]
  ]
}

Example 22. ClutterAnimator definition

The following JSON fragment defines a ClutterAnimator with the duration of 1 second and operating on the x and y properties of a ClutterActor 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 ]
       ]
     }
   ]
 }
    

ClutterAnimator is available since Clutter 1.2

ClutterAnimator has been deprecated in Clutter 1.12

Details

ClutterAnimator

typedef struct _ClutterAnimator ClutterAnimator;

Warning

ClutterAnimator is deprecated and should not be used in newly-written code. 1.12

The ClutterAnimator structure contains only private data and should be accessed using the provided API

Since 1.2


struct ClutterAnimatorClass

struct ClutterAnimatorClass {
};

Warning

ClutterAnimatorClass is deprecated and should not be used in newly-written code. 1.12

The ClutterAnimatorClass structure contains only private data

Since 1.2


clutter_animator_new ()

ClutterAnimator *   clutter_animator_new                (void);

Warning

clutter_animator_new has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Creates a new ClutterAnimator instance

Returns :

a new ClutterAnimator.

Since 1.2


clutter_animator_set ()

void                clutter_animator_set                (ClutterAnimator *animator,
                                                         gpointer first_object,
                                                         const gchar *first_property_name,
                                                         guint first_mode,
                                                         gdouble first_progress,
                                                         ...);

Warning

clutter_animator_set has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Adds multiple keys to a ClutterAnimator, specifying the value a given property should have at a given progress of the animation. The mode specified is the mode used when going to this key from the previous key of the property_name

If a given (object, property, progress) tuple already exist the mode and value will be replaced with the new values.

animator :

a ClutterAnimator

first_object :

a GObject

first_property_name :

the property to specify a key for

first_mode :

the id of the alpha function to use

first_progress :

at which stage of the animation this value applies; the range is a normalized floating point value between 0 and 1

... :

the value first_property_name should have for first_object at first_progress, followed by more (object, property_name, mode, progress, value) tuples, followed by NULL

Since 1.2


clutter_animator_set_key ()

ClutterAnimator *   clutter_animator_set_key            (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         guint mode,
                                                         gdouble progress,
                                                         const GValue *value);

Warning

clutter_animator_set_key has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Sets a single key in the ClutterAnimator for the property_name of object at progress.

See also: clutter_animator_set()

animator :

a ClutterAnimator

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.

Returns :

The animator instance. [transfer none]

Since 1.2


clutter_animator_remove_key ()

void                clutter_animator_remove_key         (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress);

Warning

clutter_animator_remove_key has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Removes all keys matching the conditions specificed in the arguments.

animator :

a ClutterAnimator

object :

a GObject to search for, or NULL for all. [allow-none]

property_name :

a specific property name to query for, or NULL for all. [allow-none]

progress :

a specific progress to search for or a negative value for all

Since 1.2


clutter_animator_get_keys ()

GList *             clutter_animator_get_keys           (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress);

Warning

clutter_animator_get_keys has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

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

animator :

a ClutterAnimator instance

object :

a GObject to search for, or NULL for all objects. [allow-none]

property_name :

a specific property name to query for, or NULL for all properties. [allow-none]

progress :

a specific progress to search for, or a negative value for all progresses

Returns :

a list of ClutterAnimatorKeys; the contents of the list are owned by the ClutterAnimator, but you should free the returned list when done, using g_list_free(). [transfer container][element-type Clutter.AnimatorKey]

Since 1.2


clutter_animator_start ()

ClutterTimeline *   clutter_animator_start              (ClutterAnimator *animator);

Warning

clutter_animator_start has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

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

animator :

a ClutterAnimator

Returns :

the ClutterTimeline that drives the animator. The returned timeline is owned by the ClutterAnimator and it should not be unreferenced. [transfer none]

Since 1.2


clutter_animator_compute_value ()

gboolean            clutter_animator_compute_value      (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gdouble progress,
                                                         GValue *value);

Warning

clutter_animator_compute_value has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

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 ClutterAnimator

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

Returns :

TRUE if the computation yields has a value, otherwise (when an error occurs or the progress is before any of the keys) FALSE is returned and the GValue is left untouched

Since 1.2


clutter_animator_set_timeline ()

void                clutter_animator_set_timeline       (ClutterAnimator *animator,
                                                         ClutterTimeline *timeline);

Warning

clutter_animator_set_timeline has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

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

animator :

a ClutterAnimator

timeline :

a ClutterTimeline

Since 1.2


clutter_animator_get_timeline ()

ClutterTimeline *   clutter_animator_get_timeline       (ClutterAnimator *animator);

Warning

clutter_animator_get_timeline has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Get the timeline hooked up for driving the ClutterAnimator

animator :

a ClutterAnimator

Returns :

the ClutterTimeline that drives the animator. [transfer none]

Since 1.2


clutter_animator_set_duration ()

void                clutter_animator_set_duration       (ClutterAnimator *animator,
                                                         guint duration);

Warning

clutter_animator_set_duration has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Runs the timeline of the ClutterAnimator with a duration in msecs as specified.

animator :

a ClutterAnimator

duration :

milliseconds a run of the animator should last.

Since 1.2


clutter_animator_get_duration ()

guint               clutter_animator_get_duration       (ClutterAnimator *animator);

Warning

clutter_animator_get_duration has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the current duration of an animator

animator :

a ClutterAnimator

Returns :

the duration of the animation, in milliseconds

Since 1.2


clutter_animator_property_set_ease_in ()

void                clutter_animator_property_set_ease_in
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         gboolean ease_in);

Warning

clutter_animator_property_set_ease_in has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Sets whether a property value is to be eased into the animation.

animator :

a ClutterAnimatorKey

object :

a GObject

property_name :

the name of a property on object

ease_in :

we are going to be easing in this property

Since 1.2


clutter_animator_property_get_ease_in ()

gboolean            clutter_animator_property_get_ease_in
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name);

Warning

clutter_animator_property_get_ease_in has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Checks if a property value is to be eased into the animation.

animator :

a ClutterAnimatorKey

object :

a GObject

property_name :

the name of a property on object

Returns :

TRUE if the property is eased in

Since 1.2


enum ClutterInterpolation

typedef enum {
  CLUTTER_INTERPOLATION_LINEAR,
  CLUTTER_INTERPOLATION_CUBIC
} ClutterInterpolation;

The mode of interpolation between key frames

CLUTTER_INTERPOLATION_LINEAR

linear interpolation

CLUTTER_INTERPOLATION_CUBIC

cubic interpolation

Since 1.2


clutter_animator_property_set_interpolation ()

void                clutter_animator_property_set_interpolation
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name,
                                                         ClutterInterpolation interpolation);

Warning

clutter_animator_property_set_interpolation has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Set the interpolation method to use, CLUTTER_INTERPOLATION_LINEAR causes the values to linearly change between the values, and CLUTTER_INTERPOLATION_CUBIC causes the values to smoothly change between the values.

animator :

a ClutterAnimatorKey

object :

a GObject

property_name :

the name of a property on object

interpolation :

the ClutterInterpolation to use

Since 1.2


clutter_animator_property_get_interpolation ()

ClutterInterpolation clutter_animator_property_get_interpolation
                                                        (ClutterAnimator *animator,
                                                         GObject *object,
                                                         const gchar *property_name);

Warning

clutter_animator_property_get_interpolation has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Get the interpolation used by animator for a property on a particular object.

animator :

a ClutterAnimatorKey

object :

a GObject

property_name :

the name of a property on object

Returns :

a ClutterInterpolation value.

Since 1.2


ClutterAnimatorKey

typedef struct _ClutterAnimatorKey ClutterAnimatorKey;

A key frame inside a ClutterAnimator

Since 1.2


clutter_animator_key_get_object ()

GObject *           clutter_animator_key_get_object     (const ClutterAnimatorKey *key);

Warning

clutter_animator_key_get_object has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the object a key applies to.

key :

a ClutterAnimatorKey

Returns :

the object an animator_key exist for. [transfer none]

Since 1.2


clutter_animator_key_get_property_name ()

const gchar *       clutter_animator_key_get_property_name
                                                        (const ClutterAnimatorKey *key);

Warning

clutter_animator_key_get_property_name has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the name of the property a key applies to.

key :

a ClutterAnimatorKey

Returns :

the name of the property an animator_key exist for.

Since 1.2


clutter_animator_key_get_property_type ()

GType               clutter_animator_key_get_property_type
                                                        (const ClutterAnimatorKey *key);

Warning

clutter_animator_key_get_property_type has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the GType of the property a key applies to

You can use this type to initialize the GValue to pass to clutter_animator_key_get_value()

key :

a ClutterAnimatorKey

Returns :

the GType of the property

Since 1.2


clutter_animator_key_get_mode ()

gulong              clutter_animator_key_get_mode       (const ClutterAnimatorKey *key);

Warning

clutter_animator_key_get_mode has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the mode of a ClutterAnimator 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 ClutterAnimatorKey

Returns :

the mode of a ClutterAnimatorKey

Since 1.2


clutter_animator_key_get_progress ()

gdouble             clutter_animator_key_get_progress   (const ClutterAnimatorKey *key);

Warning

clutter_animator_key_get_progress has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves the progress of an clutter_animator_key

key :

a ClutterAnimatorKey

Returns :

the progress defined for a ClutterAnimator key.

Since 1.2


clutter_animator_key_get_value ()

gboolean            clutter_animator_key_get_value      (const ClutterAnimatorKey *key,
                                                         GValue *value);

Warning

clutter_animator_key_get_value has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

Retrieves a copy of the value for a ClutterAnimatorKey.

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 ClutterAnimatorKey

value :

a GValue initialized with the correct type for the animator key

Returns :

TRUE if the passed GValue was successfully set, and FALSE otherwise

Since 1.2

Property Details

The "duration" property

  "duration"                 guint                 : Read / Write

Warning

ClutterAnimator:duration has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

The duration of the ClutterTimeline used by the ClutterAnimator to drive the animation

Default value: 2000

Since 1.2


The "timeline" property

  "timeline"                 ClutterTimeline*      : Read / Write

Warning

ClutterAnimator:timeline has been deprecated since version 1.12 and should not be used in newly-written code. Use ClutterKeyframeTransition instead

The ClutterTimeline used by the ClutterAnimator to drive the animation

Since 1.2

See Also

ClutterAnimatable, ClutterInterval, ClutterAlpha, ClutterTimeline