Implicit Animations

## Implicit Animations Implicit Animations — Simple implicit animations |

## Synopsis

    struct              ClutterAnimation;
    struct              ClutterAnimationClass;
    enum                ClutterAnimationMode;
    ClutterAnimation *  clutter_animation_new               (void);
    void                clutter_animation_set_object        (ClutterAnimation *animation,
                                                             GObject *object);
    GObject *           clutter_animation_get_object        (ClutterAnimation *animation);
    void                clutter_animation_set_mode          (ClutterAnimation *animation,
                                                             gulong mode);
    gulong              clutter_animation_get_mode          (ClutterAnimation *animation);
    void                clutter_animation_set_duration      (ClutterAnimation *animation,
                                                             guint msecs);
    guint               clutter_animation_get_duration      (ClutterAnimation *animation);
    void                clutter_animation_set_loop          (ClutterAnimation *animation,
                                                             gboolean loop);
    gboolean            clutter_animation_get_loop          (ClutterAnimation *animation);
    void                clutter_animation_set_timeline      (ClutterAnimation *animation,
                                                             ClutterTimeline *timeline);
    ClutterTimeline *   clutter_animation_get_timeline      (ClutterAnimation *animation);
    void                clutter_animation_set_alpha         (ClutterAnimation *animation,
                                                             ClutterAlpha *alpha);
    ClutterAlpha *      clutter_animation_get_alpha         (ClutterAnimation *animation);
    void                clutter_animation_completed         (ClutterAnimation *animation);

    ClutterAnimation *  clutter_animation_bind              (ClutterAnimation *animation,
                                                             const gchar *property_name,
                                                             const GValue *final);
    ClutterAnimation *  clutter_animation_bind_interval     (ClutterAnimation *animation,
                                                             const gchar *property_name,
                                                             ClutterInterval *interval);
    ClutterAnimation *  clutter_animation_update            (ClutterAnimation *animation,
                                                             const gchar *property_name,
                                                             const GValue *final);
    void                clutter_animation_update_interval   (ClutterAnimation *animation,
                                                             const gchar *property_name,
                                                             ClutterInterval *interval);
    gboolean            clutter_animation_has_property      (ClutterAnimation *animation,
                                                             const gchar *property_name);
    void                clutter_animation_unbind_property   (ClutterAnimation *animation,
                                                             const gchar *property_name);
    ClutterInterval *   clutter_animation_get_interval      (ClutterAnimation *animation,
                                                             const gchar *property_name);

    ClutterAnimation *  clutter_actor_animate               (ClutterActor *actor,
                                                             gulong mode,
                                                             guint duration,
                                                             const gchar *first_property_name,
                                                             ...);
    ClutterAnimation *  clutter_actor_animate_with_timeline (ClutterActor *actor,
                                                             gulong mode,
                                                             ClutterTimeline *timeline,
                                                             const gchar *first_property_name,
                                                             ...);
    ClutterAnimation *  clutter_actor_animate_with_alpha    (ClutterActor *actor,
                                                             ClutterAlpha *alpha,
                                                             const gchar *first_property_name,
                                                             ...);
    ClutterAnimation *  clutter_actor_animatev              (ClutterActor *actor,
                                                             gulong mode,
                                                             guint duration,
                                                             gint n_properties,
                                                             const gchar * const properties[],
                                                             const GValue *values);
    ClutterAnimation *  clutter_actor_animate_with_timelinev
                                                            (ClutterActor *actor,
                                                             gulong mode,
                                                             ClutterTimeline *timeline,
                                                             gint n_properties,
                                                             const gchar * const properties[],
                                                             const GValue *values);
    ClutterAnimation *  clutter_actor_animate_with_alphav   (ClutterActor *actor,
                                                             ClutterAlpha *alpha,
                                                             gint n_properties,
                                                             const gchar * const properties[],
                                                             const GValue *values);
    ClutterAnimation *  clutter_actor_get_animation         (ClutterActor *actor);
    void                clutter_actor_detach_animation      (ClutterActor *actor);

## Object Hierarchy

      GObject
       +----ClutterAnimation

## Implemented Interfaces

ClutterAnimation implements ClutterScriptable.

## Properties

      "alpha"                    ClutterAlpha*         : Read / Write
      "duration"                 guint                 : Read / Write
      "loop"                     gboolean              : Read / Write
      "mode"                     gulong                : Read / Write
      "object"                   GObject*              : Read / Write
      "timeline"                 ClutterTimeline*      : Read / Write

