Defining ClutterAnimationMode inside ClutterScript

When defining a ClutterAnimation inside a ClutterScript file or string the "mode" can be defined either using the ClutterAnimationMode enumeration values through their "nick" (the short string used inside GEnumValue), their numeric id, or using the following strings:

ClutterAnimation

typedef struct _ClutterAnimation ClutterAnimation;

The ClutterAnimation structure contains only private data and should be accessed using the provided functions.

Since 1.0

struct ClutterAnimationClass

struct ClutterAnimationClass {
  void (* started)   (ClutterAnimation *animation);
  void (* completed) (ClutterAnimation *animation);
};

The ClutterAnimationClass structure contains only private data and should be accessed using the provided functions.

Since 1.0

clutter_animation_new ()

ClutterAnimation *  clutter_animation_new               (void);

Creates a new ClutterAnimation 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 ClutterActor and automatically manage the lifetime of a ClutterAnimation instance, so you should consider using those functions instead of manually creating an animation.

Since 1.0

clutter_animation_set_object ()

void                clutter_animation_set_object        (ClutterAnimation *animation,
                                                         GObject *object);

Attaches animation to object. The ClutterAnimation will take a reference on object.

Since 1.0

clutter_animation_get_object ()

GObject *           clutter_animation_get_object        (ClutterAnimation *animation);

Retrieves the GObject attached to animation.

Since 1.0

clutter_animation_set_mode ()

void                clutter_animation_set_mode          (ClutterAnimation *animation,
                                                         gulong mode);

Sets the animation mode of animation. The animation mode is a logical id, either coming from the ClutterAnimationMode enumeration or the return value of clutter_alpha_register_func().

This function will also set "alpha" if needed.

Since 1.0

clutter_animation_get_mode ()

gulong              clutter_animation_get_mode          (ClutterAnimation *animation);

Retrieves the animation mode of animation, as set by clutter_animation_set_mode().

Since 1.0

clutter_animation_set_duration ()

void                clutter_animation_set_duration      (ClutterAnimation *animation,
                                                         guint msecs);

Sets the duration of animation in milliseconds.

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

Since 1.0

clutter_animation_get_duration ()

guint               clutter_animation_get_duration      (ClutterAnimation *animation);

Retrieves the duration of animation, in milliseconds.

Since 1.0

clutter_animation_set_loop ()

void                clutter_animation_set_loop          (ClutterAnimation *animation,
                                                         gboolean loop);

Sets whether animation should loop over itself once finished.

A looping ClutterAnimation will not emit the "completed" signal when finished.

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

Since 1.0

clutter_animation_get_loop ()

gboolean            clutter_animation_get_loop          (ClutterAnimation *animation);

Retrieves whether animation is looping.

Since 1.0

clutter_animation_set_timeline ()

void                clutter_animation_set_timeline      (ClutterAnimation *animation,
                                                         ClutterTimeline *timeline);

Sets the ClutterTimeline used by animation.

This function will take a reference on the passed timeline.

Since 1.0

clutter_animation_get_timeline ()

ClutterTimeline *   clutter_animation_get_timeline      (ClutterAnimation *animation);

Retrieves the ClutterTimeline used by animation

Since 1.0

clutter_animation_set_alpha ()

void                clutter_animation_set_alpha         (ClutterAnimation *animation,
                                                         ClutterAlpha *alpha);

Sets alpha as the ClutterAlpha used by animation.

If alpha is not NULL, the ClutterAnimation will take ownership of the ClutterAlpha instance.

Since 1.0

clutter_animation_get_alpha ()

ClutterAlpha *      clutter_animation_get_alpha         (ClutterAnimation *animation);

Retrieves the ClutterAlpha used by animation.

Since 1.0

clutter_animation_completed ()

void                clutter_animation_completed         (ClutterAnimation *animation);

Emits the ::completed signal on animation

When using this function with a ClutterAnimation 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

Since 1.0

clutter_animation_bind ()

ClutterAnimation *  clutter_animation_bind              (ClutterAnimation *animation,
                                                         const gchar *property_name,
                                                         const GValue *final);

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.

Since 1.0

clutter_animation_bind_interval ()

ClutterAnimation *  clutter_animation_bind_interval     (ClutterAnimation *animation,
                                                         const gchar *property_name,
                                                         ClutterInterval *interval);

Binds interval to the property_name of the GObject attached to animation. The ClutterAnimation will take ownership of the passed ClutterInterval. For more information about animations, see clutter_actor_animate().

If you need to update the interval instance use clutter_animation_update_interval() instead.

Since 1.0

clutter_animation_update ()

ClutterAnimation *  clutter_animation_update            (ClutterAnimation *animation,
                                                         const gchar *property_name,
                                                         const GValue *final);

