Debian Codegraph @

clutter/deprecated/clutter-state.c

raw
1 /*
2 * Clutter.
3 *
4 * An OpenGL based 'interactive canvas' library.
5 *
6 * Authored By Øyvind Kolås <[email protected]>
7 *
8 * Copyright (C) 2009 Intel Corporation
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
22 */
23
24 /**
25 * SECTION:clutter-state
26 * @short_description: State machine with animated transitions
27 *
28 * #ClutterState is an object controlling the tweening of properties on
29 * multiple actors between a set of named states. #ClutterStateKey<!-- -->s
30 * define how the properties are animated. If the source_state_name for a key
31 * is NULL it is used for transition to the target state unless a specific key
32 * exists for transitioning from the current state to the requested state.
33 *
34 * #ClutterState is available since Clutter 1.4.
35 *
36 * #ClutterState has been deprecated in Clutter 1.12. There is no direct
37 * replacement for this API, but it's highly suggested you use a combination
38 * of [implicit transitions][clutter-actor-animation] and explicit transitions
39 * using #ClutterTransition and its subclasses.
40 *
41 * ## Using ClutterState
42 *
43 * The following example defines a "base" and a "hover" state in a
44 * #ClutterState instance.
45 *
46 * |[<!-- language="C" -->
47 * ClutterState *state = clutter_state_new ();
48 * ClutterColor color = { 0, };
49 *
50 * // transition from any state to the "base" state
51 * clutter_color_from_string (&color, "rgb(255, 0, 0)");
52 * clutter_state_set (state, NULL, "base",
53 * actor, "color", CLUTTER_LINEAR, &color,
54 * actor, "scale-x", CLUTTER_EASE_IN_BOUNCE, 1.0,
55 * actor, "scale-y", CLUTTER_EASE_IN_BOUNCE, 1.0,
56 * NULL);
57 *
58 * // transition from the "base" state to the "hover" state
59 * clutter_color_from_string (&color, "rgb(0, 0, 255)");
60 * clutter_state_set (state, "base", "hover",
61 * actor, "color", CLUTTER_LINEAR, &color,
62 * actor, "scale-x", CLUTTER_EASE_OUT_BOUNCE, 1.7,
63 * actor, "scale-y", CLUTTER_EASE_OUT_BOUNCE, 1.7,
64 * NULL);
65 *
66 * // the default duration of any transition
67 * clutter_state_set_duration (state, NULL, NULL, 500);
68 *
69 * // set "base" as the initial state
70 * clutter_state_warp_to_state (state, "base");
71 * ]|
72 *
73 * The actor then uses the #ClutterState to animate through the
74 * two states using callbacks for the #ClutterActor::enter-event and
75 * #ClutterActor::leave-event signals.
76 *
77 * |[<!-- language="C" -->
78 * static gboolean
79 * on_enter (ClutterActor *actor,
80 * ClutterEvent *event,
81 * ClutterState *state)
82 * {
83 * clutter_state_set_state (state, "hover");
84 *
85 * return CLUTTER_EVENT_STOP;
86 * }
87 *
88 * static gboolean
89 * on_leave (ClutterActor *actor,
90 * ClutterEvent *event,
91 * ClutterState *state)
92 * {
93 * clutter_state_set_state (state, "base");
94 *
95 * return CLUTTER_EVENT_STOP;
96 * }
97 *
98 * ## ClutterState description for ClutterScript
99 *
100 * #ClutterState defines a custom `transitions` JSON object member which
101 * allows describing the states.
102 *
103 * The `transitions` property has the following syntax:
104 *
105 * |[
106 * {
107 * "transitions" : [
108 * {
109 * "source" : "source-state",
110 * "target" : "target-state",
111 * "duration" : milliseconds,
112 * "keys" : [
113 * [
114 * "object-id",
115 * "property-name",
116 * "easing-mode",
117 * "final-value",
118 * ],
119 * [
120 * "object-id",
121 * "property-name",
122 * "easing-mode",
123 * "final-value",
124 * pre-delay,
125 * post-delay;
126 * ],
127 * ...
128 * ]
129 * },
130 * {
131 * "source" : "source-state",
132 * "target" : "target-state",
133 * "duration" : milliseconds,
134 * "animator" : "animator-definition"
135 * },
136 * ...
137 * ]
138 * }
139 * ]|
140 *
141 * Each element of the transitions array follows the same rules and order
142 * as clutter_state_set_key() function arguments.
143 *
144 * The source and target values control the source and target state of the
145 * transition. The key and animator properties are mutually exclusive.
146 *
147 * The pre-delay and post-delay values are optional.
148 *
149 * The example below is a translation into a #ClutterScript definition of
150 * the code in the #ClutterState example above.
151 *
152 * |[
153 * {
154 * "id" : "button-state",
155 * "type" : "ClutterState",
156 * "duration" : 500,
157 * "transitions" : [
158 * {
159 * "source" : "*",
160 * "target" : "base",
161 * "keys" : [
162 * [ "button", "color", "linear", "rgb(255, 0, 0)" ],
163 * [ "button", "scale-x", "easeInBounce", 1.0 ],
164 * [ "button", "scale-y", "easeInBounce", 1.0 ]
165 * ]
166 * },
167 * {
168 * "source" : "base",
169 * "target" : "hover",
170 * "keys" : [
171 * [ "button", "color", "linear", "rgb(0, 0, 255)" ],
172 * [ "button", "scale-x", "easeOutBounce", 1.7 ],
173 * [ "button", "scale-y", "easeOutBounce", 1.7 ]
174 * ]
175 * }
176 * ]
177 * }
178 * ]|
179 */
180
181 #ifdef HAVE_CONFIG_H
182 #include "config.h"
183 #endif
184
185 #include <gobject/gvaluecollector.h>
186 #include <string.h>
187
188 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
189
190 #include "clutter-state.h"
191
192 #include "clutter-alpha.h"
193 #include "clutter-animatable.h"
194 #include "clutter-animator.h"
195 #include "clutter-enum-types.h"
196 #include "clutter-interval.h"
197 #include "clutter-marshal.h"
198 #include "clutter-private.h"
199 #include "clutter-scriptable.h"
200 #include "clutter-script-private.h"
201
202 typedef struct StateAnimator {
203 const gchar *source_state_name; /* interned string identifying entry */
204 ClutterAnimator *animator; /* pointer to animator itself */
205 } StateAnimator;
206
207 typedef struct State
208 {
209 const gchar *name; /* interned string for this state name */
210 GHashTable *durations; /* durations for transitions from various state
211 names */
212 GList *keys; /* list of all keys pertaining to transitions
213 from other states to this one */
214 GArray *animators; /* list of animators for transitioning from
215 * specific source states */
216 ClutterState *clutter_state; /* the ClutterState object this state belongs to
217 */
218 } State;
219
220 struct _ClutterStatePrivate
221 {
222 GHashTable *states; /* contains state objects */
223 guint duration; /* global fallback duration */
224 ClutterTimeline *timeline; /* The timeline used for doing the
225 progress */
226 ClutterTimeline *slave_timeline; /* a slave timeline used to compute
227 alphas */
228 const gchar *source_state_name; /* current source state */
229 State *source_state; /* current source_state */
230 const gchar *target_state_name; /* current target state */
231 State *target_state; /* target state name */
232 ClutterAnimator *current_animator; /* !NULL if the current transition is
233 overriden by an animator */
234 };
235
236 #define SLAVE_TIMELINE_LENGTH 10000
237
238 /*
239 * ClutterStateKey:
240 *
241 * An opaque data structure with accessor functions.
242 *
243 */
244 typedef struct _ClutterStateKey
245 {
246 GObject *object; /* an Gobject */
247 const gchar *property_name;/* the name of a property */
248 gulong mode; /* alpha to use */
249 GValue value; /* target value */
250 gdouble pre_delay; /* fraction of duration to delay before
251 starting */
252 gdouble pre_pre_delay;/* fraction of duration to add to
253 pre_delay. This is used to set keys
254 during transitions. */
255 gdouble post_delay; /* fraction of duration to be done in */
256
257 State *source_state; /* source state */
258 State *target_state; /* target state */
259
260 ClutterAlpha *alpha; /* The alpha this key uses for interpolation */
261 ClutterInterval *interval; /* The interval this key uses for
262 interpolation */
263
264 guint is_animatable : 1;
265 guint is_inert : 1; /* set if the key is being destroyed due to
266 weak reference */
267 gint ref_count; /* reference count for boxed life time */
268 } _ClutterStateKey;
269
270 enum
271 {
272 PROP_0,
273 PROP_DURATION,
274 PROP_STATE,
275
276 PROP_LAST
277 };
278
279 static GParamSpec *obj_props[PROP_LAST];
280
281 enum
282 {
283 COMPLETED,
284 LAST_SIGNAL
285 };
286
287 static void clutter_scriptable_iface_init (ClutterScriptableIface *iface);
288
289 static guint state_signals[LAST_SIGNAL] = {0, };
290
291 G_DEFINE_TYPE_WITH_CODE (ClutterState, clutter_state, G_TYPE_OBJECT,
292 G_ADD_PRIVATE (ClutterState)
293 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_SCRIPTABLE,
294 clutter_scriptable_iface_init))
295
296 /**
297 * clutter_state_new:
298 *
299 * Creates a new #ClutterState
300 *
301 * Return value: the newly create #ClutterState instance
302 *
303 * Since: 1.4
304 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
305 * #ClutterTransitionGroup instead
306 */
307 ClutterState *
308 clutter_state_new (void)
309 {
310 return g_object_new (CLUTTER_TYPE_STATE, NULL);
311 }
312
313 static gint
314 sort_props_func (gconstpointer a,
315 gconstpointer b)
316 {
317 const ClutterStateKey *pa = a;
318 const ClutterStateKey *pb = b;
319
320 if (pa->object == pb->object)
321 {
322 gint propnamediff = pa->property_name-pb->property_name;
323 if (propnamediff == 0)
324 return pb->source_state - pa->source_state;
325
326 return propnamediff;
327 }
328
329 return pa->object - pb->object;
330 }
331
332 static State * clutter_state_fetch_state (ClutterState *state,
333 const gchar *state_name,
334 gboolean force_creation);
335 static void object_disappeared (gpointer data,
336 GObject *where_the_object_was);
337
338 static ClutterStateKey *
339 clutter_state_key_new (State *state,
340 GObject *object,
341 const gchar *property_name,
342 GParamSpec *pspec,
343 guint mode)
344 {
345 ClutterStatePrivate *priv = state->clutter_state->priv;
346 ClutterStateKey *state_key;
347 GValue value = G_VALUE_INIT;
348
349 state_key = g_slice_new0 (ClutterStateKey);
350
351 state_key->target_state = state;
352 state_key->object = object;
353 state_key->property_name = g_intern_string (property_name);
354 state_key->mode = mode;
355 state_key->is_animatable = CLUTTER_IS_ANIMATABLE (object);
356
357 state_key->alpha = clutter_alpha_new ();
358 g_object_ref_sink (state_key->alpha);
359 clutter_alpha_set_mode (state_key->alpha, mode);
360 clutter_alpha_set_timeline (state_key->alpha, priv->slave_timeline);
361
362 state_key->interval =
363 g_object_new (CLUTTER_TYPE_INTERVAL,
364 "value-type", G_PARAM_SPEC_VALUE_TYPE (pspec),
365 NULL);
366 g_object_ref_sink (state_key->interval);
367
368 g_value_init (&value, G_PARAM_SPEC_VALUE_TYPE (pspec));
369 clutter_interval_set_initial_value (state_key->interval, &value);
370 clutter_interval_set_final_value (state_key->interval, &value);
371 g_value_unset (&value);
372
373 g_object_weak_ref (object, object_disappeared,
374 state_key->target_state->clutter_state);
375
376 return state_key;
377 }
378
379 static void
380 clutter_state_key_free (gpointer clutter_state_key)
381 {
382 ClutterStateKey *key = clutter_state_key;
383
384 if (key == NULL)
385 return;
386
387 key->ref_count -= 1;
388
389 if (key->ref_count > 0)
390 return;
391
392 if (!key->is_inert)
393 {
394 g_object_weak_unref (key->object,
395 object_disappeared,
396 key->target_state->clutter_state);
397 }
398
399 g_value_unset (&key->value);
400
401 g_object_unref (key->alpha);
402 g_object_unref (key->interval);
403
404 g_slice_free (ClutterStateKey, key);
405 }
406
407
408 static inline void
409 clutter_state_remove_key_internal (ClutterState *this,
410 const gchar *source_state_name,
411 const gchar *target_state_name,
412 GObject *object,
413 const gchar *property_name,
414 gboolean is_inert)
415 {
416 GList *s, *state_list;
417 State *source_state = NULL;
418
419 source_state_name = g_intern_string (source_state_name);
420 target_state_name = g_intern_string (target_state_name);
421 property_name = g_intern_string (property_name);
422
423 if (source_state_name)
424 source_state = clutter_state_fetch_state (this, source_state_name, FALSE);
425
426 again_from_start:
427
428 if (target_state_name != NULL)
429 state_list = g_list_append (NULL, (gpointer) target_state_name);
430 else
431 state_list = clutter_state_get_states (this);
432
433 for (s = state_list; s != NULL; s = s->next)
434 {
435 State *target_state;
436 target_state = clutter_state_fetch_state (this, s->data, FALSE);
437 /* Go through each TargetState */
438 if (target_state)
439 {
440 GList *k = target_state->keys;
441
442 /* Note the safe while() loop, because we modify the list inline */
443 while (k != NULL)
444 {
445 ClutterStateKey *key = k->data;
446
447 k = k->next;
448
449 /* Check if each key matches query */
450 if ( (object == NULL || (object == key->object))
451 && (source_state == NULL || (source_state == key->source_state))
452 && (property_name == NULL || ((property_name == key->property_name))))
453 {
454 /* Remove matching key */
455 target_state->keys = g_list_remove (target_state->keys, key);
456 key->is_inert = is_inert;
457 clutter_state_key_free (key);
458
459 /* no more keys with transitions to this target_state*/
460 if (target_state->keys == NULL)
461 {
462 /* If this state is the current state, unset the state */
463 if (target_state == this->priv->target_state)
464 clutter_state_set_state (this, NULL);
465
466 /* remove any keys that exist that uses this state as a source */
467 clutter_state_remove_key_internal (this, s->data, NULL, NULL, NULL, is_inert);
468
469 g_hash_table_remove (this->priv->states, s->data);
470 goto again_from_start; /* we have just freed State *target_state, so
471 need to restart removal */
472 }
473 }
474 }
475 }
476 }
477
478 g_list_free (state_list);
479 }
480
481 static void
482 object_disappeared (gpointer data,
483 GObject *where_the_object_was)
484 {
485 clutter_state_remove_key_internal (data, NULL, NULL,
486 (gpointer) where_the_object_was,
487 NULL,
488 TRUE);
489 }
490
491
492 static void
493 state_free (gpointer data)
494 {
495 State *state = data;
496
497 for (; state->keys;
498 state->keys = g_list_remove (state->keys, state->keys->data))
499 clutter_state_key_free (state->keys->data);
500
501 g_array_free (state->animators, TRUE);
502 g_hash_table_destroy (state->durations);
503 g_free (state);
504 }
505
506 static State *
507 state_new (ClutterState *clutter_state,
508 const gchar *name)
509 {
510 State *state;
511
512 state = g_new0 (State, 1);
513 state->clutter_state = clutter_state;
514 state->name = name;
515 state->animators = g_array_new (TRUE, TRUE, sizeof (StateAnimator));
516 state->durations = g_hash_table_new (g_direct_hash, g_direct_equal);
517
518 return state;
519 }
520
521 static void
522 clutter_state_finalize (GObject *object)
523 {
524 ClutterStatePrivate *priv = CLUTTER_STATE (object)->priv;
525
526 g_hash_table_destroy (priv->states);
527
528 g_object_unref (priv->timeline);
529 g_object_unref (priv->slave_timeline);
530
531 G_OBJECT_CLASS (clutter_state_parent_class)->finalize (object);
532 }
533
534 static void
535 clutter_state_completed (ClutterTimeline *timeline,
536 ClutterState *state)
537 {
538 ClutterStatePrivate *priv = state->priv;
539
540 if (priv->current_animator)
541 {
542 clutter_animator_set_timeline (priv->current_animator, NULL);
543 priv->current_animator = NULL;
544 }
545
546 g_signal_emit (state, state_signals[COMPLETED], 0);
547 }
548
549 static void
550 clutter_state_new_frame (ClutterTimeline *timeline,
551 gint msecs,
552 ClutterState *state)
553 {
554 ClutterStatePrivate *priv = state->priv;
555 GList *k;
556 gdouble progress;
557 const gchar *curprop = NULL;
558 GObject *curobj = NULL;
559 gboolean found_specific = FALSE;
560
561 if (priv->current_animator)
562 return;
563
564 progress = clutter_timeline_get_progress (timeline);
565
566 for (k = priv->target_state->keys; k; k = k->next)
567 {
568 ClutterStateKey *key = k->data;
569 gdouble sub_progress;
570
571 if ((curprop && !(curprop == key->property_name)) ||
572 key->object != curobj)
573 {
574 curprop = key->property_name;
575 curobj = key->object;
576 found_specific = FALSE;
577 }
578
579 if (!found_specific)
580 {
581 if (key->source_state != NULL &&
582 key->source_state->name != NULL &&
583 priv->source_state_name != NULL &&
584 g_str_equal (priv->source_state_name, key->source_state->name))
585 {
586 found_specific = TRUE;
587 }
588
589 if (found_specific || key->source_state == NULL)
590 {
591 gdouble pre_delay = key->pre_delay + key->pre_pre_delay;
592
593 sub_progress = (progress - pre_delay)
594 / (1.0 - (pre_delay + key->post_delay));
595
596 if (sub_progress >= 0.0)
597 {
598 if (sub_progress >= 1.0)
599 sub_progress = 1.0;
600
601 clutter_timeline_advance (priv->slave_timeline,
602 sub_progress * SLAVE_TIMELINE_LENGTH);
603 sub_progress = clutter_alpha_get_alpha (key->alpha);
604
605 if (key->is_animatable)
606 {
607 ClutterAnimatable *animatable;
608 GValue value = G_VALUE_INIT;
609 gboolean res;
610
611 animatable = CLUTTER_ANIMATABLE (key->object);
612
613 g_value_init (&value, clutter_state_key_get_property_type (key));
614
615 res =
616 clutter_animatable_interpolate_value (animatable,
617 key->property_name,
618 key->interval,
619 sub_progress,
620 &value);
621
622 if (res)
623 clutter_animatable_set_final_state (animatable,
624 key->property_name,
625 &value);
626
627 g_value_unset (&value);
628 }
629 else
630 {
631 const GValue *value;
632
633 value = clutter_interval_compute (key->interval, sub_progress);
634 if (value != NULL)
635 g_object_set_property (key->object, key->property_name, value);
636 }
637 }
638
639 /* XXX: should the target value of the default destination be
640 * used even when found a specific source_state key?
641 */
642 }
643 }
644 }
645 }
646
647
648 static ClutterTimeline *
649 clutter_state_change (ClutterState *state,
650 const gchar *target_state_name,
651 gboolean animate)
652 {
653 ClutterStatePrivate *priv;
654 ClutterAnimator *animator;
655 State *new_state;
656 guint duration;
657 GList *k;
658
659 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
660
661 priv = state->priv;
662
663 /* If we've been asked to change state to NULL, reset the
664 * ClutterState to its initial state, but leave the keys
665 * alone.
666 */
667 if (!target_state_name)
668 {
669 if (!priv->target_state)
670 return NULL;
671
672 priv->source_state_name = priv->target_state_name = NULL;
673 priv->source_state = priv->target_state = NULL;
674
675 clutter_timeline_stop (priv->timeline);
676 clutter_timeline_rewind (priv->timeline);
677
678 if (priv->current_animator)
679 {
680 clutter_animator_set_timeline (priv->current_animator, NULL);
681 priv->current_animator = NULL;
682 }
683
684 return NULL;
685 }
686
687 target_state_name = g_intern_string (target_state_name);
688
689 if (target_state_name == priv->target_state_name)
690 {
691 /* Avoid transitioning if the desired state is already current,
692 * unless we're warping to it and the state transition is in
693 * progress (in that case, immediately warp to the state).
694 */
695 if (!clutter_timeline_is_playing (priv->timeline) || animate)
696 return priv->timeline;
697 }
698
699 if (priv->current_animator != NULL)
700 {
701 clutter_animator_set_timeline (priv->current_animator, NULL);
702 priv->current_animator = NULL;
703 }
704
705 priv->source_state_name = priv->target_state_name;
706 priv->target_state_name = target_state_name;
707
708 g_object_notify_by_pspec (G_OBJECT (state), obj_props[PROP_STATE]);
709
710 duration = clutter_state_get_duration (state,
711 priv->source_state_name,
712 priv->target_state_name);
713 clutter_timeline_set_duration (priv->timeline, duration);
714
715 new_state = clutter_state_fetch_state (state, target_state_name, FALSE);
716 if (new_state == NULL)
717 {
718 g_warning ("State '%s' not found", target_state_name);
719
720 return NULL;
721 }
722
723 animator = clutter_state_get_animator (state,
724 priv->source_state_name,
725 priv->target_state_name);
726 priv->target_state = new_state;
727
728 if (animator == NULL && new_state->keys == NULL)
729 animator = clutter_state_get_animator (state, NULL,
730 priv->target_state_name);
731
732 if (animator != NULL)
733 {
734 /* we've got an animator overriding the tweened animation */
735 priv->current_animator = animator;
736 clutter_animator_set_timeline (animator, priv->timeline);
737 }
738 else
739 {
740 for (k = new_state->keys; k != NULL; k = k->next)
741 {
742 ClutterStateKey *key = k->data;
743 GValue initial = G_VALUE_INIT;
744
745 /* Reset the pre-pre-delay - this is only used for setting keys
746 * during transitions.
747 */
748 key->pre_pre_delay = 0;
749
750 g_value_init (&initial, clutter_interval_get_value_type (key->interval));
751
752 if (key->is_animatable)
753 {
754 ClutterAnimatable *animatable;
755
756 animatable = CLUTTER_ANIMATABLE (key->object);
757 clutter_animatable_get_initial_state (animatable,
758 key->property_name,
759 &initial);
760 }
761 else
762 g_object_get_property (key->object, key->property_name, &initial);
763
764 if (clutter_alpha_get_mode (key->alpha) != key->mode)
765 clutter_alpha_set_mode (key->alpha, key->mode);
766
767 clutter_interval_set_initial_value (key->interval, &initial);
768 clutter_interval_set_final_value (key->interval, &key->value);
769
770 g_value_unset (&initial);
771 }
772 }
773
774 if (!animate)
775 {
776 clutter_timeline_stop (priv->timeline);
777 clutter_timeline_advance (priv->timeline, duration);
778
779 /* emit signals, to change properties, and indicate that the
780 * state change is complete */
781 g_signal_emit_by_name (priv->timeline, "new-frame",
782 GINT_TO_POINTER (duration),
783 NULL);
784 g_signal_emit_by_name (priv->timeline, "completed", NULL);
785 }
786 else
787 {
788 clutter_timeline_stop (priv->timeline);
789 clutter_timeline_rewind (priv->timeline);
790 clutter_timeline_start (priv->timeline);
791 }
792
793 return priv->timeline;
794 }
795
796 /**
797 * clutter_state_set_state:
798 * @state: a #ClutterState
799 * @target_state_name: the state to transition to
800 *
801 * Change the current state of #ClutterState to @target_state_name.
802 *
803 * The state will animate during its transition, see
804 * #clutter_state_warp_to_state for animation-free state switching.
805 *
806 * Setting a %NULL state will stop the current animation and unset
807 * the current state, but keys will be left intact.
808 *
809 * Return value: (transfer none): the #ClutterTimeline that drives the
810 * state transition. The returned timeline is owned by the #ClutterState
811 * and it should not be unreferenced
812 *
813 * Since: 1.4
814 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
815 * #ClutterTransitionGroup instead
816 */
817 ClutterTimeline *
818 clutter_state_set_state (ClutterState *state,
819 const gchar *target_state_name)
820 {
821 return clutter_state_change (state, target_state_name, TRUE);
822 }
823
824 /**
825 * clutter_state_warp_to_state:
826 * @state: a #ClutterState
827 * @target_state_name: the state to transition to
828 *
829 * Change to the specified target state immediately with no animation.
830 *
831 * See clutter_state_set_state().
832 *
833 * Return value: (transfer none): the #ClutterTimeline that drives the
834 * state transition. The returned timeline is owned by the #ClutterState
835 * and it should not be unreferenced
836 *
837 * Since: 1.4
838 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
839 * #ClutterTransitionGroup instead
840 */
841 ClutterTimeline *
842 clutter_state_warp_to_state (ClutterState *state,
843 const gchar *target_state_name)
844 {
845 return clutter_state_change (state, target_state_name, FALSE);
846 }
847
848 static GParamSpec *
849 get_property_from_object (GObject *gobject,
850 const gchar *property_name)
851 {
852 GParamSpec *pspec;
853
854 if (CLUTTER_IS_ANIMATABLE (gobject))
855 {
856 ClutterAnimatable *animatable = CLUTTER_ANIMATABLE (gobject);
857
858 pspec = clutter_animatable_find_property (animatable, property_name);
859 }
860 else
861 {
862 GObjectClass *klass = G_OBJECT_GET_CLASS (gobject);
863
864 pspec = g_object_class_find_property (klass, property_name);
865 }
866
867 if (pspec == NULL)
868 {
869 g_warning ("Cannot bind property '%s': objects of type '%s' "
870 "do not have this property",
871 property_name,
872 G_OBJECT_TYPE_NAME (gobject));
873 return NULL;
874 }
875
876 if (!(pspec->flags & G_PARAM_WRITABLE))
877 {
878 g_warning ("Cannot bind property '%s' of object of type '%s': "
879 "the property is not writable",
880 property_name,
881 G_OBJECT_TYPE_NAME (gobject));
882 return NULL;
883 }
884
885 if (!(pspec->flags & G_PARAM_READABLE))
886 {
887 g_warning ("Cannot bind property '%s' of object of type '%s': "
888 "the property is not readable",
889 property_name,
890 G_OBJECT_TYPE_NAME (gobject));
891 return NULL;
892 }
893
894 if (pspec->flags & G_PARAM_CONSTRUCT_ONLY)
895 {
896 g_warning ("Cannot bind property '%s' of object of type '%s': "
897 "the property is set as constructor-only",
898 property_name,
899 G_OBJECT_TYPE_NAME (gobject));
900 return NULL;
901 }
902
903 return pspec;
904 }
905
906 /**
907 * clutter_state_set:
908 * @state: a #ClutterState instance.
909 * @source_state_name: (allow-none): the name of the source state keys are being added for
910 * @target_state_name: the name of the target state keys are being added for
911 * @first_object: a #GObject
912 * @first_property_name: a property of @first_object to specify a key for
913 * @first_mode: the id of the alpha function to use
914 * @...: the value @first_property_name should have in @target_state_name,
915 * followed by object, property name, mode, value tuples, terminated
916 * by %NULL
917 *
918 * Adds multiple keys to a named state of a #ClutterState instance, specifying
919 * the easing mode and value a given property of an object should have at a
920 * given progress of the animation.
921 *
922 * The mode specified is the easing mode used when going to from the previous
923 * key to the specified key.
924 *
925 * For instance, the code below:
926 *
927 * |[
928 * clutter_state_set (state, NULL, "hover",
929 * button, "opacity", CLUTTER_LINEAR, 255,
930 * button, "scale-x", CLUTTER_EASE_OUT_CUBIC, 1.2,
931 * button, "scale-y", CLUTTER_EASE_OUT_CUBIC, 1.2,
932 * NULL);
933 * ]|
934 *
935 * will create a transition from any state (a @source_state_name or NULL is
936 * treated as a wildcard) and a state named "hover"; the
937 * button object will have the #ClutterActor:opacity
938 * property animated to a value of 255 using %CLUTTER_LINEAR as the animation
939 * mode, and the #ClutterActor:scale-x and #ClutterActor:scale-y properties
940 * animated to a value of 1.2 using %CLUTTER_EASE_OUT_CUBIC as the animation
941 * mode. To change the state (and start the transition) you can use the
942 * clutter_state_set_state() function:
943 *
944 * |[
945 * clutter_state_set_state (state, "hover");
946 * ]|
947 *
948 * If a given object, state_name, property tuple already exist in the
949 * #ClutterState instance, then the mode and value will be replaced with
950 * the new specified values.
951 *
952 * If a property name is prefixed with "delayed::" two additional
953 * arguments per key are expected: a value relative to the full state time
954 * to pause before transitioning and a similar value to pause after
955 * transitioning, e.g.:
956 *
957 * |[
958 * clutter_state_set (state, "hover", "toggled",
959 * button, "delayed::scale-x", CLUTTER_LINEAR, 1.0, 0.2, 0.2,
960 * button, "delayed::scale-y", CLUTTER_LINEAR, 1.0, 0.2, 0.2,
961 * NULL);
962 * ]|
963 *
964 * will pause for 20% of the duration of the transition before animating,
965 * and 20% of the duration after animating.
966 *
967 * Since: 1.4
968 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
969 * #ClutterTransitionGroup instead
970 */
971 void
972 clutter_state_set (ClutterState *state,
973 const gchar *source_state_name,
974 const gchar *target_state_name,
975 gpointer first_object,
976 const gchar *first_property_name,
977 gulong first_mode,
978 ...)
979 {
980 gpointer object;
981 const gchar *property_name;
982 gulong mode;
983 va_list args;
984
985 g_return_if_fail (CLUTTER_IS_STATE (state));
986
987 object = first_object;
988
989 property_name = first_property_name;
990 mode = first_mode;
991
992 g_return_if_fail (G_IS_OBJECT (first_object));
993 g_return_if_fail (first_property_name);
994
995 va_start (args, first_mode);
996
997 while (object != NULL)
998 {
999 GParamSpec *pspec;
1000 GValue value = G_VALUE_INIT;
1001 gchar *error = NULL;
1002 gboolean is_delayed = FALSE;
1003
1004 if (g_str_has_prefix (property_name, "delayed::"))
1005 {
1006 property_name = strstr (property_name, "::") + 2;
1007 is_delayed = TRUE;
1008 }
1009
1010 pspec = get_property_from_object (object, property_name);
1011 if (pspec == NULL)
1012 break;
1013
1014 G_VALUE_COLLECT_INIT (&value, G_PARAM_SPEC_VALUE_TYPE (pspec),
1015 args, 0,
1016 &error);
1017
1018 if (error != NULL)
1019 {
1020 g_warning ("%s: %s", G_STRLOC, error);
1021 g_free (error);
1022 break;
1023 }
1024
1025 if (is_delayed)
1026 {
1027 gdouble pre_delay = va_arg (args, gdouble);
1028 gdouble post_delay = va_arg (args, gdouble);
1029
1030 clutter_state_set_key (state,
1031 source_state_name,
1032 target_state_name,
1033 object,
1034 property_name,
1035 mode,
1036 &value,
1037 pre_delay,
1038 post_delay);
1039 }
1040 else
1041 {
1042 clutter_state_set_key (state,
1043 source_state_name,
1044 target_state_name,
1045 object,
1046 property_name,
1047 mode,
1048 &value,
1049 0.0,
1050 0.0);
1051 }
1052
1053 g_value_unset (&value);
1054
1055 object = va_arg (args, gpointer);
1056 if (object != NULL)
1057 {
1058 property_name = va_arg (args, gchar*);
1059 mode = va_arg (args, gulong);
1060 }
1061 }
1062
1063 va_end (args);
1064 }
1065
1066 static void
1067 clutter_state_set_key_internal (ClutterState *state,
1068 ClutterStateKey *key)
1069 {
1070 ClutterStatePrivate *priv = state->priv;
1071 State *target_state = key->target_state;
1072 GList *old_item = NULL;
1073
1074 if ((old_item = g_list_find_custom (target_state->keys,
1075 key,
1076 sort_props_func)))
1077 {
1078 ClutterStateKey *old_key = old_item->data;
1079
1080 target_state->keys = g_list_remove (target_state->keys, old_key);
1081 clutter_state_key_free (old_key);
1082 }
1083
1084 target_state->keys = g_list_insert_sorted (target_state->keys,
1085 key,
1086 sort_props_func);
1087
1088 /* If the current target state is modified, we have some work to do.
1089 *
1090 * If the animation is running, we add a key to the current animation
1091 * with a delay of the current duration so that the new animation will
1092 * animate into place.
1093 *
1094 * If the animation isn't running, but the state is set, we immediately
1095 * warp to that state.
1096 */
1097 if (key->target_state == priv->target_state)
1098 {
1099 if (!clutter_timeline_is_playing (priv->timeline))
1100 {
1101 /* We can warp to the state by setting a NULL state, then setting
1102 * the target state again.
1103 */
1104 clutter_state_change (state, NULL, FALSE);
1105 clutter_state_change (state, target_state->name, FALSE);
1106 }
1107 else
1108 {
1109 /* Set the ClutterInterval associated with the state */
1110 GValue initial = G_VALUE_INIT;
1111 gdouble progress = clutter_timeline_get_progress (priv->timeline);
1112
1113 g_value_init (&initial,
1114 clutter_interval_get_value_type (key->interval));
1115
1116 if (key->is_animatable)
1117 {
1118 ClutterAnimatable *animatable;
1119
1120 animatable = CLUTTER_ANIMATABLE (key->object);
1121 clutter_animatable_get_initial_state (animatable,
1122 key->property_name,
1123 &initial);
1124 }
1125 else
1126 g_object_get_property (key->object, key->property_name, &initial);
1127
1128 if (clutter_alpha_get_mode (key->alpha) != key->mode)
1129 clutter_alpha_set_mode (key->alpha, key->mode);
1130
1131 clutter_interval_set_initial_value (key->interval, &initial);
1132 clutter_interval_set_final_value (key->interval, &key->value);
1133
1134 g_value_unset (&initial);
1135
1136 /* Set the delay as if the interval had just begun */
1137 if (progress > key->pre_delay)
1138 key->pre_pre_delay = MIN (progress - key->pre_delay,
1139 1.0 - key->post_delay);
1140 }
1141 }
1142 }
1143
1144 /*
1145 * clutter_state_fetch_state:
1146 * @state: a #ClutterState
1147 * @state_name: the name of the state to be retrieved
1148 * @create: %TRUE if the state should be instantiated if not found
1149 *
1150 * Retrieves the #State structure for @state_name inside the given
1151 * #ClutterState instance
1152 *
1153 * If @state_name is %NULL and @create is %TRUE then NULL will
1154 * be returned.
1155 *
1156 * Return value: a #State structure for the given name, or %NULL
1157 */
1158 static State *
1159 clutter_state_fetch_state (ClutterState *state,
1160 const gchar *state_name,
1161 gboolean create)
1162 {
1163 ClutterStatePrivate *priv = state->priv;
1164 State *retval;
1165
1166 if (state_name == NULL)
1167 {
1168 return NULL;
1169 }
1170 else
1171 state_name = g_intern_string (state_name);
1172
1173 retval = g_hash_table_lookup (priv->states, state_name);
1174 if (retval == NULL && create)
1175 {
1176 retval = state_new (state, state_name);
1177 g_hash_table_insert (priv->states, (gpointer) state_name, retval);
1178 }
1179
1180 return retval;
1181 }
1182
1183 /**
1184 * clutter_state_set_key:
1185 * @state: a #ClutterState instance.
1186 * @source_state_name: (allow-none): the source transition to specify
1187 * transition for, or %NULL to specify the default fallback when a
1188 * more specific source state doesn't exist.
1189 * @target_state_name: the name of the transition to set a key value for.
1190 * @object: the #GObject to set a key for
1191 * @property_name: the property to set a key for
1192 * @mode: the id of the alpha function to use
1193 * @value: the value for property_name of object in state_name
1194 * @pre_delay: relative time of the transition to be idle in the beginning
1195 * of the transition
1196 * @post_delay: relative time of the transition to be idle in the end of
1197 * the transition
1198 *
1199 * Sets one specific end key for a state name, @object, @property_name
1200 * combination.
1201 *
1202 * Return value: (transfer none): the #ClutterState instance, allowing
1203 * chaining of multiple calls
1204 *
1205 * Since: 1.4
1206 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1207 * #ClutterTransitionGroup instead
1208 */
1209 ClutterState *
1210 clutter_state_set_key (ClutterState *state,
1211 const gchar *source_state_name,
1212 const gchar *target_state_name,
1213 GObject *object,
1214 const gchar *property_name,
1215 guint mode,
1216 const GValue *value,
1217 gdouble pre_delay,
1218 gdouble post_delay)
1219 {
1220 GParamSpec *pspec;
1221 ClutterStateKey *state_key;
1222 State *source_state = NULL;
1223 State *target_state;
1224
1225 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
1226 g_return_val_if_fail (G_IS_OBJECT (object), NULL);
1227 g_return_val_if_fail (property_name, NULL);
1228 g_return_val_if_fail (value, NULL);
1229
1230 pspec = get_property_from_object (object, property_name);
1231 if (pspec == NULL)
1232 return state;
1233
1234 source_state = clutter_state_fetch_state (state, source_state_name, TRUE);
1235 target_state = clutter_state_fetch_state (state, target_state_name, TRUE);
1236
1237 property_name = g_intern_string (property_name);
1238 state_key = clutter_state_key_new (target_state,
1239 object, property_name, pspec,
1240 mode);
1241
1242 state_key->source_state = source_state;
1243 state_key->pre_delay = pre_delay;
1244 state_key->post_delay = post_delay;
1245
1246 g_value_init (&state_key->value, G_VALUE_TYPE (value));
1247 g_value_copy (value, &state_key->value);
1248
1249 clutter_state_set_key_internal (state, state_key);
1250
1251 return state;
1252 }
1253
1254 /**
1255 * clutter_state_get_states:
1256 * @state: a #ClutterState instance.
1257 *
1258 * Gets a list of all the state names managed by this #ClutterState.
1259 *
1260 * Return value: (transfer container) (element-type utf8): a newly allocated
1261 * #GList of state names. The contents of the returned #GList are owned
1262 * by the #ClutterState and should not be modified or freed. Use
1263 * g_list_free() to free the resources allocated by the returned list when
1264 * done using it
1265 *
1266 * Since: 1.4
1267 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1268 * #ClutterTransitionGroup instead
1269 */
1270 GList *
1271 clutter_state_get_states (ClutterState *state)
1272 {
1273 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
1274 return g_hash_table_get_keys (state->priv->states);
1275 }
1276
1277 /**
1278 * clutter_state_get_keys:
1279 * @state: a #ClutterState instance.
1280 * @source_state_name: (allow-none): the source transition name to query,
1281 * or %NULL for all source states
1282 * @target_state_name: (allow-none): the target transition name to query,
1283 * or %NULL for all target states
1284 * @object: (allow-none): the specific object instance to list keys for,
1285 * or %NULL for all managed objects
1286 * @property_name: (allow-none): the property name to search for, or %NULL
1287 * for all properties.
1288 *
1289 * Returns a list of pointers to opaque structures with accessor functions
1290 * that describe the keys added to an animator.
1291 *
1292 * Return value: (transfer container) (element-type Clutter.StateKey): a
1293 * newly allocated #GList of #ClutterStateKey<!-- -->s. The contents of
1294 * the returned list are owned by the #ClutterState and should not be
1295 * modified or freed. Use g_list_free() to free the resources allocated
1296 * by the returned list when done using it
1297 *
1298 * Since: 1.4
1299 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1300 * #ClutterTransitionGroup instead
1301 */
1302 GList *
1303 clutter_state_get_keys (ClutterState *state,
1304 const gchar *source_state_name,
1305 const gchar *target_state_name,
1306 GObject *object,
1307 const gchar *property_name)
1308 {
1309 GList *s, *state_list;
1310 GList *targets = NULL;
1311 State *source_state = NULL;
1312
1313 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
1314
1315 source_state_name = g_intern_string (source_state_name);
1316 target_state_name = g_intern_string (target_state_name);
1317 property_name = g_intern_string (property_name);
1318
1319 if (target_state_name != NULL)
1320 state_list = g_list_append (NULL, (gpointer) target_state_name);
1321 else
1322 state_list = clutter_state_get_states (state);
1323
1324 if (source_state_name)
1325 source_state = clutter_state_fetch_state (state, source_state_name, FALSE);
1326
1327 for (s = state_list; s != NULL; s = s->next)
1328 {
1329 State *target_state;
1330
1331 target_state = clutter_state_fetch_state (state, s->data, FALSE);
1332 if (target_state != NULL)
1333 {
1334 GList *k;
1335
1336 for (k = target_state->keys; k; k = k->next)
1337 {
1338 ClutterStateKey *key = k->data;
1339
1340 if ((object == NULL || (object == key->object)) &&
1341 (source_state_name == NULL ||
1342 source_state == key->source_state) &&
1343 (property_name == NULL ||
1344 (property_name == key->property_name)))
1345 {
1346 targets = g_list_prepend (targets, key);
1347 }
1348 }
1349 }
1350 }
1351
1352 g_list_free (state_list);
1353
1354 return g_list_reverse (targets);
1355 }
1356
1357
1358 /**
1359 * clutter_state_remove_key:
1360 * @state: a #ClutterState instance.
1361 * @source_state_name: (allow-none): the source state name to query,
1362 * or %NULL for all source states
1363 * @target_state_name: (allow-none): the target state name to query,
1364 * or %NULL for all target states
1365 * @object: (allow-none): the specific object instance to list keys for,
1366 * or %NULL for all managed objects
1367 * @property_name: (allow-none): the property name to search for,
1368 * or %NULL for all properties.
1369 *
1370 * Removes all keys matching the search criteria passed in arguments.
1371 *
1372 * Since: 1.4
1373 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1374 * #ClutterTransitionGroup instead
1375 */
1376 void
1377 clutter_state_remove_key (ClutterState *state,
1378 const gchar *source_state_name,
1379 const gchar *target_state_name,
1380 GObject *object,
1381 const gchar *property_name)
1382 {
1383 g_return_if_fail (CLUTTER_IS_STATE (state));
1384
1385 clutter_state_remove_key_internal (state,
1386 source_state_name, target_state_name,
1387 object, property_name,
1388 FALSE);
1389 }
1390
1391 /**
1392 * clutter_state_get_timeline:
1393 * @state: a #ClutterState
1394 *
1395 * Gets the timeline driving the #ClutterState
1396 *
1397 * Return value: (transfer none): the #ClutterTimeline that drives
1398 * the state change animations. The returned timeline is owned
1399 * by the #ClutterState and it should not be unreferenced directly
1400 *
1401 * Since: 1.4
1402 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1403 * #ClutterTransitionGroup instead
1404 */
1405 ClutterTimeline *
1406 clutter_state_get_timeline (ClutterState *state)
1407 {
1408 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
1409
1410 return state->priv->timeline;
1411 }
1412
1413
1414 static void
1415 clutter_state_set_property (GObject *object,
1416 guint prop_id,
1417 const GValue *value,
1418 GParamSpec *pspec)
1419 {
1420 ClutterState *state = CLUTTER_STATE (object);
1421
1422 switch (prop_id)
1423 {
1424 case PROP_STATE:
1425 clutter_state_set_state (state, g_value_get_string (value));
1426 break;
1427 case PROP_DURATION:
1428 state->priv->duration = g_value_get_uint (value);
1429 break;
1430 default:
1431 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1432 }
1433 }
1434
1435 static void
1436 clutter_state_get_property (GObject *object,
1437 guint prop_id,
1438 GValue *value,
1439 GParamSpec *pspec)
1440 {
1441 ClutterState *state = CLUTTER_STATE (object);
1442 switch (prop_id)
1443 {
1444 case PROP_STATE:
1445 g_value_set_string (value,
1446 clutter_state_get_state (state));
1447 break;
1448 case PROP_DURATION:
1449 g_value_set_uint (value, state->priv->duration);
1450 break;
1451 default:
1452 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
1453 }
1454 }
1455
1456 static void
1457 clutter_state_class_init (ClutterStateClass *klass)
1458 {
1459 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
1460 GParamSpec *pspec;
1461
1462 gobject_class->finalize = clutter_state_finalize;
1463 gobject_class->set_property = clutter_state_set_property;
1464 gobject_class->get_property = clutter_state_get_property;
1465
1466 /**
1467 * ClutterState::completed:
1468 * @state: the #ClutterState that emitted the signal
1469 *
1470 * The ::completed signal is emitted when a #ClutterState reaches
1471 * the target state specified by clutter_state_set_state() or
1472 * clutter_state_warp_to_state().
1473 *
1474 * Since: 1.4
1475 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1476 * #ClutterTransitionGroup instead
1477 */
1478 state_signals[COMPLETED] =
1479 g_signal_new (I_("completed"),
1480 G_TYPE_FROM_CLASS (gobject_class),
1481 G_SIGNAL_RUN_LAST,
1482 G_STRUCT_OFFSET (ClutterStateClass, completed),
1483 NULL, NULL,
1484 _clutter_marshal_VOID__VOID,
1485 G_TYPE_NONE, 0);
1486
1487 /**
1488 * ClutterState:state:
1489 *
1490 * The currently set target state, setting it causes the
1491 * state machine to transition to the new state, use
1492 * clutter_state_warp_to_state() to change state without
1493 * a transition.
1494 *
1495 * Since: 1.4
1496 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1497 * #ClutterTransitionGroup instead
1498 */
1499 pspec = g_param_spec_string ("state",
1500 P_("State"),
1501 P_("Currently set state, (transition to this state might not be complete)"),
1502 NULL,
1503 CLUTTER_PARAM_READWRITE);
1504 obj_props[PROP_STATE] = pspec;
1505 g_object_class_install_property (gobject_class, PROP_STATE, pspec);
1506
1507 /**
1508 * ClutterState:duration:
1509 *
1510 * Default duration used if an duration has not been specified for a specific
1511 * source/target state pair. The values is in milliseconds.
1512 *
1513 * Since: 1.4
1514 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1515 * #ClutterTransitionGroup instead
1516 */
1517 pspec = g_param_spec_uint ("duration",
1518 P_("Duration"),
1519 P_("Default transition duration"),
1520 0, 86400000, 1000,
1521 CLUTTER_PARAM_READWRITE);
1522 obj_props[PROP_DURATION] = pspec;
1523 g_object_class_install_property (gobject_class, PROP_DURATION, pspec);
1524 }
1525
1526 static void
1527 clutter_state_init (ClutterState *self)
1528 {
1529 ClutterStatePrivate *priv;
1530
1531 priv = self->priv = clutter_state_get_instance_private (self);
1532
1533 priv->states = g_hash_table_new_full (g_direct_hash, g_direct_equal,
1534 NULL,
1535 state_free);
1536
1537 self->priv->source_state_name = NULL;
1538 self->priv->target_state_name = NULL;
1539
1540 self->priv->duration = 1000;
1541
1542 priv->timeline = clutter_timeline_new (1000);
1543 g_signal_connect (priv->timeline, "new-frame",
1544 G_CALLBACK (clutter_state_new_frame),
1545 self);
1546 g_signal_connect (priv->timeline, "completed",
1547 G_CALLBACK (clutter_state_completed),
1548 self);
1549
1550 priv->slave_timeline = clutter_timeline_new (SLAVE_TIMELINE_LENGTH);
1551 }
1552
1553
1554 /**
1555 * clutter_state_get_animator:
1556 * @state: a #ClutterState instance.
1557 * @source_state_name: the name of a source state
1558 * @target_state_name: the name of a target state
1559 *
1560 * Retrieves the #ClutterAnimator that is being used for transitioning
1561 * between the two states, if any has been set
1562 *
1563 * Return value: (transfer none): a #ClutterAnimator instance, or %NULL
1564 *
1565 * Since: 1.4
1566 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1567 * #ClutterTransitionGroup instead
1568 */
1569 ClutterAnimator *
1570 clutter_state_get_animator (ClutterState *state,
1571 const gchar *source_state_name,
1572 const gchar *target_state_name)
1573 {
1574 State *target_state;
1575 guint i;
1576
1577 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
1578
1579 source_state_name = g_intern_string (source_state_name);
1580 if (source_state_name == g_intern_static_string (""))
1581 source_state_name = NULL;
1582
1583 target_state_name = g_intern_string (target_state_name);
1584
1585 target_state = clutter_state_fetch_state (state, target_state_name, FALSE);
1586 if (target_state == NULL)
1587 return NULL;
1588
1589 for (i = 0; i < target_state->animators->len; i++)
1590 {
1591 const StateAnimator *animator;
1592
1593 animator = &g_array_index (target_state->animators, StateAnimator, i);
1594 if (animator->source_state_name == source_state_name)
1595 return animator->animator;
1596 }
1597
1598 return NULL;
1599 }
1600
1601 /**
1602 * clutter_state_set_animator:
1603 * @state: a #ClutterState instance.
1604 * @source_state_name: the name of a source state
1605 * @target_state_name: the name of a target state
1606 * @animator: (allow-none): a #ClutterAnimator instance, or %NULL to
1607 * unset an existing #ClutterAnimator
1608 *
1609 * Specifies a #ClutterAnimator to be used when transitioning between
1610 * the two named states.
1611 *
1612 * The @animator allows specifying a transition between the state that is
1613 * more elaborate than the basic transitions allowed by the tweening of
1614 * properties defined in the #ClutterState keys.
1615 *
1616 * If @animator is %NULL it will unset an existing animator.
1617 *
1618 * #ClutterState will take a reference on the passed @animator, if any
1619 *
1620 * Since: 1.4
1621 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1622 * #ClutterTransitionGroup instead
1623 */
1624 void
1625 clutter_state_set_animator (ClutterState *state,
1626 const gchar *source_state_name,
1627 const gchar *target_state_name,
1628 ClutterAnimator *animator)
1629 {
1630 State *target_state;
1631 guint i;
1632
1633 g_return_if_fail (CLUTTER_IS_STATE (state));
1634
1635 source_state_name = g_intern_string (source_state_name);
1636 target_state_name = g_intern_string (target_state_name);
1637
1638 target_state = clutter_state_fetch_state (state, target_state_name, TRUE);
1639 if (target_state == NULL)
1640 return;
1641
1642 for (i = 0; target_state->animators->len; i++)
1643 {
1644 StateAnimator *a;
1645
1646 a = &g_array_index (target_state->animators, StateAnimator, i);
1647 if (a->source_state_name == source_state_name)
1648 {
1649 g_object_unref (a->animator);
1650
1651 if (animator != NULL)
1652 a->animator = g_object_ref (animator);
1653 else
1654 {
1655 /* remove the matched animator if passed NULL */
1656 g_array_remove_index (target_state->animators, i);
1657 }
1658
1659 return;
1660 }
1661 }
1662
1663 if (animator != NULL)
1664 {
1665 StateAnimator state_animator = {
1666 source_state_name,
1667 g_object_ref (animator)
1668 };
1669
1670 g_array_append_val (target_state->animators, state_animator);
1671 }
1672 }
1673
1674 static gpointer
1675 clutter_state_key_copy (gpointer boxed)
1676 {
1677 if (boxed != NULL)
1678 {
1679 ClutterStateKey *key = boxed;
1680
1681 key->ref_count += 1;
1682 }
1683
1684 return boxed;
1685 }
1686
1687 G_DEFINE_BOXED_TYPE (ClutterStateKey, clutter_state_key,
1688 clutter_state_key_copy,
1689 clutter_state_key_free);
1690
1691 /**
1692 * clutter_state_key_get_pre_delay:
1693 * @state_key: a #ClutterStateKey
1694 *
1695 * Retrieves the pause before transitioning starts as a fraction of
1696 * the total transition time.
1697 *
1698 * Return value: the pre delay used before starting the transition.
1699 *
1700 * Since: 1.4
1701 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1702 * #ClutterTransitionGroup instead
1703 */
1704 gdouble
1705 clutter_state_key_get_pre_delay (const ClutterStateKey *state_key)
1706 {
1707 g_return_val_if_fail (state_key != NULL, 0.0);
1708
1709 return state_key->pre_delay;
1710 }
1711
1712 /**
1713 * clutter_state_key_get_post_delay:
1714 * @state_key: a #ClutterStateKey
1715 *
1716 * Retrieves the duration of the pause after transitioning is complete
1717 * as a fraction of the total transition time.
1718 *
1719 * Return value: the post delay, used after doing the transition.
1720 *
1721 * Since: 1.4
1722 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1723 * #ClutterTransitionGroup instead
1724 */
1725 gdouble
1726 clutter_state_key_get_post_delay (const ClutterStateKey *state_key)
1727 {
1728 g_return_val_if_fail (state_key != NULL, 0.0);
1729
1730 return state_key->post_delay;
1731 }
1732
1733 /**
1734 * clutter_state_key_get_mode:
1735 * @state_key: a #ClutterStateKey
1736 *
1737 * Retrieves the easing mode used for @state_key.
1738 *
1739 * Return value: the mode of a #ClutterStateKey
1740 *
1741 * Since: 1.4
1742 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1743 * #ClutterTransitionGroup instead
1744 */
1745 gulong
1746 clutter_state_key_get_mode (const ClutterStateKey *state_key)
1747 {
1748 g_return_val_if_fail (state_key != NULL, 0);
1749
1750 return state_key->mode;
1751 }
1752
1753 /**
1754 * clutter_state_key_get_value:
1755 * @state_key: a #ClutterStateKey
1756 * @value: a #GValue initialized with the correct type for the @state_key
1757 *
1758 * Retrieves a copy of the value for a #ClutterStateKey.
1759 *
1760 * The #GValue needs to be already initialized for the value type
1761 * of the property or to a type that allow transformation from the value
1762 * type of the key.
1763 *
1764 * Use g_value_unset() when done.
1765 *
1766 * Return value: %TRUE if the value was successfully retrieved,
1767 * and %FALSE otherwise
1768 *
1769 * Since: 1.4
1770 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1771 * #ClutterTransitionGroup instead
1772 */
1773 gboolean
1774 clutter_state_key_get_value (const ClutterStateKey *state_key,
1775 GValue *value)
1776 {
1777 g_return_val_if_fail (state_key != NULL, FALSE);
1778 g_return_val_if_fail (value != NULL, FALSE);
1779 g_return_val_if_fail (G_VALUE_TYPE (value) != G_TYPE_INVALID, FALSE);
1780
1781 if (!g_type_is_a (G_VALUE_TYPE (&state_key->value), G_VALUE_TYPE (value)))
1782 {
1783 if (g_value_type_compatible (G_VALUE_TYPE (&state_key->value),
1784 G_VALUE_TYPE (value)))
1785 {
1786 g_value_copy (&state_key->value, value);
1787 return TRUE;
1788 }
1789
1790 if (g_value_type_transformable (G_VALUE_TYPE (&state_key->value),
1791 G_VALUE_TYPE (value)))
1792 {
1793 if (g_value_transform (&state_key->value, value))
1794 return TRUE;
1795 }
1796
1797 g_warning ("%s: Unable to convert from %s to %s for the "
1798 "property '%s' of object %s in the state key",
1799 G_STRLOC,
1800 g_type_name (G_VALUE_TYPE (&state_key->value)),
1801 g_type_name (G_VALUE_TYPE (value)),
1802 state_key->property_name,
1803 G_OBJECT_TYPE_NAME (state_key->object));
1804
1805 return FALSE;
1806 }
1807 else
1808 g_value_copy (&state_key->value, value);
1809
1810 return TRUE;
1811 }
1812
1813 /**
1814 * clutter_state_key_get_object:
1815 * @state_key: a #ClutterStateKey
1816 *
1817 * Retrieves the object instance this #ClutterStateKey applies to.
1818 *
1819 * Return value: (transfer none): the object this state key applies to.
1820 *
1821 * Since: 1.4
1822 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1823 * #ClutterTransitionGroup instead
1824 */
1825 GObject *
1826 clutter_state_key_get_object (const ClutterStateKey *state_key)
1827 {
1828 g_return_val_if_fail (state_key, NULL);
1829
1830 return state_key->object;
1831 }
1832
1833 /**
1834 * clutter_state_key_get_property_name:
1835 * @state_key: a #ClutterStateKey
1836 *
1837 * Retrieves the name of the property this #ClutterStateKey applies to
1838 *
1839 * Return value: the name of the property. The returned string is owned
1840 * by the #ClutterStateKey and should never be modified or freed
1841 *
1842 * Since: 1.4
1843 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1844 * #ClutterTransitionGroup instead
1845 */
1846 const gchar *
1847 clutter_state_key_get_property_name (const ClutterStateKey *state_key)
1848 {
1849 g_return_val_if_fail (state_key, NULL);
1850
1851 return state_key->property_name;
1852 }
1853
1854 /**
1855 * clutter_state_key_get_source_state_name:
1856 * @state_key: a #ClutterStateKey
1857 *
1858 * Retrieves the name of the source state of the @state_key
1859 *
1860 * Return value: the name of the source state for this key, or %NULL
1861 * if this is the generic state key for the given property when
1862 * transitioning to the target state. The returned string is owned
1863 * by the #ClutterStateKey and should never be modified or freed
1864 *
1865 * Since: 1.4
1866 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1867 * #ClutterTransitionGroup instead
1868 */
1869 const gchar *
1870 clutter_state_key_get_source_state_name (const ClutterStateKey *state_key)
1871 {
1872 g_return_val_if_fail (state_key, NULL);
1873
1874 if (state_key->source_state != NULL)
1875 return state_key->source_state->name;
1876
1877 return NULL;
1878 }
1879
1880 /**
1881 * clutter_state_key_get_target_state_name:
1882 * @state_key: a #ClutterStateKey
1883 *
1884 * Get the name of the source state this #ClutterStateKey contains,
1885 * or NULL if this is the generic state key for the given property
1886 * when transitioning to the target state.
1887 *
1888 * Return value: the name of the source state for this key, or NULL if
1889 * the key is generic
1890 *
1891 * Since: 1.4
1892 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1893 * #ClutterTransitionGroup instead
1894 */
1895 const gchar *
1896 clutter_state_key_get_target_state_name (const ClutterStateKey *state_key)
1897 {
1898 g_return_val_if_fail (state_key, NULL);
1899
1900 return state_key->target_state->name;
1901 }
1902
1903 /**
1904 * clutter_state_key_get_property_type:
1905 * @key: a #ClutterStateKey
1906 *
1907 * Retrieves the #GType of the property a key applies to
1908 *
1909 * You can use this type to initialize the #GValue to pass to
1910 * clutter_state_key_get_value()
1911 *
1912 * Return value: the #GType of the property
1913 *
1914 * Since: 1.4
1915 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1916 * #ClutterTransitionGroup instead
1917 */
1918 GType
1919 clutter_state_key_get_property_type (const ClutterStateKey *key)
1920 {
1921 g_return_val_if_fail (key != NULL, G_TYPE_INVALID);
1922
1923 return G_VALUE_TYPE (&key->value);
1924 }
1925
1926
1927 /**
1928 * clutter_state_set_duration:
1929 * @state: a #ClutterState
1930 * @source_state_name: (allow-none): the name of the source state, or %NULL
1931 * @target_state_name: (allow-none): the name of the target state, or %NULL
1932 * @duration: the duration of the transition, in milliseconds
1933 *
1934 * Sets the duration of a transition.
1935 *
1936 * If both state names are %NULL the default duration for @state is set.
1937 *
1938 * If only @target_state_name is specified, the passed @duration becomes
1939 * the default duration for transitions to the target state.
1940 *
1941 * If both states names are specified, the passed @duration only applies
1942 * to the specified transition.
1943 *
1944 * Since: 1.4
1945 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
1946 * #ClutterTransitionGroup instead
1947 */
1948 void
1949 clutter_state_set_duration (ClutterState *state,
1950 const gchar *source_state_name,
1951 const gchar *target_state_name,
1952 guint duration)
1953 {
1954 State *target_state;
1955
1956 g_return_if_fail (CLUTTER_IS_STATE (state));
1957
1958 source_state_name = g_intern_string (source_state_name);
1959 if (source_state_name == g_intern_static_string (""))
1960 source_state_name = NULL;
1961
1962 target_state_name = g_intern_string (target_state_name);
1963 if (target_state_name == g_intern_static_string (""))
1964 target_state_name = NULL;
1965
1966 if (target_state_name == NULL)
1967 {
1968 state->priv->duration = duration;
1969 return;
1970 }
1971
1972 target_state = clutter_state_fetch_state (state, target_state_name, FALSE);
1973 if (target_state != NULL)
1974 {
1975 if (source_state_name != NULL)
1976 g_hash_table_insert (target_state->durations,
1977 (gpointer) source_state_name,
1978 GINT_TO_POINTER (duration));
1979 else
1980 g_hash_table_insert (target_state->durations,
1981 NULL,
1982 GINT_TO_POINTER (duration));
1983 }
1984 }
1985
1986 /**
1987 * clutter_state_get_duration:
1988 * @state: a #ClutterState
1989 * @source_state_name: (allow-none): the name of the source state to
1990 * get the duration of, or %NULL
1991 * @target_state_name: (allow-none): the name of the source state to
1992 * get the duration of, or %NULL
1993 *
1994 * Queries the duration used for transitions between a source and
1995 * target state pair
1996 *
1997 * The semantics for the query are the same as the semantics used for
1998 * setting the duration with clutter_state_set_duration()
1999 *
2000 * Return value: the duration, in milliseconds
2001 *
2002 * Since: 1.4
2003 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
2004 * #ClutterTransitionGroup instead
2005 */
2006 guint
2007 clutter_state_get_duration (ClutterState *state,
2008 const gchar *source_state_name,
2009 const gchar *target_state_name)
2010 {
2011 State *target_state;
2012 guint ret = 0;
2013
2014 g_return_val_if_fail (CLUTTER_IS_STATE (state), 0);
2015
2016 source_state_name = g_intern_string (source_state_name);
2017 if (source_state_name == g_intern_static_string (""))
2018 source_state_name = NULL;
2019
2020 target_state_name = g_intern_string (target_state_name);
2021 if (target_state_name == g_intern_static_string (""))
2022 target_state_name = NULL;
2023
2024 if (target_state_name == NULL)
2025 return state->priv->duration;
2026
2027 target_state = clutter_state_fetch_state (state, target_state_name, FALSE);
2028 if (target_state != NULL)
2029 {
2030 if (source_state_name)
2031 {
2032 ret = GPOINTER_TO_INT (g_hash_table_lookup (target_state->durations,
2033 source_state_name));
2034 if(!ret)
2035 ret = GPOINTER_TO_INT (g_hash_table_lookup (target_state->durations,
2036 NULL));
2037 }
2038 else
2039 ret = GPOINTER_TO_INT (g_hash_table_lookup (target_state->durations,
2040 NULL));
2041 }
2042
2043 if (!ret)
2044 ret = state->priv->duration;
2045
2046 return ret;
2047 }
2048
2049 /**
2050 * clutter_state_get_state:
2051 * @state: a #ClutterState
2052 *
2053 * Queries the currently set target state.
2054 *
2055 * During a transition this function will return the target of the transition.
2056 *
2057 * This function is useful when called from handlers of the
2058 * #ClutterState::completed signal.
2059 *
2060 * Return value: a string containing the target state. The returned string
2061 * is owned by the #ClutterState and should not be modified or freed
2062 *
2063 * Since: 1.4
2064 * Deprecated: 1.12: Use #ClutterKeyframeTransition and
2065 * #ClutterTransitionGroup instead
2066 */
2067 const gchar *
2068 clutter_state_get_state (ClutterState *state)
2069 {
2070 g_return_val_if_fail (CLUTTER_IS_STATE (state), NULL);
2071
2072 return state->priv->target_state_name;
2073 }
2074
2075 typedef struct _ParseClosure {
2076 ClutterState *state;
2077 ClutterScript *script;
2078
2079 GValue *value;
2080
2081 gboolean result;
2082 } ParseClosure;
2083
2084 static void
2085 parse_state_transition (JsonArray *array,
2086 guint index_,
2087 JsonNode *element,
2088 gpointer data)
2089 {
2090 ParseClosure *clos = data;
2091 JsonObject *object;
2092 const gchar *source_name, *target_name;
2093 State *source_state, *target_state;
2094 JsonArray *keys;
2095 GSList *valid_keys = NULL;
2096 GList *array_keys, *k;
2097
2098 if (JSON_NODE_TYPE (element) != JSON_NODE_OBJECT)
2099 {
2100 g_warning ("The 'transitions' member of a ClutterState description "
2101 "should be an array of objects, but the element %d of the "
2102 "array is of type '%s'. The element will be ignored.",
2103 index_,
2104 json_node_type_name (element));
2105 return;
2106 }
2107
2108 object = json_node_get_object (element);
2109
2110 if (!json_object_has_member (object, "source") ||
2111 !json_object_has_member (object, "target") ||
2112 !(json_object_has_member (object, "keys") ||
2113 json_object_has_member (object, "animator")))
2114 {
2115 g_warning ("The transition description at index %d is missing one "
2116 "of the mandatory members: source, target and keys or "
2117 "animator", index_);
2118 return;
2119 }
2120
2121 source_name = json_object_get_string_member (object, "source");
2122 source_state = clutter_state_fetch_state (clos->state, source_name, TRUE);
2123
2124 target_name = json_object_get_string_member (object, "target");
2125 target_state = clutter_state_fetch_state (clos->state, target_name, TRUE);
2126
2127 if (json_object_has_member (object, "duration"))
2128 {
2129 guint duration = json_object_get_int_member (object, "duration");
2130
2131 clutter_state_set_duration (clos->state,
2132 source_name, target_name,
2133 duration);
2134 }
2135
2136 if (json_object_has_member (object, "animator"))
2137 {
2138 const gchar *id_ = json_object_get_string_member (object, "animator");
2139 GObject *animator;
2140
2141 animator = clutter_script_get_object (clos->script, id_);
2142 if (animator == NULL)
2143 {
2144 g_warning ("No object with id '%s' has been defined.", id_);
2145 return;
2146 }
2147
2148 clutter_state_set_animator (clos->state,
2149 source_name,
2150 target_name,
2151 CLUTTER_ANIMATOR (animator));
2152 }
2153
2154 if (!json_object_has_member (object, "keys"))
2155 return;
2156
2157 keys = json_object_get_array_member (object, "keys");
2158 if (keys == NULL && !json_object_has_member (object, "animator"))
2159 {
2160 g_warning ("The transition description at index %d has an invalid "
2161 "key member of type '%s' when an array was expected.",
2162 index_,
2163 json_node_type_name (json_object_get_member (object, "keys")));
2164 return;
2165 }
2166
2167 if (G_IS_VALUE (clos->value))
2168 valid_keys = g_slist_reverse (g_value_get_pointer (clos->value));
2169 else
2170 g_value_init (clos->value, G_TYPE_POINTER);
2171
2172 array_keys = json_array_get_elements (keys);
2173 for (k = array_keys; k != NULL; k = k->next)
2174 {
2175 JsonNode *node = k->data;
2176 JsonArray *key = json_node_get_array (node);
2177 ClutterStateKey *state_key;
2178 GObject *gobject;
2179 GParamSpec *pspec;
2180 const gchar *id_;
2181 const gchar *property;
2182 gulong mode;
2183 gboolean res;
2184
2185 id_ = json_array_get_string_element (key, 0);
2186 gobject = clutter_script_get_object (clos->script, id_);
2187 if (gobject == NULL)
2188 {
2189 g_warning ("No object with id '%s' has been defined.", id_);
2190 continue;
2191 }
2192
2193 property = json_array_get_string_element (key, 1);
2194 pspec = get_property_from_object (gobject, property);
2195 if (pspec == NULL)
2196 {
2197 g_warning ("The object of type '%s' and name '%s' has no "
2198 "property named '%s'.",
2199 G_OBJECT_TYPE_NAME (gobject),
2200 id_,
2201 property);
2202 continue;
2203 }
2204
2205 mode = _clutter_script_resolve_animation_mode (json_array_get_element (key, 2));
2206
2207 state_key = clutter_state_key_new (target_state,
2208 gobject, property, pspec,
2209 mode);
2210
2211 res = _clutter_script_parse_node (clos->script,
2212 &(state_key->value),
2213 property,
2214 json_array_get_element (key, 3),
2215 pspec);
2216 if (!res)
2217 {
2218 g_warning ("Unable to parse the key value for the "
2219 "property '%s' of object '%s' at index %d",
2220 property,
2221 id_,
2222 index_);
2223 clutter_state_key_free (state_key);
2224 continue;
2225 }
2226
2227 switch (json_array_get_length (key))
2228 {
2229 case 5:
2230 state_key->pre_delay = json_array_get_double_element (key, 4);
2231 state_key->post_delay = 0.0;
2232 break;
2233
2234 case 6:
2235 state_key->pre_delay = json_array_get_double_element (key, 4);
2236 state_key->post_delay = json_array_get_double_element (key, 5);
2237 break;
2238
2239 default:
2240 state_key->pre_delay = 0.0;
2241 state_key->post_delay = 0.0;
2242 break;
2243 }
2244
2245 state_key->source_state = source_state;
2246
2247 valid_keys = g_slist_prepend (valid_keys, state_key);
2248 }
2249
2250 g_list_free (array_keys);
2251
2252 g_value_set_pointer (clos->value, g_slist_reverse (valid_keys));
2253
2254 clos->result = TRUE;
2255 }
2256
2257 static gboolean
2258 clutter_state_parse_custom_node (ClutterScriptable *scriptable,
2259 ClutterScript *script,
2260 GValue *value,
2261 const gchar *name,
2262 JsonNode *node)
2263 {
2264 ParseClosure clos;
2265
2266 if (strcmp (name, "transitions") != 0)
2267 return FALSE;
2268
2269 if (JSON_NODE_TYPE (node) != JSON_NODE_ARRAY)
2270 return FALSE;
2271
2272 clos.state = CLUTTER_STATE (scriptable);
2273 clos.script = script;
2274 clos.value = value;
2275 clos.result = FALSE;
2276
2277 json_array_foreach_element (json_node_get_array (node),
2278 parse_state_transition,
2279 &clos);
2280
2281 return clos.result;
2282 }
2283
2284 static void
2285 clutter_state_set_custom_property (ClutterScriptable *scriptable,
2286 ClutterScript *script,
2287 const gchar *name,
2288 const GValue *value)
2289 {
2290 if (strcmp (name, "transitions") == 0)
2291 {
2292 ClutterState *state = CLUTTER_STATE (scriptable);
2293 GSList *keys = g_value_get_pointer (value);
2294 GSList *k;
2295
2296 for (k = keys; k != NULL; k = k->next)
2297 clutter_state_set_key_internal (state, k->data);
2298
2299 g_slist_free (keys);
2300 }
2301 else
2302 g_object_set_property (G_OBJECT (scriptable), name, value);
2303 }
2304
2305 static void
2306 clutter_scriptable_iface_init (ClutterScriptableIface *iface)
2307 {
2308 iface->parse_custom_node = clutter_state_parse_custom_node;
2309 iface->set_custom_property = clutter_state_set_custom_property;
2310 }