## Signals

      "completed"                                      : Run Last
      "started"                                        : Run Last

## Description

ClutterAnimation is an object providing simple, implicit animations for GObjects.

ClutterAnimation instances will bind one or more GObject properties belonging to a GObject to a ClutterInterval, and will then use a ClutterAlpha 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 ClutterTimeline using `clutter_animation_get_timeline()` and then use ClutterTimeline functions like `clutter_timeline_start()`, `clutter_timeline_pause()` or `clutter_timeline_stop()`.

A ClutterAnimation will emit the "completed" signal when the ClutterTimeline used by the animation is completed; unlike ClutterTimeline, though, the "completed" will not be emitted if "loop" is set to `TRUE` - 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 ClutterAnimation implements the ClutterAnimatable interface it is possible for that instance to control the way the initial and final states are interpolated.

ClutterAnimations are distinguished from ClutterBehaviours 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 ClutterBehaviour `alpha_notify` virtual function, and can control multiple ClutterActors 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 ClutterAnimation instance and animate an actor between its current state and the specified final state.

### 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:

easeInQuad, easeOutQuad, easeInOutQuad | Corresponding to the quadratic easing modes
easeInCubic, easeOutCubic, easeInOutCubic | Corresponding to the cubic easing modes
easeInQuart, easeOutQuart, easeInOutQuart | Corresponding to the quartic easing modes
easeInQuint, easeOutQuint, easeInOutQuint | Corresponding to the quintic easing modes
easeInSine, easeOutSine, easeInOutSine | Corresponding to the sine easing modes
easeInExpo, easeOutExpo, easeInOutExpo | Corresponding to the exponential easing modes
easeInCirc, easeOutCirc, easeInOutCirc | Corresponding to the circular easing modes
easeInElastic, easeOutElastic, easeInOutElastic | Corresponding to the overshooting elastic easing modes
easeInBack, easeOutBack, easeInOutBack | Corresponding to the overshooting cubic easing modes
easeInBounce, easeOutBounce, easeInOutBounce | Corresponding to the bouncing easing modes