Updates the final value of the interval for property_name

Since 1.0

clutter_animation_update_interval ()

void                clutter_animation_update_interval   (ClutterAnimation *animation,
                                                         const gchar *property_name,
                                                         ClutterInterval *interval);

Changes the interval for property_name. The ClutterAnimation will take ownership of the passed ClutterInterval.

Since 1.0

clutter_animation_has_property ()

gboolean            clutter_animation_has_property      (ClutterAnimation *animation,
                                                         const gchar *property_name);

Checks whether animation is controlling property_name.

Since 1.0

clutter_animation_unbind_property ()

void                clutter_animation_unbind_property   (ClutterAnimation *animation,
                                                         const gchar *property_name);

Removes property_name from the list of animated properties.

Since 1.0

clutter_animation_get_interval ()

ClutterInterval *   clutter_animation_get_interval      (ClutterAnimation *animation,
                                                         const gchar *property_name);

Retrieves the ClutterInterval associated to property_name inside animation.

Since 1.0

clutter_actor_animate ()

ClutterAnimation *  clutter_actor_animate               (ClutterActor *actor,
                                                         gulong mode,
                                                         guint duration,
                                                         const gchar *first_property_name,
                                                         ...);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite duration and a speed given by the mode.

For example, this:

1
2
3
4

clutter_actor_animate (rectangle, CLUTTER_LINEAR, 250,
                       "width", 100.0,
                       "height", 100.0,
                       NULL);

will make width and height properties of the ClutterActor "rectangle" grow linearly between the current value and 100 pixels, in 250 milliseconds.

The animation mode is a logical id, either from the ClutterAnimationMode enumeration of from clutter_alpha_register_func().

All the properties specified will be animated between the current value and the final value. If a property should be set at the beginning of the animation but not updated during the animation, it should be prefixed by the "fixed::" string, for instance:

1
2
3
4

clutter_actor_animate (actor, CLUTTER_EASE_IN_SINE, 100,
                       "rotation-angle-z", 360.0,
                       "fixed::rotation-center-z", &center,
                       NULL);

Will animate the "rotation-angle-z" property between the current value and 360 degrees, and set the "rotation-center-z" property to the fixed value of the ClutterVertex "center".

This function will implicitly create a ClutterAnimation object which will be assigned to the actor and will be returned to the developer to control the animation or to know when the animation has been completed.

If a name argument starts with "signal::", "signal-after::", "signal-swapped::" or "signal-swapped-after::" the two following arguments are used as callback function and data for a signal handler installed on the ClutterAnimation object for the specified signal name, for instance:

1
2
3
4
5
6
7
8
9
10
11

static void
on_animation_completed (ClutterAnimation *animation,
                        ClutterActor     *actor)
{
  clutter_actor_hide (actor);
}

clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
                       "opacity", 0,
                       "signal::completed", on_animation_completed, actor,
                       NULL);

or, to automatically destroy an actor at the end of the animation:

1
2
3
4
5
6

clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
                       "opacity", 0,
                       "signal-swapped-after::completed",
                         clutter_actor_destroy,
                         actor,
                       NULL);

The "signal::" modifier is the equivalent of using g_signal_connect(); the "signal-after::" modifier is the equivalent of using g_signal_connect_after() or g_signal_connect_data() with the G_CONNECT_AFTER; the "signal-swapped::" modifier is the equivalent of using g_signal_connect_swapped() or g_signal_connect_data() with the G_CONNECT_SWAPPED flah; finally, the "signal-swapped-after::" modifier is the equivalent of using g_signal_connect_data() with both the G_CONNECT_AFTER and G_CONNECT_SWAPPED flags. The clutter_actor_animate() function will not keep track of multiple connections to the same signal, so it is your responsability to avoid them when calling clutter_actor_animate() multiple times on the same actor.

Calling this function on an actor that is already being animated will cause the current animation to change with the new final values, the new easing mode and the new duration - that is, this code:

1
2
3
4
5
6
7
8
9

clutter_actor_animate (actor, CLUTTER_LINEAR, 250,
                       "width", 100.0,
                       "height", 100.0,
                       NULL);
clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
                       "x", 100.0,
                       "y", 100.0,
                       "width", 200.0,
                       NULL);

is the equivalent of:

1
2
3
4
5
6

clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
                       "x", 100.0,
                       "y", 100.0,
                       "width", 200.0,
                       "height", 100.0,
                       NULL);

Since the created ClutterAnimation instance attached to actor is guaranteed to be valid throughout the "completed" signal emission chain, you will not be able to create a new animation using clutter_actor_animate() on the same actor from within the "completed" signal handler unless you use g_signal_connect_after() to connect the callback function, for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

