Debian Codegraph @

clutter/deprecated/clutter-animation.c

raw
1 /*
2 * Clutter.
3 *
4 * An OpenGL based 'interactive canvas' library.
5 *
6 * Copyright (C) 2008 Intel Corporation.
7 *
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Lesser General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
12 *
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public
19 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 *
21 * Author:
22 * Emmanuele Bassi <[email protected]>
23 */
24
25 /**
26 * SECTION:clutter-animation
27 * @short_description: Simple implicit animations
28 * @See_Also: #ClutterAnimatable, #ClutterInterval, #ClutterAlpha,
29 * #ClutterTimeline
30 *
31 * #ClutterAnimation is an object providing simple, implicit animations
32 * for #GObjects.
33 *
34 * #ClutterAnimation instances will bind one or more #GObject properties
35 * belonging to a #GObject to a #ClutterInterval, and will then use a
36 * #ClutterAlpha to interpolate the property between the initial and final
37 * values of the interval.
38 *
39 * The duration of the animation is set using clutter_animation_set_duration().
40 * The easing mode of the animation is set using clutter_animation_set_mode().
41 *
42 * If you want to control the animation you should retrieve the
43 * #ClutterTimeline using clutter_animation_get_timeline() and then
44 * use #ClutterTimeline functions like clutter_timeline_start(),
45 * clutter_timeline_pause() or clutter_timeline_stop().
46 *
47 * A #ClutterAnimation will emit the #ClutterAnimation::completed signal
48 * when the #ClutterTimeline used by the animation is completed; unlike
49 * #ClutterTimeline, though, the #ClutterAnimation::completed will not be
50 * emitted if #ClutterAnimation:loop is set to %TRUE - that is, a looping
51 * animation never completes.
52 *
53 * If your animation depends on user control you can force its completion
54 * using clutter_animation_completed().
55 *
56 * If the #GObject instance bound to a #ClutterAnimation implements the
57 * #ClutterAnimatable interface it is possible for that instance to
58 * control the way the initial and final states are interpolated.
59 *
60 * #ClutterAnimations are distinguished from #ClutterBehaviours
61 * because the former can only control #GObject properties of a single
62 * #GObject instance, while the latter can control multiple properties
63 * using accessor functions inside the #ClutterBehaviour
64 * `alpha_notify` virtual function, and can control multiple #ClutterActors
65 * as well.
66 *
67 * For convenience, it is possible to use the clutter_actor_animate()
68 * function call which will take care of setting up and tearing down
69 * a #ClutterAnimation instance and animate an actor between its current
70 * state and the specified final state.
71 *
72 * #ClutterAnimation is available since Clutter 1.0.
73 *
74 * #ClutterAnimation has been deprecated in Clutter 1.12. You should use
75 * the [implicit animation API][clutter-actor-animation] available inside
76 * #ClutterActor instead. If you require to define explicit transitions for
77 * one or more properties in order to reuse them, see #ClutterTransition
78 * instead.
79 *
80 * ## Defining ClutterAnimationMode inside ClutterScript
81 *
82 * When defining a #ClutterAnimation inside a ClutterScript
83 * file or string the #ClutterAnimation:mode can be defined either
84 * using the #ClutterAnimationMode enumeration values through their
85 * "nick" (the short string used inside #GEnumValue), their numeric
86 * id, or using the following strings:
87 *
88 * - easeInQuad, easeOutQuad, easeInOutQuad
89 * - easeInCubic, easeOutCubic, easeInOutCubic
90 * - easeInQuart, easeOutQuart, easeInOutQuart
91 * - easeInQuint, easeOutQuint, easeInOutQuint
92 * - easeInSine, easeOutSine, easeInOutSine
93 * - easeInExpo, easeOutExpo, easeInOutExpo
94 * - easeInCirc, easeOutCirc, easeInOutCirc
95 * - easeInElastic, easeOutElastic, easeInOutElastic
96 * - easeInBack, easeOutBack, easeInOutBack
97 * - easeInBounce, easeOutBounce, easeInOutBounce
98 */
99
100 #ifdef HAVE_CONFIG_H
101 #include "config.h"
102 #endif
103
104 #include <glib-object.h>
105 #include <gobject/gvaluecollector.h>
106
107 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
108
109 #include "clutter-alpha.h"
110 #include "clutter-animatable.h"
111 #include "clutter-animation.h"
112 #include "clutter-debug.h"
113 #include "clutter-enum-types.h"
114 #include "clutter-interval.h"
115 #include "clutter-marshal.h"
116 #include "clutter-private.h"
117 #include "clutter-scriptable.h"
118 #include "clutter-script-private.h"
119
120 #include "deprecated/clutter-animation.h"
121
122 enum
123 {
124 PROP_0,
125
126 PROP_OBJECT,
127 PROP_MODE,
128 PROP_DURATION,
129 PROP_LOOP,
130 PROP_TIMELINE,
131 PROP_ALPHA,
132
133 PROP_LAST
134 };
135
136 static GParamSpec *obj_props[PROP_LAST];
137
138 enum
139 {
140 STARTED,
141 COMPLETED,
142
143 LAST_SIGNAL
144 };
145
146 struct _ClutterAnimationPrivate
147 {
148 GObject *object;
149
150 GHashTable *properties;
151
152 ClutterAlpha *alpha;
153 ClutterTimeline *timeline;
154
155 guint timeline_started_id;
156 guint timeline_completed_id;
157 guint timeline_frame_id;
158 };
159
160 static guint animation_signals[LAST_SIGNAL] = { 0, };
161
162 static GQuark quark_object_animation = 0;
163
164 static void clutter_scriptable_init (ClutterScriptableIface *iface);
165
166 static void clutter_animation_set_alpha_internal (ClutterAnimation *animation,
167 ClutterAlpha *alpha);
168 static ClutterAlpha * clutter_animation_get_alpha_internal (ClutterAnimation *animation);
169 static ClutterTimeline * clutter_animation_get_timeline_internal (ClutterAnimation *animation);
170
171 G_DEFINE_TYPE_WITH_CODE (ClutterAnimation, clutter_animation, G_TYPE_OBJECT,
172 G_ADD_PRIVATE (ClutterAnimation)
173 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_SCRIPTABLE,
174 clutter_scriptable_init));
175
176 static ClutterAlpha *
177 clutter_animation_get_alpha_internal (ClutterAnimation *animation)
178 {
179 ClutterAnimationPrivate *priv = animation->priv;
180
181 if (priv->alpha == NULL)
182 {
183 ClutterAlpha *alpha;
184
185 alpha = clutter_alpha_new ();
186 clutter_alpha_set_mode (alpha, CLUTTER_LINEAR);
187
188 priv->alpha = g_object_ref_sink (alpha);
189
190 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_ALPHA]);
191 }
192
193 return priv->alpha;
194 }
195
196 static void
197 on_actor_destroy (ClutterActor *actor,
198 ClutterAnimation *animation)
199 {
200 ClutterAnimationPrivate *priv = animation->priv;
201 GObject *obj = G_OBJECT (actor);
202
203 if (obj == priv->object)
204 {
205 g_object_set_qdata (priv->object, quark_object_animation, NULL);
206 g_signal_handlers_disconnect_by_func (priv->object,
207 G_CALLBACK (on_actor_destroy),
208 animation);
209 g_object_unref (animation);
210 }
211 }
212
213 static void
214 clutter_animation_real_completed (ClutterAnimation *self)
215 {
216 ClutterAnimationPrivate *priv = self->priv;
217 ClutterAnimatable *animatable = NULL;
218 ClutterAnimation *animation;
219 ClutterTimeline *timeline;
220 ClutterTimelineDirection direction;
221 gpointer key, value;
222 GHashTableIter iter;
223
224 timeline = clutter_animation_get_timeline (self);
225 direction = clutter_timeline_get_direction (timeline);
226
227 if (CLUTTER_IS_ANIMATABLE (priv->object))
228 animatable = CLUTTER_ANIMATABLE (priv->object);
229
230 /* explicitly set the final state of the animation */
231 CLUTTER_NOTE (ANIMATION, "Set final state on object [%p]", priv->object);
232 g_hash_table_iter_init (&iter, priv->properties);
233 while (g_hash_table_iter_next (&iter, &key, &value))
234 {
235 const gchar *p_name = key;
236 ClutterInterval *interval = value;
237 GValue *p_value;
238
239 if (direction == CLUTTER_TIMELINE_FORWARD)
240 p_value = clutter_interval_peek_final_value (interval);
241 else
242 p_value = clutter_interval_peek_initial_value (interval);
243
244 if (animatable != NULL)
245 clutter_animatable_set_final_state (animatable, p_name, p_value);
246 else
247 g_object_set_property (priv->object, p_name, p_value);
248 }
249
250 /* at this point, if this animation was created by clutter_actor_animate()
251 * and friends, the animation will be attached to the object's data; since
252 * we want to allow developers to use g_signal_connect_after("completed")
253 * to concatenate a new animation, we need to remove the animation back
254 * pointer here, and unref() the animation. FIXME - we might want to
255 * provide a clutter_animation_attach()/clutter_animation_detach() pair
256 * to let the user reattach an animation
257 */
258 animation = g_object_get_qdata (priv->object, quark_object_animation);
259 if (animation == self)
260 {
261 CLUTTER_NOTE (ANIMATION, "Unsetting animation for actor [%p]",
262 priv->object);
263
264 g_object_set_qdata (priv->object, quark_object_animation, NULL);
265 g_signal_handlers_disconnect_by_func (priv->object,
266 G_CALLBACK (on_actor_destroy),
267 animation);
268
269 CLUTTER_NOTE (ANIMATION, "Releasing the reference Animation [%p]",
270 animation);
271 g_object_unref (animation);
272 }
273 }
274
275 static void
276 clutter_animation_finalize (GObject *gobject)
277 {
278 ClutterAnimationPrivate *priv = CLUTTER_ANIMATION (gobject)->priv;
279
280 CLUTTER_NOTE (ANIMATION,
281 "Destroying properties table for Animation [%p]",
282 gobject);
283 g_hash_table_destroy (priv->properties);
284
285 G_OBJECT_CLASS (clutter_animation_parent_class)->finalize (gobject);
286 }
287
288 static void
289 clutter_animation_dispose (GObject *gobject)
290 {
291 ClutterAnimationPrivate *priv = CLUTTER_ANIMATION (gobject)->priv;
292 ClutterTimeline *timeline;
293
294 if (priv->alpha != NULL)
295 timeline = clutter_alpha_get_timeline (priv->alpha);
296 else
297 timeline = priv->timeline;
298
299 if (timeline != NULL && priv->timeline_started_id != 0)
300 g_signal_handler_disconnect (timeline, priv->timeline_started_id);
301
302 if (timeline != NULL && priv->timeline_completed_id != 0)
303 g_signal_handler_disconnect (timeline, priv->timeline_completed_id);
304
305 if (timeline != NULL && priv->timeline_frame_id != 0)
306 g_signal_handler_disconnect (timeline, priv->timeline_frame_id);
307
308 priv->timeline_started_id = 0;
309 priv->timeline_completed_id = 0;
310 priv->timeline_frame_id = 0;
311
312 if (priv->timeline != NULL)
313 {
314 g_object_unref (priv->timeline);
315 priv->timeline = NULL;
316 }
317
318 if (priv->alpha != NULL)
319 {
320 g_object_unref (priv->alpha);
321 priv->alpha = NULL;
322 }
323
324 if (priv->object != NULL)
325 {
326 g_object_unref (priv->object);
327 priv->object = NULL;
328 }
329
330 G_OBJECT_CLASS (clutter_animation_parent_class)->dispose (gobject);
331 }
332
333 static void
334 clutter_animation_set_property (GObject *gobject,
335 guint prop_id,
336 const GValue *value,
337 GParamSpec *pspec)
338 {
339 ClutterAnimation *animation = CLUTTER_ANIMATION (gobject);
340
341 switch (prop_id)
342 {
343 case PROP_OBJECT:
344 clutter_animation_set_object (animation, g_value_get_object (value));
345 break;
346
347 case PROP_MODE:
348 clutter_animation_set_mode (animation, g_value_get_ulong (value));
349 break;
350
351 case PROP_DURATION:
352 clutter_animation_set_duration (animation, g_value_get_uint (value));
353 break;
354
355 case PROP_LOOP:
356 clutter_animation_set_loop (animation, g_value_get_boolean (value));
357 break;
358
359 case PROP_TIMELINE:
360 clutter_animation_set_timeline (animation, g_value_get_object (value));
361 break;
362
363 case PROP_ALPHA:
364 clutter_animation_set_alpha_internal (animation, g_value_get_object (value));
365 break;
366
367 default:
368 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
369 break;
370 }
371 }
372
373 static void
374 clutter_animation_get_property (GObject *gobject,
375 guint prop_id,
376 GValue *value,
377 GParamSpec *pspec)
378 {
379 ClutterAnimation *animation = CLUTTER_ANIMATION (gobject);
380 ClutterAnimationPrivate *priv = animation->priv;
381
382 switch (prop_id)
383 {
384 case PROP_OBJECT:
385 g_value_set_object (value, priv->object);
386 break;
387
388 case PROP_MODE:
389 g_value_set_ulong (value, clutter_animation_get_mode (animation));
390 break;
391
392 case PROP_DURATION:
393 g_value_set_uint (value, clutter_animation_get_duration (animation));
394 break;
395
396 case PROP_LOOP:
397 g_value_set_boolean (value, clutter_animation_get_loop (animation));
398 break;
399
400 case PROP_TIMELINE:
401 g_value_set_object (value, clutter_animation_get_timeline (animation));
402 break;
403
404 case PROP_ALPHA:
405 g_value_set_object (value, clutter_animation_get_alpha_internal (animation));
406 break;
407
408 default:
409 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
410 break;
411 }
412 }
413
414 static gboolean
415 clutter_animation_parse_custom_node (ClutterScriptable *scriptable,
416 ClutterScript *script,
417 GValue *value,
418 const gchar *name,
419 JsonNode *node)
420 {
421 if (strncmp (name, "mode", 4) == 0)
422 {
423 gulong mode;
424
425 mode = _clutter_script_resolve_animation_mode (node);
426
427 g_value_init (value, G_TYPE_ULONG);
428 g_value_set_ulong (value, mode);
429
430 return TRUE;
431 }
432
433 return FALSE;
434 }
435
436 static void
437 clutter_scriptable_init (ClutterScriptableIface *iface)
438 {
439 iface->parse_custom_node = clutter_animation_parse_custom_node;
440 }
441
442 static void
443 clutter_animation_class_init (ClutterAnimationClass *klass)
444 {
445 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
446
447 quark_object_animation =
448 g_quark_from_static_string ("clutter-actor-animation");
449
450 klass->completed = clutter_animation_real_completed;
451
452 gobject_class->set_property = clutter_animation_set_property;
453 gobject_class->get_property = clutter_animation_get_property;
454 gobject_class->dispose = clutter_animation_dispose;
455 gobject_class->finalize = clutter_animation_finalize;
456
457 /**
458 * ClutterAnimation:object:
459 *
460 * The #GObject to which the animation applies.
461 *
462 * Since: 1.0
463 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
464 */
465 obj_props[PROP_OBJECT] =
466 g_param_spec_object ("object",
467 P_("Object"),
468 P_("Object to which the animation applies"),
469 G_TYPE_OBJECT,
470 CLUTTER_PARAM_READWRITE);
471
472 /**
473 * ClutterAnimation:mode:
474 *
475 * The animation mode, either a value from #ClutterAnimationMode
476 * or a value returned by clutter_alpha_register_func(). The
477 * default value is %CLUTTER_LINEAR.
478 *
479 * Since: 1.0
480 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
481 */
482 obj_props[PROP_MODE] =
483 g_param_spec_ulong ("mode",
484 P_("Mode"),
485 P_("The mode of the animation"),
486 0, G_MAXULONG,
487 CLUTTER_LINEAR,
488 CLUTTER_PARAM_READWRITE);
489
490 /**
491 * ClutterAnimation:duration:
492 *
493 * The duration of the animation, expressed in milliseconds.
494 *
495 * Since: 1.0
496 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
497 */
498 obj_props[PROP_DURATION] =
499 g_param_spec_uint ("duration",
500 P_("Duration"),
501 P_("Duration of the animation, in milliseconds"),
502 0, G_MAXUINT,
503 0,
504 CLUTTER_PARAM_READWRITE);
505
506 /**
507 * ClutterAnimation:loop:
508 *
509 * Whether the animation should loop.
510 *
511 * Since: 1.0
512 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
513 */
514 obj_props[PROP_LOOP] =
515 g_param_spec_boolean ("loop",
516 P_("Loop"),
517 P_("Whether the animation should loop"),
518 FALSE,
519 CLUTTER_PARAM_READWRITE);
520
521 /**
522 * ClutterAnimation:timeline:
523 *
524 * The #ClutterTimeline used by the animation.
525 *
526 * Since: 1.0
527 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
528 */
529 obj_props[PROP_TIMELINE] =
530 g_param_spec_object ("timeline",
531 P_("Timeline"),
532 P_("The timeline used by the animation"),
533 CLUTTER_TYPE_TIMELINE,
534 CLUTTER_PARAM_READWRITE);
535
536 /**
537 * ClutterAnimation:alpha:
538 *
539 * The #ClutterAlpha used by the animation.
540 *
541 * Since: 1.0
542 *
543 * Deprecated: 1.10: Use the #ClutterAnimation:timeline property and
544 * the #ClutterTimeline:progress-mode property instead.
545 */
546 obj_props[PROP_ALPHA] =
547 g_param_spec_object ("alpha",
548 P_("Alpha"),
549 P_("The alpha used by the animation"),
550 CLUTTER_TYPE_ALPHA,
551 CLUTTER_PARAM_READWRITE | G_PARAM_DEPRECATED);
552
553 g_object_class_install_properties (gobject_class,
554 PROP_LAST,
555 obj_props);
556
557 /**
558 * ClutterAnimation::started:
559 * @animation: the animation that emitted the signal
560 *
561 * The ::started signal is emitted once the animation has been
562 * started
563 *
564 * Since: 1.0
565 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
566 */
567 animation_signals[STARTED] =
568 g_signal_new (I_("started"),
569 G_TYPE_FROM_CLASS (klass),
570 G_SIGNAL_RUN_LAST,
571 G_STRUCT_OFFSET (ClutterAnimationClass, started),
572 NULL, NULL,
573 _clutter_marshal_VOID__VOID,
574 G_TYPE_NONE, 0);
575
576 /**
577 * ClutterAnimation::completed:
578 * @animation: the animation that emitted the signal
579 *
580 * The ::completed signal is emitted once the animation has
581 * been completed.
582 *
583 * The @animation instance is guaranteed to be valid for the entire
584 * duration of the signal emission chain.
585 *
586 * Since: 1.0
587 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
588 */
589 animation_signals[COMPLETED] =
590 g_signal_new (I_("completed"),
591 G_TYPE_FROM_CLASS (klass),
592 G_SIGNAL_RUN_LAST,
593 G_STRUCT_OFFSET (ClutterAnimationClass, completed),
594 NULL, NULL,
595 _clutter_marshal_VOID__VOID,
596 G_TYPE_NONE, 0);
597 }
598
599 static void
600 clutter_animation_init (ClutterAnimation *self)
601 {
602 self->priv = clutter_animation_get_instance_private (self);
603
604 self->priv->properties =
605 g_hash_table_new_full (g_str_hash, g_str_equal,
606 (GDestroyNotify) g_free,
607 (GDestroyNotify) g_object_unref);
608 }
609
610 static inline void
611 clutter_animation_bind_property_internal (ClutterAnimation *animation,
612 const gchar *property_name,
613 GParamSpec *pspec,
614 ClutterInterval *interval)
615 {
616 ClutterAnimationPrivate *priv = animation->priv;
617
618 if (!clutter_interval_validate (interval, pspec))
619 {
620 g_warning ("Cannot bind property '%s': the interval is out "
621 "of bounds",
622 property_name);
623 return;
624 }
625
626 g_hash_table_insert (priv->properties,
627 g_strdup (property_name),
628 g_object_ref_sink (interval));
629 }
630
631 static inline void
632 clutter_animation_update_property_internal (ClutterAnimation *animation,
633 const gchar *property_name,
634 GParamSpec *pspec,
635 ClutterInterval *interval)
636 {
637 ClutterAnimationPrivate *priv = animation->priv;
638
639 if (!clutter_interval_validate (interval, pspec))
640 {
641 g_warning ("Cannot bind property '%s': the interval is out "
642 "of bounds",
643 property_name);
644 return;
645 }
646
647 g_hash_table_replace (priv->properties,
648 g_strdup (property_name),
649 g_object_ref_sink (interval));
650 }
651
652 static GParamSpec *
653 clutter_animation_validate_bind (ClutterAnimation *animation,
654 const char *property_name,
655 GType argtype)
656 {
657 ClutterAnimationPrivate *priv;
658 GParamSpec *pspec;
659 GType pspec_type;
660
661 priv = animation->priv;
662
663 if (G_UNLIKELY (!priv->object))
664 {
665 g_warning ("Cannot bind property '%s': the animation has no "
666 "object set. You need to call clutter_animation_set_object() "
667 "first to be able to bind a property",
668 property_name);
669 return NULL;
670 }
671
672 if (G_UNLIKELY (clutter_animation_has_property (animation, property_name)))
673 {
674 g_warning ("Cannot bind property '%s': the animation already has "
675 "a bound property with the same name",
676 property_name);
677 return NULL;
678 }
679
680 if (CLUTTER_IS_ANIMATABLE (priv->object))
681 {
682 ClutterAnimatable *animatable = CLUTTER_ANIMATABLE (priv->object);
683
684 pspec = clutter_animatable_find_property (animatable, property_name);
685 }
686 else
687 {
688 GObjectClass *klass = G_OBJECT_GET_CLASS (priv->object);
689
690 pspec = g_object_class_find_property (klass, property_name);
691 }
692
693 if (pspec == NULL)
694 {
695 g_warning ("Cannot bind property '%s': objects of type '%s' have "
696 "no such property",
697 property_name,
698 g_type_name (G_OBJECT_TYPE (priv->object)));
699 return NULL;
700 }
701
702 if (!(pspec->flags & G_PARAM_WRITABLE))
703 {
704 g_warning ("Cannot bind property '%s': the property is not writable",
705 property_name);
706 return NULL;
707 }
708
709 pspec_type = G_PARAM_SPEC_VALUE_TYPE (pspec);
710
711 if (g_value_type_transformable (argtype, pspec_type))
712 return pspec;
713 else
714 {
715 g_warning ("Cannot bind property '%s': the interval value of "
716 "type '%s' is not compatible with the property value "
717 "of type '%s'",
718 property_name,
719 g_type_name (argtype),
720 g_type_name (pspec_type));
721 return NULL;
722 }
723 }
724
725 /**
726 * clutter_animation_bind_interval:
727 * @animation: a #ClutterAnimation
728 * @property_name: the property to control
729 * @interval: (transfer full): a #ClutterInterval
730 *
731 * Binds @interval to the @property_name of the #GObject
732 * attached to @animation. The #ClutterAnimation will take
733 * ownership of the passed #ClutterInterval. For more information
734 * about animations, see clutter_actor_animate().
735 *
736 * If you need to update the interval instance use
737 * clutter_animation_update_interval() instead.
738 *
739 * Return value: (transfer none): The animation itself.
740 * Since: 1.0
741 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
742 */
743 ClutterAnimation *
744 clutter_animation_bind_interval (ClutterAnimation *animation,
745 const gchar *property_name,
746 ClutterInterval *interval)
747 {
748 GParamSpec *pspec;
749
750 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
751 g_return_val_if_fail (property_name != NULL, NULL);
752 g_return_val_if_fail (CLUTTER_IS_INTERVAL (interval), NULL);
753
754 pspec = clutter_animation_validate_bind (animation, property_name,
755 clutter_interval_get_value_type (interval));
756 if (pspec == NULL)
757 return NULL;
758
759 clutter_animation_bind_property_internal (animation, property_name,
760 pspec,
761 interval);
762
763 return animation;
764 }
765
766
767 /**
768 * clutter_animation_bind:
769 * @animation: a #ClutterAnimation
770 * @property_name: the property to control
771 * @final: The final value of the property
772 *
773 * Adds a single property with name @property_name to the
774 * animation @animation. For more information about animations,
775 * see clutter_actor_animate().
776 *
777 * This method returns the animation primarily to make chained
778 * calls convenient in language bindings.
779 *
780 * Return value: (transfer none): The animation itself.
781 *
782 * Since: 1.0
783 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
784 */
785 ClutterAnimation *
786 clutter_animation_bind (ClutterAnimation *animation,
787 const gchar *property_name,
788 const GValue *final)
789 {
790 ClutterAnimationPrivate *priv;
791 GParamSpec *pspec;
792 ClutterInterval *interval;
793 GType type;
794 GValue initial = G_VALUE_INIT;
795 GValue real_final = G_VALUE_INIT;
796
797 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
798 g_return_val_if_fail (property_name != NULL, NULL);
799
800 priv = animation->priv;
801
802 type = G_VALUE_TYPE (final);
803 pspec = clutter_animation_validate_bind (animation, property_name, type);
804 if (pspec == NULL)
805 return NULL;
806
807 g_value_init (&real_final, G_PARAM_SPEC_VALUE_TYPE (pspec));
808 if (!g_value_transform (final, &real_final))
809 {
810 g_value_unset (&real_final);
811 g_warning ("Unable to transform the value of type '%s' to a value "
812 "of '%s' compatible with the property '%s'of the object "
813 "of type '%s'",
814 g_type_name (type),
815 g_type_name (G_PARAM_SPEC_VALUE_TYPE (pspec)),
816 property_name,
817 G_OBJECT_TYPE_NAME (priv->object));
818 return NULL;
819 }
820
821 g_value_init (&initial, G_PARAM_SPEC_VALUE_TYPE (pspec));
822
823 if (CLUTTER_IS_ANIMATABLE (priv->object))
824 clutter_animatable_get_initial_state (CLUTTER_ANIMATABLE (priv->object),
825 property_name,
826 &initial);
827 else
828 g_object_get_property (priv->object, property_name, &initial);
829
830 interval = clutter_interval_new_with_values (G_PARAM_SPEC_VALUE_TYPE (pspec),
831 &initial,
832 &real_final);
833
834 g_value_unset (&initial);
835 g_value_unset (&real_final);
836
837 clutter_animation_bind_property_internal (animation, property_name,
838 pspec,
839 interval);
840
841 return animation;
842 }
843
844
845 /**
846 * clutter_animation_unbind_property:
847 * @animation: a #ClutterAnimation
848 * @property_name: name of the property
849 *
850 * Removes @property_name from the list of animated properties.
851 *
852 * Since: 1.0
853 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
854 */
855 void
856 clutter_animation_unbind_property (ClutterAnimation *animation,
857 const gchar *property_name)
858 {
859 ClutterAnimationPrivate *priv;
860
861 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
862 g_return_if_fail (property_name != NULL);
863
864 priv = animation->priv;
865
866 if (!clutter_animation_has_property (animation, property_name))
867 {
868 g_warning ("Cannot unbind property '%s': the animation has "
869 "no bound property with that name",
870 property_name);
871 return;
872 }
873
874 g_hash_table_remove (priv->properties, property_name);
875 }
876
877 /**
878 * clutter_animation_has_property:
879 * @animation: a #ClutterAnimation
880 * @property_name: name of the property
881 *
882 * Checks whether @animation is controlling @property_name.
883 *
884 * Return value: %TRUE if the property is animated by the
885 * #ClutterAnimation, %FALSE otherwise
886 *
887 * Since: 1.0
888 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
889 */
890 gboolean
891 clutter_animation_has_property (ClutterAnimation *animation,
892 const gchar *property_name)
893 {
894 ClutterAnimationPrivate *priv;
895
896 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), FALSE);
897 g_return_val_if_fail (property_name != NULL, FALSE);
898
899 priv = animation->priv;
900
901 return g_hash_table_lookup (priv->properties, property_name) != NULL;
902 }
903
904 /**
905 * clutter_animation_update_interval:
906 * @animation: a #ClutterAnimation
907 * @property_name: name of the property
908 * @interval: a #ClutterInterval
909 *
910 * Changes the @interval for @property_name. The #ClutterAnimation
911 * will take ownership of the passed #ClutterInterval.
912 *
913 * Since: 1.0
914 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
915 */
916 void
917 clutter_animation_update_interval (ClutterAnimation *animation,
918 const gchar *property_name,
919 ClutterInterval *interval)
920 {
921 ClutterAnimationPrivate *priv;
922 GParamSpec *pspec;
923 GType pspec_type, int_type;
924
925 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
926 g_return_if_fail (property_name != NULL);
927 g_return_if_fail (CLUTTER_IS_INTERVAL (interval));
928
929 priv = animation->priv;
930
931 if (!clutter_animation_has_property (animation, property_name))
932 {
933 g_warning ("Cannot update property '%s': the animation has "
934 "no bound property with that name",
935 property_name);
936 return;
937 }
938
939 if (CLUTTER_IS_ANIMATABLE (priv->object))
940 {
941 ClutterAnimatable *animatable = CLUTTER_ANIMATABLE (priv->object);
942
943 pspec = clutter_animatable_find_property (animatable, property_name);
944 }
945 else
946 {
947 GObjectClass *klass = G_OBJECT_GET_CLASS (priv->object);
948
949 pspec = g_object_class_find_property (klass, property_name);
950 }
951
952 if (pspec == NULL)
953 {
954 g_warning ("Cannot update property '%s': objects of type '%s' have "
955 "no such property",
956 property_name,
957 g_type_name (G_OBJECT_TYPE (priv->object)));
958 return;
959 }
960
961 pspec_type = G_PARAM_SPEC_VALUE_TYPE (pspec);
962 int_type = clutter_interval_get_value_type (interval);
963
964 if (!g_value_type_compatible (int_type, pspec_type) ||
965 !g_value_type_transformable (int_type, pspec_type))
966 {
967 g_warning ("Cannot update property '%s': the interval value of "
968 "type '%s' is not compatible with the property value "
969 "of type '%s'",
970 property_name,
971 g_type_name (int_type),
972 g_type_name (pspec_type));
973 return;
974 }
975
976 clutter_animation_update_property_internal (animation, property_name,
977 pspec,
978 interval);
979 }
980
981 /**
982 * clutter_animation_update:
983 * @animation: a #ClutterAnimation
984 * @property_name: name of the property
985 * @final: The final value of the property
986 *
987 * Updates the @final value of the interval for @property_name
988 *
989 * Return value: (transfer none): The animation itself.
990 *
991 * Since: 1.0
992 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
993 */
994 ClutterAnimation *
995 clutter_animation_update (ClutterAnimation *animation,
996 const gchar *property_name,
997 const GValue *final)
998 {
999 ClutterInterval *interval;
1000 GType int_type;
1001
1002 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
1003 g_return_val_if_fail (property_name != NULL, NULL);
1004 g_return_val_if_fail (final != NULL, NULL);
1005 g_return_val_if_fail (G_VALUE_TYPE (final) != G_TYPE_INVALID, NULL);
1006
1007 interval = clutter_animation_get_interval (animation, property_name);
1008 if (interval == NULL)
1009 {
1010 g_warning ("Cannot update property '%s': the animation has "
1011 "no bound property with that name",
1012 property_name);
1013 return NULL;
1014 }
1015
1016 int_type = clutter_interval_get_value_type (interval);
1017
1018 if (!g_value_type_compatible (G_VALUE_TYPE (final), int_type) ||
1019 !g_value_type_transformable (G_VALUE_TYPE (final), int_type))
1020 {
1021 g_warning ("Cannot update property '%s': the interval value of "
1022 "type '%s' is not compatible with the property value "
1023 "of type '%s'",
1024 property_name,
1025 g_type_name (int_type),
1026 g_type_name (G_VALUE_TYPE (final)));
1027 return NULL;
1028 }
1029
1030 clutter_interval_set_final_value (interval, final);
1031
1032 return animation;
1033 }
1034
1035 /**
1036 * clutter_animation_get_interval:
1037 * @animation: a #ClutterAnimation
1038 * @property_name: name of the property
1039 *
1040 * Retrieves the #ClutterInterval associated to @property_name
1041 * inside @animation.
1042 *
1043 * Return value: (transfer none): a #ClutterInterval or %NULL if no
1044 * property with the same name was found. The returned interval is
1045 * owned by the #ClutterAnimation and should not be unreferenced
1046 *
1047 * Since: 1.0
1048 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1049 */
1050 ClutterInterval *
1051 clutter_animation_get_interval (ClutterAnimation *animation,
1052 const gchar *property_name)
1053 {
1054 ClutterAnimationPrivate *priv;
1055
1056 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
1057 g_return_val_if_fail (property_name != NULL, NULL);
1058
1059 priv = animation->priv;
1060
1061 return g_hash_table_lookup (priv->properties, property_name);
1062 }
1063
1064 static void
1065 on_timeline_started (ClutterTimeline *timeline,
1066 ClutterAnimation *animation)
1067 {
1068 g_signal_emit (animation, animation_signals[STARTED], 0);
1069 }
1070
1071 static void
1072 on_timeline_completed (ClutterTimeline *timeline,
1073 ClutterAnimation *animation)
1074 {
1075 CLUTTER_NOTE (ANIMATION, "Timeline [%p] complete", timeline);
1076
1077 if (!clutter_animation_get_loop (animation))
1078 g_signal_emit (animation, animation_signals[COMPLETED], 0);
1079 }
1080
1081 static void
1082 on_timeline_frame (ClutterTimeline *timeline,
1083 gint elapsed,
1084 ClutterAnimation *animation)
1085 {
1086 ClutterAnimationPrivate *priv;
1087 GList *properties, *p;
1088 gdouble alpha_value;
1089 gboolean is_animatable = FALSE;
1090 ClutterAnimatable *animatable = NULL;
1091
1092 /* make sure the animation survives the notification */
1093 g_object_ref (animation);
1094
1095 priv = animation->priv;
1096
1097 if (priv->alpha != NULL)
1098 alpha_value = clutter_alpha_get_alpha (priv->alpha);
1099 else
1100 alpha_value = clutter_timeline_get_progress (priv->timeline);
1101
1102 if (CLUTTER_IS_ANIMATABLE (priv->object))
1103 {
1104 animatable = CLUTTER_ANIMATABLE (priv->object);
1105 is_animatable = TRUE;
1106 }
1107
1108 g_object_freeze_notify (priv->object);
1109
1110 properties = g_hash_table_get_keys (priv->properties);
1111 for (p = properties; p != NULL; p = p->next)
1112 {
1113 const gchar *p_name = p->data;
1114 ClutterInterval *interval;
1115 GValue value = G_VALUE_INIT;
1116 gboolean apply;
1117
1118 interval = g_hash_table_lookup (priv->properties, p_name);
1119 g_assert (CLUTTER_IS_INTERVAL (interval));
1120
1121 g_value_init (&value, clutter_interval_get_value_type (interval));
1122
1123 if (is_animatable)
1124 {
1125 apply = clutter_animatable_interpolate_value (animatable, p_name,
1126 interval,
1127 alpha_value,
1128 &value);
1129 }
1130 else
1131 {
1132 apply = clutter_interval_compute_value (interval,
1133 alpha_value,
1134 &value);
1135 }
1136
1137 if (apply)
1138 {
1139 if (is_animatable)
1140 clutter_animatable_set_final_state (animatable, p_name, &value);
1141 else
1142 g_object_set_property (priv->object, p_name, &value);
1143 }
1144
1145 g_value_unset (&value);
1146 }
1147
1148 g_list_free (properties);
1149
1150 g_object_thaw_notify (priv->object);
1151
1152 g_object_unref (animation);
1153 }
1154
1155 static ClutterTimeline *
1156 clutter_animation_get_timeline_internal (ClutterAnimation *animation)
1157 {
1158 ClutterAnimationPrivate *priv = animation->priv;
1159 ClutterTimeline *timeline;
1160
1161 if (priv->timeline != NULL)
1162 return priv->timeline;
1163
1164 if (priv->alpha != NULL)
1165 {
1166 timeline = clutter_alpha_get_timeline (priv->alpha);
1167 if (timeline != NULL)
1168 return timeline;
1169 }
1170
1171 timeline = g_object_new (CLUTTER_TYPE_TIMELINE, NULL);
1172
1173 priv->timeline_started_id =
1174 g_signal_connect (timeline, "started",
1175 G_CALLBACK (on_timeline_started),
1176 animation);
1177
1178 priv->timeline_completed_id =
1179 g_signal_connect (timeline, "completed",
1180 G_CALLBACK (on_timeline_completed),
1181 animation);
1182
1183 priv->timeline_frame_id =
1184 g_signal_connect (timeline, "new-frame",
1185 G_CALLBACK (on_timeline_frame),
1186 animation);
1187
1188 if (priv->alpha != NULL)
1189 {
1190 clutter_alpha_set_timeline (priv->alpha, timeline);
1191
1192 /* the alpha owns the timeline now */
1193 g_object_unref (timeline);
1194 }
1195
1196 priv->timeline = timeline;
1197
1198 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_TIMELINE]);
1199
1200 return priv->timeline;
1201 }
1202
1203 static void
1204 clutter_animation_set_alpha_internal (ClutterAnimation *animation,
1205 ClutterAlpha *alpha)
1206 {
1207 ClutterAnimationPrivate *priv;
1208 ClutterTimeline *timeline;
1209
1210 priv = animation->priv;
1211
1212 if (priv->alpha == alpha)
1213 return;
1214
1215 g_object_freeze_notify (G_OBJECT (animation));
1216
1217 if (priv->alpha != NULL)
1218 timeline = clutter_alpha_get_timeline (priv->alpha);
1219 else
1220 timeline = NULL;
1221
1222 /* disconnect the old timeline first */
1223 if (timeline != NULL && priv->timeline_started_id != 0)
1224 {
1225 g_signal_handler_disconnect (timeline, priv->timeline_started_id);
1226 priv->timeline_started_id = 0;
1227 }
1228
1229 if (timeline != NULL && priv->timeline_completed_id != 0)
1230 {
1231 g_signal_handler_disconnect (timeline, priv->timeline_completed_id);
1232 priv->timeline_completed_id = 0;
1233 }
1234
1235 /* then we need to disconnect the signal handler from the old alpha */
1236 if (timeline != NULL && priv->timeline_frame_id != 0)
1237 {
1238 g_signal_handler_disconnect (timeline, priv->timeline_frame_id);
1239 priv->timeline_frame_id = 0;
1240 }
1241
1242 if (priv->alpha != NULL)
1243 {
1244 /* this will take care of any reference we hold on the timeline */
1245 g_object_unref (priv->alpha);
1246 priv->alpha = NULL;
1247 }
1248
1249 if (alpha == NULL)
1250 goto out;
1251
1252 priv->alpha = g_object_ref_sink (alpha);
1253
1254 /* if the alpha has a timeline then we use it, otherwise we create one */
1255 timeline = clutter_alpha_get_timeline (priv->alpha);
1256 if (timeline != NULL)
1257 {
1258 priv->timeline_started_id =
1259 g_signal_connect (timeline, "started",
1260 G_CALLBACK (on_timeline_started),
1261 animation);
1262 priv->timeline_completed_id =
1263 g_signal_connect (timeline, "completed",
1264 G_CALLBACK (on_timeline_completed),
1265 animation);
1266 priv->timeline_frame_id =
1267 g_signal_connect (timeline, "new-frame",
1268 G_CALLBACK (on_timeline_frame),
1269 animation);
1270 }
1271 else
1272 {
1273 /* FIXME - add a create_timeline_internal() because this does
1274 * not look very good
1275 */
1276 (void) clutter_animation_get_timeline_internal (animation);
1277 }
1278
1279 out:
1280 /* emit all relevant notifications */
1281 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_MODE]);
1282 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_DURATION]);
1283 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_LOOP]);
1284 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_ALPHA]);
1285 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_TIMELINE]);
1286
1287 g_object_thaw_notify (G_OBJECT (animation));
1288 }
1289
1290 /**
1291 * clutter_animation_new:
1292 *
1293 * Creates a new #ClutterAnimation instance. You should set the
1294 * #GObject to be animated using clutter_animation_set_object(),
1295 * set the duration with clutter_animation_set_duration() and the
1296 * easing mode using clutter_animation_set_mode().
1297 *
1298 * Use clutter_animation_bind() or clutter_animation_bind_interval()
1299 * to define the properties to be animated. The interval and the
1300 * animated properties can be updated at runtime.
1301 *
1302 * The clutter_actor_animate() and relative family of functions provide
1303 * an easy way to animate a #ClutterActor and automatically manage the
1304 * lifetime of a #ClutterAnimation instance, so you should consider using
1305 * those functions instead of manually creating an animation.
1306 *
1307 * Return value: the newly created #ClutterAnimation. Use g_object_unref()
1308 * to release the associated resources
1309 *
1310 * Since: 1.0
1311 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1312 */
1313 ClutterAnimation *
1314 clutter_animation_new (void)
1315 {
1316 return g_object_new (CLUTTER_TYPE_ANIMATION, NULL);
1317 }
1318
1319 /**
1320 * clutter_animation_set_object:
1321 * @animation: a #ClutterAnimation
1322 * @object: a #GObject
1323 *
1324 * Attaches @animation to @object. The #ClutterAnimation will take a
1325 * reference on @object.
1326 *
1327 * Since: 1.0
1328 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1329 */
1330 void
1331 clutter_animation_set_object (ClutterAnimation *animation,
1332 GObject *object)
1333 {
1334 ClutterAnimationPrivate *priv;
1335
1336 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1337 g_return_if_fail (object == NULL || G_IS_OBJECT (object));
1338
1339 priv = animation->priv;
1340
1341 if (priv->object != NULL)
1342 {
1343 g_object_set_qdata (priv->object, quark_object_animation, NULL);
1344
1345 g_object_unref (priv->object);
1346 priv->object = NULL;
1347 }
1348
1349 if (object != NULL)
1350 priv->object = g_object_ref (object);
1351
1352 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_OBJECT]);
1353 }
1354
1355 /**
1356 * clutter_animation_get_object:
1357 * @animation: a #ClutterAnimation
1358 *
1359 * Retrieves the #GObject attached to @animation.
1360 *
1361 * Return value: (transfer none): a #GObject
1362 *
1363 * Since: 1.0
1364 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1365 */
1366 GObject *
1367 clutter_animation_get_object (ClutterAnimation *animation)
1368 {
1369 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
1370
1371 return animation->priv->object;
1372 }
1373
1374 /**
1375 * clutter_animation_set_mode:
1376 * @animation: a #ClutterAnimation
1377 * @mode: an animation mode logical id
1378 *
1379 * Sets the animation @mode of @animation. The animation @mode is
1380 * a logical id, either coming from the #ClutterAnimationMode enumeration
1381 * or the return value of clutter_alpha_register_func().
1382 *
1383 * This function will also set #ClutterAnimation:alpha if needed.
1384 *
1385 * Since: 1.0
1386 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1387 */
1388 void
1389 clutter_animation_set_mode (ClutterAnimation *animation,
1390 gulong mode)
1391 {
1392 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1393
1394 g_object_freeze_notify (G_OBJECT (animation));
1395
1396 if (animation->priv->alpha != NULL || mode > CLUTTER_ANIMATION_LAST)
1397 {
1398 ClutterAlpha *alpha;
1399
1400 if (animation->priv->alpha == NULL)
1401 alpha = clutter_animation_get_alpha_internal (animation);
1402 else
1403 alpha = animation->priv->alpha;
1404
1405 clutter_alpha_set_mode (alpha, mode);
1406 }
1407 else
1408 {
1409 ClutterTimeline *timeline;
1410
1411 timeline = clutter_animation_get_timeline_internal (animation);
1412
1413 clutter_timeline_set_progress_mode (timeline, mode);
1414 }
1415
1416 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_MODE]);
1417
1418 g_object_thaw_notify (G_OBJECT (animation));
1419 }
1420
1421 /**
1422 * clutter_animation_get_mode:
1423 * @animation: a #ClutterAnimation
1424 *
1425 * Retrieves the animation mode of @animation, as set by
1426 * clutter_animation_set_mode().
1427 *
1428 * Return value: the mode for the animation
1429 *
1430 * Since: 1.0
1431 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1432 */
1433 gulong
1434 clutter_animation_get_mode (ClutterAnimation *animation)
1435 {
1436 ClutterTimeline *timeline;
1437
1438 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), CLUTTER_LINEAR);
1439
1440 if (animation->priv->alpha != NULL)
1441 return clutter_alpha_get_mode (animation->priv->alpha);
1442
1443 timeline = clutter_animation_get_timeline_internal (animation);
1444
1445 return clutter_timeline_get_progress_mode (timeline);
1446 }
1447
1448 /**
1449 * clutter_animation_set_duration:
1450 * @animation: a #ClutterAnimation
1451 * @msecs: the duration in milliseconds
1452 *
1453 * Sets the duration of @animation in milliseconds.
1454 *
1455 * This function will set #ClutterAnimation:alpha and
1456 * #ClutterAnimation:timeline if needed.
1457 *
1458 * Since: 1.0
1459 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1460 */
1461 void
1462 clutter_animation_set_duration (ClutterAnimation *animation,
1463 guint msecs)
1464 {
1465 ClutterTimeline *timeline;
1466
1467 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1468
1469 g_object_freeze_notify (G_OBJECT (animation));
1470
1471 timeline = clutter_animation_get_timeline_internal (animation);
1472 clutter_timeline_set_duration (timeline, msecs);
1473 clutter_timeline_rewind (timeline);
1474
1475 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_DURATION]);
1476
1477 g_object_thaw_notify (G_OBJECT (animation));
1478 }
1479
1480 /**
1481 * clutter_animation_set_loop:
1482 * @animation: a #ClutterAnimation
1483 * @loop: %TRUE if the animation should loop
1484 *
1485 * Sets whether @animation should loop over itself once finished.
1486 *
1487 * A looping #ClutterAnimation will not emit the #ClutterAnimation::completed
1488 * signal when finished.
1489 *
1490 * This function will set #ClutterAnimation:alpha and
1491 * #ClutterAnimation:timeline if needed.
1492 *
1493 * Since: 1.0
1494 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1495 */
1496 void
1497 clutter_animation_set_loop (ClutterAnimation *animation,
1498 gboolean loop)
1499 {
1500 ClutterTimeline *timeline;
1501
1502 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1503
1504 g_object_freeze_notify (G_OBJECT (animation));
1505
1506 timeline = clutter_animation_get_timeline_internal (animation);
1507 clutter_timeline_set_repeat_count (timeline, loop ? -1 : 0);
1508
1509 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_LOOP]);
1510
1511 g_object_thaw_notify (G_OBJECT (animation));
1512 }
1513
1514 /**
1515 * clutter_animation_get_loop:
1516 * @animation: a #ClutterAnimation
1517 *
1518 * Retrieves whether @animation is looping.
1519 *
1520 * Return value: %TRUE if the animation is looping
1521 *
1522 * Since: 1.0
1523 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1524 */
1525 gboolean
1526 clutter_animation_get_loop (ClutterAnimation *animation)
1527 {
1528 ClutterTimeline *timeline;
1529
1530 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), FALSE);
1531
1532 timeline = clutter_animation_get_timeline_internal (animation);
1533
1534 return clutter_timeline_get_repeat_count (timeline) != 0;
1535 }
1536
1537 /**
1538 * clutter_animation_get_duration:
1539 * @animation: a #ClutterAnimation
1540 *
1541 * Retrieves the duration of @animation, in milliseconds.
1542 *
1543 * Return value: the duration of the animation
1544 *
1545 * Since: 1.0
1546 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1547 */
1548 guint
1549 clutter_animation_get_duration (ClutterAnimation *animation)
1550 {
1551 ClutterTimeline *timeline;
1552
1553 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), 0);
1554
1555 timeline = clutter_animation_get_timeline_internal (animation);
1556
1557 return clutter_timeline_get_duration (timeline);
1558 }
1559
1560 /**
1561 * clutter_animation_set_timeline:
1562 * @animation: a #ClutterAnimation
1563 * @timeline: (allow-none): a #ClutterTimeline, or %NULL to unset the
1564 * current #ClutterTimeline
1565 *
1566 * Sets the #ClutterTimeline used by @animation.
1567 *
1568 * This function will take a reference on the passed @timeline.
1569 *
1570 * Since: 1.0
1571 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1572 */
1573 void
1574 clutter_animation_set_timeline (ClutterAnimation *animation,
1575 ClutterTimeline *timeline)
1576 {
1577 ClutterAnimationPrivate *priv;
1578 ClutterTimeline *cur_timeline;
1579
1580 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1581 g_return_if_fail (timeline == NULL || CLUTTER_IS_TIMELINE (timeline));
1582
1583 priv = animation->priv;
1584
1585 if (priv->alpha != NULL)
1586 cur_timeline = clutter_alpha_get_timeline (priv->alpha);
1587 else
1588 cur_timeline = priv->timeline;
1589
1590 if (cur_timeline == timeline)
1591 return;
1592
1593 g_object_freeze_notify (G_OBJECT (animation));
1594
1595 if (cur_timeline != NULL && priv->timeline_started_id != 0)
1596 g_signal_handler_disconnect (cur_timeline, priv->timeline_started_id);
1597
1598 if (cur_timeline != NULL && priv->timeline_completed_id != 0)
1599 g_signal_handler_disconnect (cur_timeline, priv->timeline_completed_id);
1600
1601 if (cur_timeline != NULL && priv->timeline_frame_id != 0)
1602 g_signal_handler_disconnect (cur_timeline, priv->timeline_frame_id);
1603
1604 priv->timeline_started_id = 0;
1605 priv->timeline_completed_id = 0;
1606 priv->timeline_frame_id = 0;
1607
1608 /* Release previously set timeline if any */
1609 g_clear_object (&priv->timeline);
1610
1611 if (priv->alpha != NULL)
1612 clutter_alpha_set_timeline (priv->alpha, timeline);
1613 else
1614 {
1615 /* Hold a reference to the timeline if it's not reffed by the priv->alpha */
1616 priv->timeline = timeline;
1617
1618 if (priv->timeline)
1619 g_object_ref (priv->timeline);
1620 }
1621
1622 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_TIMELINE]);
1623 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_DURATION]);
1624 g_object_notify_by_pspec (G_OBJECT (animation), obj_props[PROP_LOOP]);
1625
1626 if (timeline != NULL)
1627 {
1628 priv->timeline_started_id =
1629 g_signal_connect (timeline, "started",
1630 G_CALLBACK (on_timeline_started),
1631 animation);
1632 priv->timeline_completed_id =
1633 g_signal_connect (timeline, "completed",
1634 G_CALLBACK (on_timeline_completed),
1635 animation);
1636 priv->timeline_frame_id =
1637 g_signal_connect (timeline, "new-frame",
1638 G_CALLBACK (on_timeline_frame),
1639 animation);
1640 }
1641
1642 g_object_thaw_notify (G_OBJECT (animation));
1643 }
1644
1645 /**
1646 * clutter_animation_get_timeline:
1647 * @animation: a #ClutterAnimation
1648 *
1649 * Retrieves the #ClutterTimeline used by @animation
1650 *
1651 * Return value: (transfer none): the timeline used by the animation
1652 *
1653 * Since: 1.0
1654 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1655 */
1656 ClutterTimeline *
1657 clutter_animation_get_timeline (ClutterAnimation *animation)
1658 {
1659 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
1660
1661 return clutter_animation_get_timeline_internal (animation);
1662 }
1663
1664 /**
1665 * clutter_animation_set_alpha:
1666 * @animation: a #ClutterAnimation
1667 * @alpha: a #ClutterAlpha, or %NULL to unset the current #ClutterAlpha
1668 *
1669 * Sets @alpha as the #ClutterAlpha used by @animation.
1670 *
1671 * If @alpha is not %NULL, the #ClutterAnimation will take ownership
1672 * of the #ClutterAlpha instance.
1673 *
1674 * Since: 1.0
1675 *
1676 * Deprecated: 1.10: Use clutter_animation_get_timeline() and
1677 * clutter_timeline_set_progress_mode() instead.
1678 */
1679 void
1680 clutter_animation_set_alpha (ClutterAnimation *animation,
1681 ClutterAlpha *alpha)
1682 {
1683 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1684 g_return_if_fail (alpha == NULL || CLUTTER_IS_ALPHA (alpha));
1685
1686 clutter_animation_set_alpha_internal (animation, alpha);
1687 }
1688
1689 /**
1690 * clutter_animation_get_alpha:
1691 * @animation: a #ClutterAnimation
1692 *
1693 * Retrieves the #ClutterAlpha used by @animation.
1694 *
1695 * Return value: (transfer none): the alpha object used by the animation
1696 *
1697 * Since: 1.0
1698 *
1699 * Deprecated: 1.10: Use clutter_animation_get_timeline() and
1700 * clutter_timeline_get_progress_mode() instead.
1701 */
1702 ClutterAlpha *
1703 clutter_animation_get_alpha (ClutterAnimation *animation)
1704 {
1705 g_return_val_if_fail (CLUTTER_IS_ANIMATION (animation), NULL);
1706
1707 return clutter_animation_get_alpha_internal (animation);
1708 }
1709
1710 /**
1711 * clutter_animation_completed:
1712 * @animation: a #ClutterAnimation
1713 *
1714 * Emits the ::completed signal on @animation
1715 *
1716 * When using this function with a #ClutterAnimation created
1717 * by the clutter_actor_animate() family of functions, @animation
1718 * will be unreferenced and it will not be valid anymore,
1719 * unless g_object_ref() was called before calling this function
1720 * or unless a reference was taken inside a handler for the
1721 * #ClutterAnimation::completed signal
1722 *
1723 * Since: 1.0
1724 * Deprecated: 1.12: Use #ClutterPropertyTransition instead
1725 */
1726 void
1727 clutter_animation_completed (ClutterAnimation *animation)
1728 {
1729 g_return_if_fail (CLUTTER_IS_ANIMATION (animation));
1730
1731 g_signal_emit (animation, animation_signals[COMPLETED], 0);
1732 }
1733
1734 /*
1735 * starts the timeline
1736 */
1737 static void
1738 clutter_animation_start (ClutterAnimation *animation)
1739 {
1740 ClutterTimeline *timeline;
1741
1742 timeline = clutter_animation_get_timeline_internal (animation);
1743
1744 if (G_LIKELY (timeline != NULL))
1745 clutter_timeline_start (timeline);
1746 else
1747 {
1748 /* sanity check */
1749 g_warning (G_STRLOC ": no timeline found, unable to start the animation");
1750 }
1751 }
1752
1753 static void
1754 clutter_animation_setup_property (ClutterAnimation *animation,
1755 const gchar *property_name,
1756 const GValue *value,
1757 GParamSpec *pspec,
1758 gboolean is_fixed)
1759 {
1760 ClutterAnimationPrivate *priv = animation->priv;
1761 GValue real_value = G_VALUE_INIT;
1762
1763 if (pspec->flags & G_PARAM_CONSTRUCT_ONLY)
1764 {
1765 g_warning ("Cannot bind property '%s': the property is "
1766 "construct-only",
1767 property_name);
1768 return;
1769 }
1770
1771 if (!(pspec->flags & G_PARAM_WRITABLE))
1772 {
1773 g_warning ("Cannot bind property '%s': the property is "
1774 "not writable",
1775 property_name);
1776 return;
1777 }
1778
1779 /* initialize the real value that will be used to store the
1780 * final state of the animation
1781 */
1782 g_value_init (&real_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
1783
1784 /* if it's not the same type of the GParamSpec value, try to
1785 * convert it using the GValue transformation API, otherwise
1786 * just copy it
1787 */
1788 if (!g_type_is_a (G_VALUE_TYPE (value), G_VALUE_TYPE (&real_value)))
1789 {
1790 /* are these two types compatible (can be directly copied)? */
1791 if (g_value_type_compatible (G_VALUE_TYPE (value),
1792 G_VALUE_TYPE (&real_value)))
1793 {
1794 g_value_copy (value, &real_value);
1795 goto done;
1796 }
1797
1798 /* are these two type transformable? */
1799 if (g_value_type_transformable (G_VALUE_TYPE (value),
1800 G_VALUE_TYPE (&real_value)))
1801 {
1802 if (g_value_transform (value, &real_value))
1803 goto done;
1804 }
1805
1806 /* if not compatible and not transformable then we can't do much */
1807 g_warning ("%s: Unable to convert from %s to %s for "
1808 "the property '%s' of object %s",
1809 G_STRLOC,
1810 g_type_name (G_VALUE_TYPE (value)),
1811 g_type_name (G_VALUE_TYPE (&real_value)),
1812 property_name,
1813 G_OBJECT_TYPE_NAME (priv->object));
1814 g_value_unset (&real_value);
1815 return;
1816 }
1817 else
1818 g_value_copy (value, &real_value);
1819
1820 done:
1821 /* create an interval and bind it to the property, in case
1822 * it's not a fixed property, otherwise just set it
1823 */
1824 if (G_LIKELY (!is_fixed))
1825 {
1826 ClutterInterval *interval;
1827 GValue cur_value = G_VALUE_INIT;
1828
1829 g_value_init (&cur_value, G_PARAM_SPEC_VALUE_TYPE (pspec));
1830
1831 if (CLUTTER_IS_ANIMATABLE (priv->object))
1832 clutter_animatable_get_initial_state (CLUTTER_ANIMATABLE (priv->object),
1833 property_name,
1834 &cur_value);
1835 else
1836 g_object_get_property (priv->object, property_name, &cur_value);
1837
1838 interval =
1839 clutter_interval_new_with_values (G_PARAM_SPEC_VALUE_TYPE (pspec),
1840 &cur_value,
1841 &real_value);
1842
1843 if (!clutter_animation_has_property (animation, property_name))
1844 clutter_animation_bind_property_internal (animation, property_name,
1845 pspec,
1846 interval);
1847 else
1848 clutter_animation_update_property_internal (animation, property_name,
1849 pspec,
1850 interval);
1851
1852 g_value_unset (&cur_value);
1853 }
1854 else
1855 {
1856 if (CLUTTER_IS_ANIMATABLE (priv->object))
1857 clutter_animatable_set_final_state (CLUTTER_ANIMATABLE (priv->object),
1858 property_name,
1859 &real_value);
1860 else
1861 g_object_set_property (priv->object, property_name, &real_value);
1862 }
1863
1864 g_value_unset (&real_value);
1865 }
1866
1867 static void
1868 clutter_animation_setupv (ClutterAnimation *animation,
1869 gint n_properties,
1870 const gchar * const properties[],
1871 const GValue *values)
1872 {
1873 ClutterAnimationPrivate *priv = animation->priv;
1874 ClutterAnimatable *animatable = NULL;
1875 GObjectClass *klass = NULL;
1876 gint i;
1877
1878 if (CLUTTER_IS_ANIMATABLE (priv->object))
1879 animatable = CLUTTER_ANIMATABLE (priv->object);
1880 else
1881 klass = G_OBJECT_GET_CLASS (priv->object);
1882
1883 for (i = 0; i < n_properties; i++)
1884 {
1885 const gchar *property_name = properties[i];
1886 GParamSpec *pspec;
1887 gboolean is_fixed = FALSE;
1888
1889 if (g_str_has_prefix (property_name, "fixed::"))
1890 {
1891 property_name += 7; /* strlen("fixed::") */
1892 is_fixed = TRUE;
1893 }
1894
1895 if (animatable != NULL)
1896 pspec = clutter_animatable_find_property (animatable, property_name);
1897 else
1898 pspec = g_object_class_find_property (klass, property_name);
1899
1900 if (pspec == NULL)
1901 {
1902 g_warning ("Cannot bind property '%s': objects of type '%s' do "
1903 "not have this property",
1904 property_name,
1905 g_type_name (G_OBJECT_TYPE (priv->object)));
1906 break;
1907 }
1908
1909 clutter_animation_setup_property (animation, property_name,
1910 &values[i],
1911 pspec,
1912 is_fixed);
1913 }
1914 }
1915
1916 static const struct
1917 {
1918 const gchar *name;
1919 GConnectFlags flags;
1920 } signal_prefixes[] =
1921 {
1922 { "::", 0 },
1923 { "-swapped::", G_CONNECT_SWAPPED },
1924 { "-after::", G_CONNECT_AFTER },
1925 { "-swapped-after::", G_CONNECT_SWAPPED | G_CONNECT_AFTER }
1926 };
1927
1928 static gboolean
1929 clutter_animation_has_signal_prefix (const gchar *property_name,
1930 GConnectFlags *flags,
1931 int *offset)
1932 {
1933 int i;
1934
1935 if (!g_str_has_prefix (property_name, "signal"))
1936 return FALSE;
1937
1938 for (i = 0; i < G_N_ELEMENTS (signal_prefixes); i++)
1939 if (g_str_has_prefix (property_name + 6, signal_prefixes[i].name))
1940 {
1941 *offset = strlen (signal_prefixes[i].name) + 6;
1942 *flags = signal_prefixes[i].flags;
1943 return TRUE;
1944 }
1945
1946 return FALSE;
1947 }
1948
1949 static void
1950 clutter_animation_setup_valist (ClutterAnimation *animation,
1951 const gchar *first_property_name,
1952 va_list var_args)
1953 {
1954 ClutterAnimationPrivate *priv = animation->priv;
1955 ClutterAnimatable *animatable = NULL;
1956 GObjectClass *klass = NULL;
1957 const gchar *property_name;
1958
1959 if (CLUTTER_IS_ANIMATABLE (priv->object))
1960 animatable = CLUTTER_ANIMATABLE (priv->object);
1961 else
1962 klass = G_OBJECT_GET_CLASS (priv->object);
1963
1964 property_name = first_property_name;
1965 while (property_name != NULL)
1966 {
1967 GParamSpec *pspec;
1968 GValue final = G_VALUE_INIT;
1969 gchar *error = NULL;
1970 gboolean is_fixed = FALSE;
1971 GConnectFlags flags;
1972 int offset;
1973
1974 if (clutter_animation_has_signal_prefix (property_name,
1975 &flags,
1976 &offset))
1977 {
1978 const gchar *signal_name = property_name + offset;
1979 GCallback callback = va_arg (var_args, GCallback);
1980 gpointer userdata = va_arg (var_args, gpointer);
1981
1982 g_signal_connect_data (animation, signal_name,
1983 callback, userdata,
1984 NULL, flags);
1985 }
1986 else
1987 {
1988 if (g_str_has_prefix (property_name, "fixed::"))
1989 {
1990 property_name += 7; /* strlen("fixed::") */
1991 is_fixed = TRUE;
1992 }
1993
1994 if (animatable != NULL)
1995 pspec = clutter_animatable_find_property (animatable,
1996 property_name);
1997 else
1998 pspec = g_object_class_find_property (klass, property_name);
1999
2000 if (pspec == NULL)
2001 {
2002 g_warning ("Cannot bind property '%s': objects of type '%s' do "
2003 "not have this property",
2004 property_name,
2005 g_type_name (G_OBJECT_TYPE (priv->object)));
2006 break;
2007 }
2008
2009 G_VALUE_COLLECT_INIT (&final, G_PARAM_SPEC_VALUE_TYPE (pspec),
2010 var_args, 0,
2011 &error);
2012
2013 if (error)
2014 {
2015 g_warning ("%s: %s", G_STRLOC, error);
2016 g_free (error);
2017 break;
2018 }
2019
2020 clutter_animation_setup_property (animation, property_name,
2021 &final,
2022 pspec,
2023 is_fixed);
2024
2025
2026 g_value_unset (&final);
2027 }
2028
2029 property_name = va_arg (var_args, gchar*);
2030 }
2031 }
2032
2033 static ClutterAnimation *
2034 animation_create_for_actor (ClutterActor *actor)
2035 {
2036 ClutterAnimation *animation;
2037 GObject *object = G_OBJECT (actor);
2038
2039 animation = g_object_get_qdata (object, quark_object_animation);
2040 if (animation == NULL)
2041 {
2042 animation = clutter_animation_new ();
2043 clutter_animation_set_object (animation, object);
2044 g_object_set_qdata (object, quark_object_animation, animation);
2045
2046 /* use the ::destroy signal to get a notification
2047 * that the actor went away mid-animation
2048 */
2049 g_signal_connect (object, "destroy",
2050 G_CALLBACK (on_actor_destroy),
2051 animation);
2052
2053 CLUTTER_NOTE (ANIMATION,
2054 "Created new Animation [%p] for actor [%p]",
2055 animation,
2056 actor);
2057 }
2058 else
2059 {
2060 CLUTTER_NOTE (ANIMATION,
2061 "Reusing Animation [%p] for actor [%p]",
2062 animation,
2063 actor);
2064 }
2065
2066 return animation;
2067 }
2068
2069 /**
2070 * clutter_actor_animate_with_alpha:
2071 * @actor: a #ClutterActor
2072 * @alpha: a #ClutterAlpha
2073 * @first_property_name: the name of a property
2074 * @...: a %NULL terminated list of property names and
2075 * property values
2076 *
2077 * Animates the given list of properties of @actor between the current
2078 * value for each property and a new final value. The animation has a
2079 * definite behaviour given by the passed @alpha.
2080 *
2081 * See clutter_actor_animate() for further details.
2082 *
2083 * This function is useful if you want to use an existing #ClutterAlpha
2084 * to animate @actor.
2085 *
2086 * Return value: (transfer none): a #ClutterAnimation object. The object is owned by the
2087 * #ClutterActor and should not be unreferenced with g_object_unref()
2088 *
2089 * Since: 1.0
2090 *
2091 * Deprecated: 1.10: Use the implicit transition for animatable properties
2092 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2093 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2094 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2095 */
2096 ClutterAnimation *
2097 clutter_actor_animate_with_alpha (ClutterActor *actor,
2098 ClutterAlpha *alpha,
2099 const gchar *first_property_name,
2100 ...)
2101 {
2102 ClutterAnimation *animation;
2103 ClutterTimeline *timeline;
2104 va_list args;
2105
2106 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2107 g_return_val_if_fail (CLUTTER_IS_ALPHA (alpha), NULL);
2108 g_return_val_if_fail (first_property_name != NULL, NULL);
2109
2110 timeline = clutter_alpha_get_timeline (alpha);
2111 if (timeline == NULL)
2112 {
2113 g_warning ("The passed ClutterAlpha does not have an "
2114 "associated ClutterTimeline.");
2115 return NULL;
2116 }
2117
2118 animation = animation_create_for_actor (actor);
2119 clutter_animation_set_alpha_internal (animation, alpha);
2120
2121 va_start (args, first_property_name);
2122 clutter_animation_setup_valist (animation, first_property_name, args);
2123 va_end (args);
2124
2125 clutter_animation_start (animation);
2126
2127 return animation;
2128 }
2129
2130 /**
2131 * clutter_actor_animate_with_timeline:
2132 * @actor: a #ClutterActor
2133 * @mode: an animation mode logical id
2134 * @timeline: a #ClutterTimeline
2135 * @first_property_name: the name of a property
2136 * @...: a %NULL terminated list of property names and
2137 * property values
2138 *
2139 * Animates the given list of properties of @actor between the current
2140 * value for each property and a new final value. The animation has a
2141 * definite duration given by @timeline and a speed given by the @mode.
2142 *
2143 * See clutter_actor_animate() for further details.
2144 *
2145 * This function is useful if you want to use an existing timeline
2146 * to animate @actor.
2147 *
2148 * Return value: (transfer none): a #ClutterAnimation object. The object is
2149 * owned by the #ClutterActor and should not be unreferenced with
2150 * g_object_unref()
2151 *
2152 * Since: 1.0
2153 * Deprecated: 1.12: Use the implicit transition for animatable properties
2154 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2155 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2156 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2157 */
2158 ClutterAnimation *
2159 clutter_actor_animate_with_timeline (ClutterActor *actor,
2160 gulong mode,
2161 ClutterTimeline *timeline,
2162 const gchar *first_property_name,
2163 ...)
2164 {
2165 ClutterAnimation *animation;
2166 va_list args;
2167
2168 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2169 g_return_val_if_fail (CLUTTER_IS_TIMELINE (timeline), NULL);
2170 g_return_val_if_fail (first_property_name != NULL, NULL);
2171
2172 animation = animation_create_for_actor (actor);
2173 clutter_animation_set_mode (animation, mode);
2174 clutter_animation_set_timeline (animation, timeline);
2175
2176 va_start (args, first_property_name);
2177 clutter_animation_setup_valist (animation, first_property_name, args);
2178 va_end (args);
2179
2180 clutter_animation_start (animation);
2181
2182 return animation;
2183 }
2184
2185 /**
2186 * clutter_actor_animate:
2187 * @actor: a #ClutterActor
2188 * @mode: an animation mode logical id
2189 * @duration: duration of the animation, in milliseconds
2190 * @first_property_name: the name of a property
2191 * @...: a %NULL terminated list of property names and
2192 * property values
2193 *
2194 * Animates the given list of properties of @actor between the current
2195 * value for each property and a new final value. The animation has a
2196 * definite duration and a speed given by the @mode.
2197 *
2198 * For example, this:
2199 *
2200 * |[<!-- language="C" -->
2201 * clutter_actor_animate (rectangle, CLUTTER_LINEAR, 250,
2202 * "width", 100.0,
2203 * "height", 100.0,
2204 * NULL);
2205 * ]|
2206 *
2207 * will make width and height properties of the #ClutterActor "rectangle"
2208 * grow linearly between the current value and 100 pixels, in 250 milliseconds.
2209 *
2210 * The animation @mode is a logical id, either from the #ClutterAnimationMode
2211 * enumeration of from clutter_alpha_register_func().
2212 *
2213 * All the properties specified will be animated between the current value
2214 * and the final value. If a property should be set at the beginning of
2215 * the animation but not updated during the animation, it should be prefixed
2216 * by the "fixed::" string, for instance:
2217 *
2218 * |[<!-- language="C" -->
2219 * clutter_actor_animate (actor, CLUTTER_EASE_IN_SINE, 100,
2220 * "rotation-angle-z", 360.0,
2221 * "fixed::rotation-center-z", &center,
2222 * NULL);
2223 * ]|
2224 *
2225 * Will animate the "rotation-angle-z" property between the current value
2226 * and 360 degrees, and set the "rotation-center-z" property to the fixed
2227 * value of the #ClutterVertex "center".
2228 *
2229 * This function will implicitly create a #ClutterAnimation object which
2230 * will be assigned to the @actor and will be returned to the developer
2231 * to control the animation or to know when the animation has been
2232 * completed.
2233 *
2234 * If a name argument starts with "signal::", "signal-after::",
2235 * "signal-swapped::" or "signal-swapped-after::" the two following arguments
2236 * are used as callback function and data for a signal handler installed on
2237 * the #ClutterAnimation object for the specified signal name, for instance:
2238 *
2239 * |[<!-- language="C" -->
2240 * static void
2241 * on_animation_completed (ClutterAnimation *animation,
2242 * ClutterActor *actor)
2243 * {
2244 * clutter_actor_hide (actor);
2245 * }
2246 *
2247 * clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
2248 * "opacity", 0,
2249 * "signal::completed", on_animation_completed, actor,
2250 * NULL);
2251 * ]|
2252 *
2253 * or, to automatically destroy an actor at the end of the animation:
2254 *
2255 * |[<!-- language="C" -->
2256 * clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 100,
2257 * "opacity", 0,
2258 * "signal-swapped-after::completed",
2259 * clutter_actor_destroy,
2260 * actor,
2261 * NULL);
2262 * ]|
2263 *
2264 * The "signal::" modifier is the equivalent of using g_signal_connect();
2265 * the "signal-after::" modifier is the equivalent of using
2266 * g_signal_connect_after() or g_signal_connect_data() with the
2267 * %G_CONNECT_AFTER; the "signal-swapped::" modifier is the equivalent
2268 * of using g_signal_connect_swapped() or g_signal_connect_data() with the
2269 * %G_CONNECT_SWAPPED flah; finally, the "signal-swapped-after::" modifier
2270 * is the equivalent of using g_signal_connect_data() with both the
2271 * %G_CONNECT_AFTER and %G_CONNECT_SWAPPED flags. The clutter_actor_animate()
2272 * function will not keep track of multiple connections to the same signal,
2273 * so it is your responsability to avoid them when calling
2274 * clutter_actor_animate() multiple times on the same actor.
2275 *
2276 * Calling this function on an actor that is already being animated
2277 * will cause the current animation to change with the new final values,
2278 * the new easing mode and the new duration - that is, this code:
2279 *
2280 * |[<!-- language="C" -->
2281 * clutter_actor_animate (actor, CLUTTER_LINEAR, 250,
2282 * "width", 100.0,
2283 * "height", 100.0,
2284 * NULL);
2285 * clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
2286 * "x", 100.0,
2287 * "y", 100.0,
2288 * "width", 200.0,
2289 * NULL);
2290 * ]|
2291 *
2292 * is the equivalent of:
2293 *
2294 * |[<!-- language="C" -->
2295 * clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 500,
2296 * "x", 100.0,
2297 * "y", 100.0,
2298 * "width", 200.0,
2299 * "height", 100.0,
2300 * NULL);
2301 * ]|
2302 *
2303 * Unless the animation is looping, the #ClutterAnimation created by
2304 * clutter_actor_animate() will become invalid as soon as it is
2305 * complete.
2306 *
2307 * Since the created #ClutterAnimation instance attached to @actor
2308 * is guaranteed to be valid throughout the #ClutterAnimation::completed
2309 * signal emission chain, you will not be able to create a new animation
2310 * using clutter_actor_animate() on the same @actor from within the
2311 * #ClutterAnimation::completed signal handler unless you use
2312 * g_signal_connect_after() to connect the callback function, for instance:
2313 *
2314 * |[<!-- language="C" -->
2315 * static void
2316 * on_animation_completed (ClutterAnimation *animation,
2317 * ClutterActor *actor)
2318 * {
2319 * clutter_actor_animate (actor, CLUTTER_EASE_OUT_CUBIC, 250,
2320 * "x", 500.0,
2321 * "y", 500.0,
2322 * NULL);
2323 * }
2324 *
2325 * ...
2326 * animation = clutter_actor_animate (actor, CLUTTER_EASE_IN_CUBIC, 250,
2327 * "x", 100.0,
2328 * "y", 100.0,
2329 * NULL);
2330 * g_signal_connect (animation, "completed",
2331 * G_CALLBACK (on_animation_completed),
2332 * actor);
2333 * ...
2334 * ]|
2335 *
2336 * Return value: (transfer none): a #ClutterAnimation object. The object is
2337 * owned by the #ClutterActor and should not be unreferenced with
2338 * g_object_unref()
2339 *
2340 * Since: 1.0
2341 * Deprecated: 1.12: Use the implicit transition for animatable properties
2342 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2343 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2344 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2345 */
2346 ClutterAnimation *
2347 clutter_actor_animate (ClutterActor *actor,
2348 gulong mode,
2349 guint duration,
2350 const gchar *first_property_name,
2351 ...)
2352 {
2353 ClutterAnimation *animation;
2354 va_list args;
2355
2356 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2357 g_return_val_if_fail (mode != CLUTTER_CUSTOM_MODE, NULL);
2358 g_return_val_if_fail (duration > 0, NULL);
2359 g_return_val_if_fail (first_property_name != NULL, NULL);
2360
2361 animation = animation_create_for_actor (actor);
2362 clutter_animation_set_mode (animation, mode);
2363 clutter_animation_set_duration (animation, duration);
2364
2365 va_start (args, first_property_name);
2366 clutter_animation_setup_valist (animation, first_property_name, args);
2367 va_end (args);
2368
2369 clutter_animation_start (animation);
2370
2371 return animation;
2372 }
2373
2374 /**
2375 * clutter_actor_animatev:
2376 * @actor: a #ClutterActor
2377 * @mode: an animation mode logical id
2378 * @duration: duration of the animation, in milliseconds
2379 * @n_properties: number of property names and values
2380 * @properties: (array length=n_properties) (element-type utf8): a vector
2381 * containing the property names to set
2382 * @values: (array length=n_properties): a vector containing the
2383 * property values to set
2384 *
2385 * Animates the given list of properties of @actor between the current
2386 * value for each property and a new final value. The animation has a
2387 * definite duration and a speed given by the @mode.
2388 *
2389 * This is the vector-based variant of clutter_actor_animate(), useful
2390 * for language bindings.
2391 *
2392 * Unlike clutter_actor_animate(), this function will not
2393 * allow you to specify "signal::" names and callbacks.
2394 *
2395 * Return value: (transfer none): a #ClutterAnimation object. The object is
2396 * owned by the #ClutterActor and should not be unreferenced with
2397 * g_object_unref()
2398 *
2399 * Since: 1.0
2400 * Deprecated: 1.12: Use the implicit transition for animatable properties
2401 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2402 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2403 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2404 */
2405 ClutterAnimation *
2406 clutter_actor_animatev (ClutterActor *actor,
2407 gulong mode,
2408 guint duration,
2409 gint n_properties,
2410 const gchar * const properties[],
2411 const GValue *values)
2412 {
2413 ClutterAnimation *animation;
2414
2415 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2416 g_return_val_if_fail (mode != CLUTTER_CUSTOM_MODE, NULL);
2417 g_return_val_if_fail (duration > 0, NULL);
2418 g_return_val_if_fail (properties != NULL, NULL);
2419 g_return_val_if_fail (values != NULL, NULL);
2420
2421 animation = animation_create_for_actor (actor);
2422 clutter_animation_set_mode (animation, mode);
2423 clutter_animation_set_duration (animation, duration);
2424 clutter_animation_setupv (animation, n_properties, properties, values);
2425 clutter_animation_start (animation);
2426
2427 return animation;
2428 }
2429
2430 /**
2431 * clutter_actor_animate_with_timelinev:
2432 * @actor: a #ClutterActor
2433 * @mode: an animation mode logical id
2434 * @timeline: a #ClutterTimeline
2435 * @n_properties: number of property names and values
2436 * @properties: (array length=n_properties) (element-type utf8): a vector
2437 * containing the property names to set
2438 * @values: (array length=n_properties): a vector containing the
2439 * property values to set
2440 *
2441 * Animates the given list of properties of @actor between the current
2442 * value for each property and a new final value. The animation has a
2443 * definite duration given by @timeline and a speed given by the @mode.
2444 *
2445 * See clutter_actor_animate() for further details.
2446 *
2447 * This function is useful if you want to use an existing timeline
2448 * to animate @actor.
2449 *
2450 * This is the vector-based variant of clutter_actor_animate_with_timeline(),
2451 * useful for language bindings.
2452 *
2453 * Unlike clutter_actor_animate_with_timeline(), this function
2454 * will not allow you to specify "signal::" names and callbacks.
2455 *
2456 * Return value: (transfer none): a #ClutterAnimation object. The object is
2457 * owned by the #ClutterActor and should not be unreferenced with
2458 * g_object_unref()
2459 *
2460 * Since: 1.0
2461 * Deprecated: 1.12: Use the implicit transition for animatable properties
2462 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2463 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2464 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2465 */
2466 ClutterAnimation *
2467 clutter_actor_animate_with_timelinev (ClutterActor *actor,
2468 gulong mode,
2469 ClutterTimeline *timeline,
2470 gint n_properties,
2471 const gchar * const properties[],
2472 const GValue *values)
2473 {
2474 ClutterAnimation *animation;
2475
2476 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2477 g_return_val_if_fail (CLUTTER_IS_TIMELINE (timeline), NULL);
2478 g_return_val_if_fail (properties != NULL, NULL);
2479 g_return_val_if_fail (values != NULL, NULL);
2480
2481 animation = animation_create_for_actor (actor);
2482 clutter_animation_set_mode (animation, mode);
2483 clutter_animation_set_timeline (animation, timeline);
2484 clutter_animation_setupv (animation, n_properties, properties, values);
2485 clutter_animation_start (animation);
2486
2487 return animation;
2488 }
2489
2490 /**
2491 * clutter_actor_animate_with_alphav:
2492 * @actor: a #ClutterActor
2493 * @alpha: a #ClutterAlpha
2494 * @n_properties: number of property names and values
2495 * @properties: (array length=n_properties) (element-type utf8): a vector
2496 * containing the property names to set
2497 * @values: (array length=n_properties): a vector containing the
2498 * property values to set
2499 *
2500 * Animates the given list of properties of @actor between the current
2501 * value for each property and a new final value. The animation has a
2502 * definite behaviour given by the passed @alpha.
2503 *
2504 * See clutter_actor_animate() for further details.
2505 *
2506 * This function is useful if you want to use an existing #ClutterAlpha
2507 * to animate @actor.
2508 *
2509 * This is the vector-based variant of clutter_actor_animate_with_alpha(),
2510 * useful for language bindings.
2511 *
2512 * Unlike clutter_actor_animate_with_alpha(), this function will
2513 * not allow you to specify "signal::" names and callbacks.
2514 *
2515 * Return value: (transfer none): a #ClutterAnimation object. The object is owned by the
2516 * #ClutterActor and should not be unreferenced with g_object_unref()
2517 *
2518 * Since: 1.0
2519 *
2520 * Deprecated: 1.10: Use the implicit transition for animatable properties
2521 * in #ClutterActor instead. See clutter_actor_save_easing_state(),
2522 * clutter_actor_set_easing_mode(), clutter_actor_set_easing_duration(),
2523 * clutter_actor_set_easing_delay(), and clutter_actor_restore_easing_state().
2524 */
2525 ClutterAnimation *
2526 clutter_actor_animate_with_alphav (ClutterActor *actor,
2527 ClutterAlpha *alpha,
2528 gint n_properties,
2529 const gchar * const properties[],
2530 const GValue *values)
2531 {
2532 ClutterAnimation *animation;
2533 ClutterTimeline *timeline;
2534
2535 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2536 g_return_val_if_fail (CLUTTER_IS_ALPHA (alpha), NULL);
2537 g_return_val_if_fail (properties != NULL, NULL);
2538 g_return_val_if_fail (values != NULL, NULL);
2539
2540 timeline = clutter_alpha_get_timeline (alpha);
2541 if (timeline == NULL)
2542 {
2543 g_warning ("The passed ClutterAlpha does not have an "
2544 "associated ClutterTimeline.");
2545 return NULL;
2546 }
2547
2548 animation = animation_create_for_actor (actor);
2549 clutter_animation_set_alpha_internal (animation, alpha);
2550 clutter_animation_setupv (animation, n_properties, properties, values);
2551 clutter_animation_start (animation);
2552
2553 return animation;
2554 }
2555
2556 /**
2557 * clutter_actor_get_animation:
2558 * @actor: a #ClutterActor
2559 *
2560 * Retrieves the #ClutterAnimation used by @actor, if clutter_actor_animate()
2561 * has been called on @actor.
2562 *
2563 * Return value: (transfer none): a #ClutterAnimation, or %NULL
2564 *
2565 * Since: 1.0
2566 * Deprecated: 1.12: Use the implicit transition for animatable properties
2567 * in #ClutterActor instead, and clutter_actor_get_transition() to retrieve
2568 * the transition.
2569 */
2570 ClutterAnimation *
2571 clutter_actor_get_animation (ClutterActor *actor)
2572 {
2573 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
2574
2575 return g_object_get_qdata (G_OBJECT (actor), quark_object_animation);
2576 }
2577
2578 /**
2579 * clutter_actor_detach_animation:
2580 * @actor: a #ClutterActor
2581 *
2582 * Detaches the #ClutterAnimation used by @actor, if clutter_actor_animate()
2583 * has been called on @actor.
2584 *
2585 * Once the animation has been detached, it loses a reference. If it was
2586 * the only reference then the #ClutterAnimation becomes invalid.
2587 *
2588 * The #ClutterAnimation::completed signal will not be emitted.
2589 *
2590 * Since: 1.4
2591 * Deprecated: 1.12: Use the implicit transition for animatable properties
2592 * in #ClutterActor instead, and clutter_actor_remove_transition() to
2593 * remove the transition.
2594 */
2595 void
2596 clutter_actor_detach_animation (ClutterActor *actor)
2597 {
2598 ClutterAnimation *animation;
2599 ClutterAnimationPrivate *priv;
2600
2601 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
2602
2603 animation = g_object_get_qdata (G_OBJECT (actor), quark_object_animation);
2604 if (animation == NULL)
2605 return;
2606
2607 priv = animation->priv;
2608
2609 g_assert (priv->object == G_OBJECT (actor));
2610
2611 /* we can't call get_timeline_internal() here because it would be
2612 * pointless to create a timeline on an animation we want to detach
2613 */
2614 if (priv->alpha != NULL)
2615 {
2616 ClutterTimeline *timeline;
2617
2618 timeline = clutter_alpha_get_timeline (priv->alpha);
2619 if (timeline != NULL)
2620 clutter_timeline_stop (timeline);
2621 }
2622
2623 /* disconnect the ::destroy handler added by animation_create_for_actor() */
2624 g_signal_handlers_disconnect_by_func (actor,
2625 G_CALLBACK (on_actor_destroy),
2626 animation);
2627
2628 clutter_animation_set_object (animation, NULL);
2629
2630 /* drop the reference on the animation */
2631 g_object_unref (animation);
2632 }