Example 11. Tweening using `clutter_actor_animate()`

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
    257
    258
    259
    260
    261
    262
    263
    264
    265
    266
    267
    268
    269
    270
    #include <stdlib.h>
    #include <gmodule.h>
    #include <clutter/clutter.h>

    /* all the easing modes provided by Clutter */
    static const struct {
      const gchar *name;
      ClutterAnimationMode mode;
    } easing_modes[] = {
      { "linear", CLUTTER_LINEAR },
      { "easeInQuad", CLUTTER_EASE_IN_QUAD },
      { "easeOutQuad", CLUTTER_EASE_OUT_QUAD },
      { "easeInOutQuad", CLUTTER_EASE_IN_OUT_QUAD },
      { "easeInCubic", CLUTTER_EASE_IN_CUBIC },
      { "easeOutCubic", CLUTTER_EASE_OUT_CUBIC },
      { "easeInOutCubic", CLUTTER_EASE_IN_OUT_CUBIC },
      { "easeInQuart", CLUTTER_EASE_IN_QUART },
      { "easeOutQuart", CLUTTER_EASE_OUT_QUART },
      { "easeInOutQuart", CLUTTER_EASE_IN_OUT_QUART },
      { "easeInQuint", CLUTTER_EASE_IN_QUINT },
      { "easeOutQuint", CLUTTER_EASE_OUT_QUINT },
      { "easeInOutQuint", CLUTTER_EASE_IN_OUT_QUINT },
      { "easeInSine", CLUTTER_EASE_IN_SINE },
      { "easeOutSine", CLUTTER_EASE_OUT_SINE },
      { "easeInOutSine", CLUTTER_EASE_IN_OUT_SINE },
      { "easeInExpo", CLUTTER_EASE_IN_EXPO },
      { "easeOutExpo", CLUTTER_EASE_OUT_EXPO },
      { "easeInOutExpo", CLUTTER_EASE_IN_OUT_EXPO },
      { "easeInCirc", CLUTTER_EASE_IN_CIRC },
      { "easeOutCirc", CLUTTER_EASE_OUT_CIRC },
      { "easeInOutCirc", CLUTTER_EASE_IN_OUT_CIRC },
      { "easeInElastic", CLUTTER_EASE_IN_ELASTIC },
      { "easeOutElastic", CLUTTER_EASE_OUT_ELASTIC },
      { "easeInOutElastic", CLUTTER_EASE_IN_OUT_ELASTIC },
      { "easeInBack", CLUTTER_EASE_IN_BACK },
      { "easeOutBack", CLUTTER_EASE_OUT_BACK },
      { "easeInOutBack", CLUTTER_EASE_IN_OUT_BACK },
      { "easeInBounce", CLUTTER_EASE_IN_BOUNCE },
      { "easeOutBounce", CLUTTER_EASE_OUT_BOUNCE },
      { "easeInOutBounce", CLUTTER_EASE_IN_OUT_BOUNCE },
    };

    #define HELP_TEXT       "Easing mode: %s (%d of %d)\n" \
                            "Left click to tween\n" \
                            "Right click to change the easing mode"

    static const gint n_easing_modes = G_N_ELEMENTS (easing_modes);
    static gint current_mode = 0;

    static gint duration = 1;
    static gboolean recenter = FALSE;

    static ClutterActor *main_stage = NULL;
    static ClutterActor *easing_mode_label = NULL;

    static ClutterAnimation *last_animation = NULL;

    /* recenter_bouncer:
     *
     * repositions (through an animation) the bouncer at the center of the stage
     */
    static void
    recenter_bouncer (ClutterAnimation *animation,
                      ClutterActor     *rectangle)
    {
      gfloat base_x, base_y;
      gint cur_mode;

      base_x = clutter_actor_get_width (main_stage) / 2;
      base_y = clutter_actor_get_height (main_stage) / 2;

      cur_mode = easing_modes[current_mode].mode;

      clutter_actor_animate (rectangle, cur_mode, 250,
                             "x", base_x,
                             "y", base_y,
                             NULL);
    }

    static gboolean
    on_button_press (ClutterActor       *actor,
                     ClutterButtonEvent *event,
                     ClutterActor       *rectangle)
    {
      if (event->button == CLUTTER_BUTTON_SECONDARY)
        {
          gchar *text;

          /* cycle through the various easing modes */
          current_mode = (current_mode + 1 < n_easing_modes)
                       ? current_mode + 1
                       : 0;

          /* update the text of the label */
          text = g_strdup_printf (HELP_TEXT,
                                  easing_modes[current_mode].name,
                                  current_mode + 1,
                                  n_easing_modes);

          clutter_text_set_text (CLUTTER_TEXT (easing_mode_label), text);
          g_free (text);
        }
      else if (event->button == CLUTTER_BUTTON_PRIMARY)
        {
          ClutterAnimation *animation;
          ClutterAnimationMode cur_mode;

          cur_mode = easing_modes[current_mode].mode;

          /* tween the actor using the current easing mode */
          animation =
            clutter_actor_animate (rectangle, cur_mode, duration * 1000,
                                   "x", event->x,
                                   "y", event->y,
                                   NULL);

          /* if we were asked to, recenter the bouncer at the end of the
           * animation. we keep track of the animation to avoid connecting
           * the signal handler to the same Animation twice.
           */
          if (recenter && last_animation != animation)
            g_signal_connect_after (animation, "completed",
                                    G_CALLBACK (recenter_bouncer),
                                    rectangle);

          last_animation = animation;
        }

      return TRUE;
    }

    static gboolean
    draw_bouncer (ClutterCairoTexture *texture,
                  cairo_t             *cr)
    {
      const ClutterColor *bouncer_color;
      cairo_pattern_t *pattern;
      guint width, height;
      float radius;

      clutter_cairo_texture_get_surface_size (texture, &width, &height);

      radius = MAX (width, height);

      clutter_cairo_texture_clear (texture);

      cairo_arc (cr, radius / 2, radius / 2, radius / 2, 0.0, 2.0 * G_PI);

      bouncer_color = CLUTTER_COLOR_DarkScarletRed;

      pattern = cairo_pattern_create_radial (radius / 2, radius / 2, 0,
                                             radius, radius, radius);
      cairo_pattern_add_color_stop_rgba (pattern,
                                         0,
                                         bouncer_color->red / 255.0,
                                         bouncer_color->green / 255.0,
                                         bouncer_color->blue / 255.0,
                                         bouncer_color->alpha / 255.0);
      cairo_pattern_add_color_stop_rgba (pattern,
                                         0.85,
                                         bouncer_color->red / 255.0,
                                         bouncer_color->green / 255.0,
                                         bouncer_color->blue / 255.0,
                                         0.25);

      cairo_set_source (cr, pattern);
      cairo_fill_preserve (cr);

      cairo_pattern_destroy (pattern);

      return TRUE;
    }

    static ClutterActor *
    make_bouncer (gfloat width,
                  gfloat height)
    {
      ClutterActor *retval;

      retval = clutter_cairo_texture_new (width, height);
      g_signal_connect (retval, "draw", G_CALLBACK (draw_bouncer), NULL);

      clutter_actor_set_name (retval, "bouncer");
      clutter_actor_set_size (retval, width, height);
      clutter_actor_set_anchor_point (retval, width / 2, height / 2);
      clutter_actor_set_reactive (retval, TRUE);

      /* make sure we draw the bouncer immediately */
      clutter_cairo_texture_invalidate (CLUTTER_CAIRO_TEXTURE (retval));

      return retval;
    }

    static GOptionEntry test_easing_entries[] = {
      {
        "re-center", 'r',
        0,
        G_OPTION_ARG_NONE, &recenter,
        "Re-center the actor when the animation ends",
        NULL
      },
      {
        "duration", 'd',
        0,
        G_OPTION_ARG_INT, &duration,
        "Duration of the animation",
        "SECONDS"
      },

      { NULL }
    };

    G_MODULE_EXPORT int
    test_easing_main (int argc, char *argv[])
    {
      ClutterActor *stage, *rect, *label;
      gchar *text;
      gfloat stage_width, stage_height;
      GError *error = NULL;

      if (clutter_init_with_args (&argc, &argv,
                                  NULL,
                                  test_easing_entries,
                                  NULL,
                                  &error) != CLUTTER_INIT_SUCCESS)
        return 1;

      stage = clutter_stage_new ();
      clutter_stage_set_title (CLUTTER_STAGE (stage), "Easing Modes");
      clutter_actor_set_background_color (stage, CLUTTER_COLOR_LightSkyBlue);
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
      main_stage = stage;

      clutter_actor_get_size (stage, &stage_width, &stage_height);

      /* create the actor that we want to tween */
      rect = make_bouncer (50, 50);
      clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
      clutter_actor_set_position (rect, stage_width / 2, stage_height / 2);

      text = g_strdup_printf (HELP_TEXT,
                              easing_modes[current_mode].name,
                              current_mode + 1,
                              n_easing_modes);

      label = clutter_text_new ();
      clutter_container_add_actor (CLUTTER_CONTAINER (stage), label);
      clutter_text_set_text (CLUTTER_TEXT (label), text);
      clutter_actor_add_constraint (label, clutter_align_constraint_new (stage, CLUTTER_ALIGN_X_AXIS, 0.95));
      clutter_actor_add_constraint (label, clutter_align_constraint_new (stage, CLUTTER_ALIGN_Y_AXIS, 0.95));
      easing_mode_label = label;

      g_free (text);

      g_signal_connect (stage,
                        "button-press-event", G_CALLBACK (on_button_press),
                        rect);

      clutter_actor_show (stage);

      clutter_main ();

      return EXIT_SUCCESS;
    }

    G_MODULE_EXPORT const char *
    test_easing_describe (void)
    {
      return "Visualize all easing modes provided by Clutter";
    }