static void
on_animation_completed (ClutterAnimation *animation,
                        ClutterActor     *actor)
{
  clutter_actor_animate (actor, CLUTTER_EASE_OUT_CUBIC, 250,
                         "x", 500.0,
                         "y", 500.0,
                         NULL);
}

  ...
  animation = clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 250,
                                     "x", 100.0,
                                     "y", 100.0,
                                     NULL);
  g_signal_connect (animation, "completed",
                    G_CALLBACK (on_animation_completed),
                    actor);
  ...

Since 1.0

clutter_actor_animate_with_timeline ()

ClutterAnimation *  clutter_actor_animate_with_timeline (ClutterActor *actor,
                                                         gulong mode,
                                                         ClutterTimeline *timeline,
                                                         const gchar *first_property_name,
                                                         ...);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite duration given by timeline and a speed given by the mode.

See clutter_actor_animate() for further details.

This function is useful if you want to use an existing timeline to animate actor.

Since 1.0

clutter_actor_animate_with_alpha ()

ClutterAnimation *  clutter_actor_animate_with_alpha    (ClutterActor *actor,
                                                         ClutterAlpha *alpha,
                                                         const gchar *first_property_name,
                                                         ...);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite behaviour given by the passed alpha.

See clutter_actor_animate() for further details.

This function is useful if you want to use an existing ClutterAlpha to animate actor.

Since 1.0

clutter_actor_animatev ()

ClutterAnimation *  clutter_actor_animatev              (ClutterActor *actor,
                                                         gulong mode,
                                                         guint duration,
                                                         gint n_properties,
                                                         const gchar * const properties[],
                                                         const GValue *values);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite duration and a speed given by the mode.

This is the vector-based variant of clutter_actor_animate(), useful for language bindings.

Since 1.0

clutter_actor_animate_with_timelinev ()

ClutterAnimation *  clutter_actor_animate_with_timelinev
                                                        (ClutterActor *actor,
                                                         gulong mode,
                                                         ClutterTimeline *timeline,
                                                         gint n_properties,
                                                         const gchar * const properties[],
                                                         const GValue *values);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite duration given by timeline and a speed given by the mode.

See clutter_actor_animate() for further details.

This function is useful if you want to use an existing timeline to animate actor.

This is the vector-based variant of clutter_actor_animate_with_timeline(), useful for language bindings.

Since 1.0

clutter_actor_animate_with_alphav ()

ClutterAnimation *  clutter_actor_animate_with_alphav   (ClutterActor *actor,
                                                         ClutterAlpha *alpha,
                                                         gint n_properties,
                                                         const gchar * const properties[],
                                                         const GValue *values);

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite behaviour given by the passed alpha.

See clutter_actor_animate() for further details.

This function is useful if you want to use an existing ClutterAlpha to animate actor.

This is the vector-based variant of clutter_actor_animate_with_alpha(), useful for language bindings.

Since 1.0

clutter_actor_get_animation ()

ClutterAnimation *  clutter_actor_get_animation         (ClutterActor *actor);

Retrieves the ClutterAnimation used by actor, if clutter_actor_animate() has been called on actor.

Since 1.0

clutter_actor_detach_animation ()

void                clutter_actor_detach_animation      (ClutterActor *actor);

Detaches the ClutterAnimation 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 ClutterAnimation becomes invalid.

The "completed" signal will not be emitted.

Since 1.4

The "alpha" property

  "alpha"                    ClutterAlpha*         : Read / Write

The ClutterAlpha used by the animation.

Since 1.0

The "duration" property

  "duration"                 guint                 : Read / Write

The duration of the animation, expressed in milliseconds.

Default value: 0

Since 1.0

The "loop" property

  "loop"                     gboolean              : Read / Write

Whether the animation should loop.

Default value: FALSE

Since 1.0

The "mode" property

  "mode"                     gulong                : Read / Write

The animation mode, either a value from ClutterAnimationMode or a value returned by clutter_alpha_register_func(). The default value is CLUTTER_LINEAR.

Since 1.0

The "object" property

  "object"                   GObject*              : Read / Write

The GObject to which the animation applies.

Since 1.0

The "timeline" property

  "timeline"                 ClutterTimeline*      : Read / Write

The ClutterTimeline used by the animation.

Since 1.0

The "completed" signal

void                user_function                      (ClutterAnimation *animation,
                                                        gpointer          user_data)      : Run Last

The ::completed signal is emitted once the animation has been completed.

The animation instance is guaranteed to be valid for the entire duration of the signal emission chain.

Since 1.0

The "started" signal

void                user_function                      (ClutterAnimation *animation,
                                                        gpointer          user_data)      : Run Last

The ::started signal is emitted once the animation has been started

Since 1.0