ClutterAnimation is available since Clutter 1.0

## Details

### struct ClutterAnimation

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

`started` () | class handler for the "started" signal
`completed` () | class handler for the "completed" signal

Since 1.0

### enum ClutterAnimationMode

    typedef enum {
      CLUTTER_CUSTOM_MODE = 0,

      /* linear */
      CLUTTER_LINEAR,

      /* quadratic */
      CLUTTER_EASE_IN_QUAD,
      CLUTTER_EASE_OUT_QUAD,
      CLUTTER_EASE_IN_OUT_QUAD,

      /* cubic */
      CLUTTER_EASE_IN_CUBIC,
      CLUTTER_EASE_OUT_CUBIC,
      CLUTTER_EASE_IN_OUT_CUBIC,

      /* quartic */
      CLUTTER_EASE_IN_QUART,
      CLUTTER_EASE_OUT_QUART,
      CLUTTER_EASE_IN_OUT_QUART,

      /* quintic */
      CLUTTER_EASE_IN_QUINT,
      CLUTTER_EASE_OUT_QUINT,
      CLUTTER_EASE_IN_OUT_QUINT,

      /* sinusoidal */
      CLUTTER_EASE_IN_SINE,
      CLUTTER_EASE_OUT_SINE,
      CLUTTER_EASE_IN_OUT_SINE,

      /* exponential */
      CLUTTER_EASE_IN_EXPO,
      CLUTTER_EASE_OUT_EXPO,
      CLUTTER_EASE_IN_OUT_EXPO,

      /* circular */
      CLUTTER_EASE_IN_CIRC,
      CLUTTER_EASE_OUT_CIRC,
      CLUTTER_EASE_IN_OUT_CIRC,

      /* elastic */
      CLUTTER_EASE_IN_ELASTIC,
      CLUTTER_EASE_OUT_ELASTIC,
      CLUTTER_EASE_IN_OUT_ELASTIC,

      /* overshooting cubic */
      CLUTTER_EASE_IN_BACK,
      CLUTTER_EASE_OUT_BACK,
      CLUTTER_EASE_IN_OUT_BACK,

      /* exponentially decaying parabolic */
      CLUTTER_EASE_IN_BOUNCE,
      CLUTTER_EASE_OUT_BOUNCE,
      CLUTTER_EASE_IN_OUT_BOUNCE,

      /* guard, before registered alpha functions */
      CLUTTER_ANIMATION_LAST
    } ClutterAnimationMode;

The animation modes used by ClutterAlpha and ClutterAnimation. This enumeration can be expanded in later versions of Clutter. See the ClutterAlpha documentation for a graph of all the animation modes.

Every global alpha function registered using `clutter_alpha_register_func()` or `clutter_alpha_register_closure()` will have a logical id greater than `CLUTTER_ANIMATION_LAST`.

`CLUTTER_CUSTOM_MODE` | custom progress function
`CLUTTER_LINEAR` | linear tweening
`CLUTTER_EASE_IN_QUAD` | quadratic tweening
`CLUTTER_EASE_OUT_QUAD` | quadratic tweening, inverse of `CLUTTER_EASE_IN_QUAD`
`CLUTTER_EASE_IN_OUT_QUAD` | quadratic tweening, combininig `CLUTTER_EASE_IN_QUAD` and `CLUTTER_EASE_OUT_QUAD`
`CLUTTER_EASE_IN_CUBIC` | cubic tweening
`CLUTTER_EASE_OUT_CUBIC` | cubic tweening, invers of `CLUTTER_EASE_IN_CUBIC`
`CLUTTER_EASE_IN_OUT_CUBIC` | cubic tweening, combining `CLUTTER_EASE_IN_CUBIC` and `CLUTTER_EASE_OUT_CUBIC`
`CLUTTER_EASE_IN_QUART` | quartic tweening
`CLUTTER_EASE_OUT_QUART` | quartic tweening, inverse of `CLUTTER_EASE_IN_QUART`
`CLUTTER_EASE_IN_OUT_QUART` | quartic tweening, combining `CLUTTER_EASE_IN_QUART` and `CLUTTER_EASE_OUT_QUART`
`CLUTTER_EASE_IN_QUINT` | quintic tweening
`CLUTTER_EASE_OUT_QUINT` | quintic tweening, inverse of `CLUTTER_EASE_IN_QUINT`
`CLUTTER_EASE_IN_OUT_QUINT` | fifth power tweening, combining `CLUTTER_EASE_IN_QUINT` and `CLUTTER_EASE_OUT_QUINT`
`CLUTTER_EASE_IN_SINE` | sinusoidal tweening
`CLUTTER_EASE_OUT_SINE` | sinusoidal tweening, inverse of `CLUTTER_EASE_IN_SINE`
`CLUTTER_EASE_IN_OUT_SINE` | sine wave tweening, combining `CLUTTER_EASE_IN_SINE` and `CLUTTER_EASE_OUT_SINE`
`CLUTTER_EASE_IN_EXPO` | exponential tweening
`CLUTTER_EASE_OUT_EXPO` | exponential tweening, inverse of `CLUTTER_EASE_IN_EXPO`
`CLUTTER_EASE_IN_OUT_EXPO` | exponential tweening, combining `CLUTTER_EASE_IN_EXPO` and `CLUTTER_EASE_OUT_EXPO`
`CLUTTER_EASE_IN_CIRC` | circular tweening
`CLUTTER_EASE_OUT_CIRC` | circular tweening, inverse of `CLUTTER_EASE_IN_CIRC`
`CLUTTER_EASE_IN_OUT_CIRC` | circular tweening, combining `CLUTTER_EASE_IN_CIRC` and `CLUTTER_EASE_OUT_CIRC`
`CLUTTER_EASE_IN_ELASTIC` | elastic tweening, with offshoot on start
`CLUTTER_EASE_OUT_ELASTIC` | elastic tweening, with offshoot on end
`CLUTTER_EASE_IN_OUT_ELASTIC` | elastic tweening with offshoot on both ends
`CLUTTER_EASE_IN_BACK` | overshooting cubic tweening, with backtracking on start
`CLUTTER_EASE_OUT_BACK` | overshooting cubic tweening, with backtracking on end
`CLUTTER_EASE_IN_OUT_BACK` | overshooting cubic tweening, with backtracking on both ends
`CLUTTER_EASE_IN_BOUNCE` | exponentially decaying parabolic (bounce) tweening, with bounce on start
`CLUTTER_EASE_OUT_BOUNCE` | exponentially decaying parabolic (bounce) tweening, with bounce on end
`CLUTTER_EASE_IN_OUT_BOUNCE` | exponentially decaying parabolic (bounce) tweening, with bounce on both ends
`CLUTTER_ANIMATION_LAST` | last animation mode, used as a guard for registered global alpha 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.

Returns : | the newly created ClutterAnimation. Use `g_object_unref()` to release the associated resources

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

`animation` : | a ClutterAnimation
`object` : | a GObject

Since 1.0

### clutter_animation_get_object ()

    GObject *           clutter_animation_get_object        (ClutterAnimation *animation);

Retrieves the GObject attached to `animation`.

`animation` : | a ClutterAnimation
Returns : | a GObject. [transfer none]

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.

`animation` : | a ClutterAnimation
`mode` : | an animation mode logical id

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()`.

`animation` : | a ClutterAnimation
Returns : | the mode for the animation

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.

`animation` : | a ClutterAnimation
`msecs` : | the duration in milliseconds

Since 1.0

### clutter_animation_get_duration ()

    guint               clutter_animation_get_duration      (ClutterAnimation *animation);

Retrieves the duration of `animation`, in milliseconds.

`animation` : | a ClutterAnimation
Returns : | the duration of the animation

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.

`animation` : | a ClutterAnimation
`loop` : | `TRUE` if the animation should loop

Since 1.0

### clutter_animation_get_loop ()

    gboolean            clutter_animation_get_loop          (ClutterAnimation *animation);

Retrieves whether `animation` is looping.

`animation` : | a ClutterAnimation
Returns : | `TRUE` if the 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`.

`animation` : | a ClutterAnimation
`timeline` : | a ClutterTimeline, or `NULL` to unset the current ClutterTimeline. [allow-none]

Since 1.0

### clutter_animation_get_timeline ()

    ClutterTimeline *   clutter_animation_get_timeline      (ClutterAnimation *animation);

Retrieves the ClutterTimeline used by `animation`

`animation` : | a ClutterAnimation
Returns : | the timeline used by the animation. [transfer none]

Since 1.0

### clutter_animation_set_alpha ()

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

### Warning

`clutter_animation_set_alpha` has been deprecated since version 1.10 and should not be used in newly-written code. Use `clutter_animation_get_timeline()` and `clutter_timeline_set_progress_mode()` instead.

Sets `alpha` as the ClutterAlpha used by `animation`.

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

`animation` : | a ClutterAnimation
`alpha` : | a ClutterAlpha, or `NULL` to unset the current ClutterAlpha

Since 1.0

### clutter_animation_get_alpha ()

    ClutterAlpha *      clutter_animation_get_alpha         (ClutterAnimation *animation);

### Warning

`clutter_animation_get_alpha` has been deprecated since version 1.10 and should not be used in newly-written code. Use `clutter_animation_get_timeline()` and `clutter_timeline_get_progress_mode()` instead.

Retrieves the ClutterAlpha used by `animation`.

`animation` : | a ClutterAnimation
Returns : | the alpha object used by the animation. [transfer none]

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

`animation` : | a ClutterAnimation

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.

`animation` : | a ClutterAnimation
`property_name` : | the property to control
`final` : | The final value of the property
Returns : | The animation itself. [transfer none]

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.

`animation` : | a ClutterAnimation
`property_name` : | the property to control
`interval` : | a ClutterInterval. [transfer full]
Returns : | The animation itself. [transfer none]

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`

`animation` : | a ClutterAnimation
`property_name` : | name of the property
`final` : | The final value of the property
Returns : | The animation itself. [transfer none]

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.

`animation` : | a ClutterAnimation
`property_name` : | name of the property
`interval` : | a 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`.

`animation` : | a ClutterAnimation
`property_name` : | name of the property
Returns : | `TRUE` if the property is animated by the ClutterAnimation, `FALSE` otherwise

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.

`animation` : | a ClutterAnimation
`property_name` : | name of the property

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

`animation` : | a ClutterAnimation
`property_name` : | name of the property
Returns : | a ClutterInterval or `NULL` if no property with the same name was found. The returned interval is owned by the ClutterAnimation and should not be unreferenced. [transfer none]

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);

### Note

Unless the animation is looping, the ClutterAnimation created by `clutter_actor_animate()` will become invalid as soon as it is complete.

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);
      ...

`actor` : | a ClutterActor
`mode` : | an animation mode logical id
`duration` : | duration of the animation, in milliseconds
`first_property_name` : | the name of a property
`...` : | a `NULL` terminated list of property names and property values
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

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

`actor` : | a ClutterActor
`mode` : | an animation mode logical id
`timeline` : | a ClutterTimeline
`first_property_name` : | the name of a property
`...` : | a `NULL` terminated list of property names and property values
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

Since 1.0

### clutter_actor_animate_with_alpha ()

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

### Warning

`clutter_actor_animate_with_alpha` has been deprecated since version 1.10 and should not be used in newly-written code. Use `clutter_actor_animate_with_timeline()` instead

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

`actor` : | a ClutterActor
`alpha` : | a ClutterAlpha
`first_property_name` : | the name of a property
`...` : | a `NULL` terminated list of property names and property values
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

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.

### Warning

Unlike `clutter_actor_animate()`, this function will not allow you to specify "signal::" names and callbacks.

`actor` : | a ClutterActor
`mode` : | an animation mode logical id
`duration` : | duration of the animation, in milliseconds
`n_properties` : | number of property names and values
`properties` : | a vector containing the property names to set. [array length=n_properties][element-type utf8]
`values` : | a vector containing the property values to set. [array length=n_properties]
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

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.

### Warning

Unlike `clutter_actor_animate_with_timeline()`, this function will not allow you to specify "signal::" names and callbacks.

`actor` : | a ClutterActor
`mode` : | an animation mode logical id
`timeline` : | a ClutterTimeline
`n_properties` : | number of property names and values
`properties` : | a vector containing the property names to set. [array length=n_properties][element-type utf8]
`values` : | a vector containing the property values to set. [array length=n_properties]
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

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);

### Warning

`clutter_actor_animate_with_alphav` has been deprecated since version 1.10 and should not be used in newly-written code. Use `clutter_actor_animate_with_timelinev()` instead

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.

### Warning

Unlike `clutter_actor_animate_with_alpha()`, this function will not allow you to specify "signal::" names and callbacks.

`actor` : | a ClutterActor
`alpha` : | a ClutterAlpha
`n_properties` : | number of property names and values
`properties` : | a vector containing the property names to set. [array length=n_properties][element-type utf8]
`values` : | a vector containing the property values to set. [array length=n_properties]
Returns : | a ClutterAnimation object. The object is owned by the ClutterActor and should not be unreferenced with `g_object_unref()`. [transfer none]

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

`actor` : | a ClutterActor
Returns : | a ClutterAnimation, or `NULL`. [transfer none]

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.

`actor` : | a ClutterActor

Since 1.4

## Property Details

### The `"alpha"` property

      "alpha"                    ClutterAlpha*         : Read / Write

### Warning

`ClutterAnimation:alpha` has been deprecated since version 1.10 and should not be used in newly-written code. Use the "timeline" property and the "progress-mode" property instead.

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

## Signal Details

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

`animation` : | the animation that emitted the signal
`user_data` : | user data set when the signal handler was connected.

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

`animation` : | the animation that emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0

## See Also

ClutterAnimatable, ClutterInterval, ClutterAlpha, ClutterTimeline