Debian Codegraph @

clutter/deprecated/clutter-score.c

raw
1 /*
2 * Clutter.
3 *
4 * An OpenGL based 'interactive canvas' library.
5 *
6 * Authored By Matthew Allum <[email protected]>
7 *
8 * Copyright (C) 2007 OpenedHand
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
26 /**
27 * SECTION:clutter-score
28 * @short_description: Controller for multiple timelines
29 *
30 * #ClutterScore is a base class for sequencing multiple timelines in order.
31 * Using #ClutterScore it is possible to start multiple timelines at the
32 * same time or launch multiple timelines when a particular timeline has
33 * emitted the ClutterTimeline::completed signal.
34 *
35 * Each time a #ClutterTimeline is started and completed, a signal will be
36 * emitted.
37 *
38 * For example, this code will start two #ClutterTimeline<!-- -->s after
39 * a third timeline terminates:
40 *
41 * |[
42 * ClutterTimeline *timeline_1, *timeline_2, *timeline_3;
43 * ClutterScore *score;
44 *
45 * timeline_1 = clutter_timeline_new_for_duration (1000);
46 * timeline_2 = clutter_timeline_new_for_duration (500);
47 * timeline_3 = clutter_timeline_new_for_duration (500);
48 *
49 * score = clutter_score_new ();
50 *
51 * clutter_score_append (score, NULL, timeline_1);
52 * clutter_score_append (score, timeline_1, timeline_2);
53 * clutter_score_append (score, timeline_1, timeline_3);
54 *
55 * clutter_score_start (score);
56 * ]|
57 *
58 * A #ClutterScore takes a reference on the timelines it manages,
59 * so timelines can be safely unreferenced after being appended.
60 *
61 * New timelines can be appended to the #ClutterScore using
62 * clutter_score_append() and removed using clutter_score_remove().
63 *
64 * Timelines can also be appended to a specific marker on the
65 * parent timeline, using clutter_score_append_at_marker().
66 *
67 * The score can be cleared using clutter_score_remove_all().
68 *
69 * The list of timelines can be retrieved using
70 * clutter_score_list_timelines().
71 *
72 * The score state is controlled using clutter_score_start(),
73 * clutter_score_pause(), clutter_score_stop() and clutter_score_rewind().
74 * The state can be queried using clutter_score_is_playing().
75 *
76 * #ClutterScore is available since Clutter 0.6
77 *
78 * Deprecated: 1.8: Use #ClutterAnimator or #ClutterState to create
79 * complex animations involving multiple timelines.
80 */
81
82 #ifdef HAVE_CONFIG_H
83 #include "config.h"
84 #endif
85
86 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
87
88 #include "clutter-score.h"
89 #include "clutter-main.h"
90 #include "clutter-marshal.h"
91 #include "clutter-private.h"
92 #include "clutter-debug.h"
93
94 typedef struct _ClutterScoreEntry ClutterScoreEntry;
95
96 struct _ClutterScoreEntry
97 {
98 /* the entry unique id */
99 gulong id;
100
101 ClutterTimeline *timeline;
102 ClutterTimeline *parent;
103
104 /* the optional marker on the parent */
105 gchar *marker;
106
107 /* signal handlers id */
108 gulong complete_id;
109 gulong marker_id;
110
111 ClutterScore *score;
112
113 /* pointer back to the tree structure */
114 GNode *node;
115 };
116
117 struct _ClutterScorePrivate
118 {
119 GNode *root;
120
121 GHashTable *running_timelines;
122
123 gulong last_id;
124
125 guint is_paused : 1;
126 guint loop : 1;
127 };
128
129 enum
130 {
131 PROP_0,
132
133 PROP_LOOP
134 };
135
136 enum
137 {
138 TIMELINE_STARTED,
139 TIMELINE_COMPLETED,
140
141 STARTED,
142 PAUSED,
143 COMPLETED,
144
145 LAST_SIGNAL
146 };
147
148 static inline void clutter_score_clear (ClutterScore *score);
149
150 G_DEFINE_TYPE_WITH_PRIVATE (ClutterScore, clutter_score, G_TYPE_OBJECT)
151
152 static int score_signals[LAST_SIGNAL] = { 0 };
153
154 /* Object */
155
156 static void
157 clutter_score_set_property (GObject *gobject,
158 guint prop_id,
159 const GValue *value,
160 GParamSpec *pspec)
161 {
162 ClutterScorePrivate *priv;
163
164 priv = clutter_score_get_instance_private (CLUTTER_SCORE (gobject));
165
166 switch (prop_id)
167 {
168 case PROP_LOOP:
169 priv->loop = g_value_get_boolean (value);
170 break;
171 default:
172 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
173 break;
174 }
175 }
176
177 static void
178 clutter_score_get_property (GObject *gobject,
179 guint prop_id,
180 GValue *value,
181 GParamSpec *pspec)
182 {
183 ClutterScorePrivate *priv;
184
185 priv = clutter_score_get_instance_private (CLUTTER_SCORE (gobject));
186
187 switch (prop_id)
188 {
189 case PROP_LOOP:
190 g_value_set_boolean (value, priv->loop);
191 break;
192 default:
193 G_OBJECT_WARN_INVALID_PROPERTY_ID (gobject, prop_id, pspec);
194 break;
195 }
196 }
197
198 static void
199 clutter_score_finalize (GObject *object)
200 {
201 ClutterScore *score = CLUTTER_SCORE (object);
202
203 clutter_score_stop (score);
204 clutter_score_clear (score);
205
206 G_OBJECT_CLASS (clutter_score_parent_class)->finalize (object);
207 }
208
209 static void
210 clutter_score_class_init (ClutterScoreClass *klass)
211 {
212 GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
213
214 gobject_class->set_property = clutter_score_set_property;
215 gobject_class->get_property = clutter_score_get_property;
216 gobject_class->finalize = clutter_score_finalize;
217
218 /**
219 * ClutterScore:loop:
220 *
221 * Whether the #ClutterScore should restart once finished.
222 *
223 * Since: 0.6
224 * Deprecated: 1.8
225 */
226 g_object_class_install_property (gobject_class,
227 PROP_LOOP,
228 g_param_spec_boolean ("loop",
229 "Loop",
230 "Whether the score should restart once finished",
231 FALSE,
232 CLUTTER_PARAM_READWRITE));
233
234 /**
235 * ClutterScore::timeline-started:
236 * @score: the score which received the signal
237 * @timeline: the current timeline
238 *
239 * The ::timeline-started signal is emitted each time a new timeline
240 * inside a #ClutterScore starts playing.
241 *
242 * Since: 0.6
243 * Deprecated: 1.8
244 */
245 score_signals[TIMELINE_STARTED] =
246 g_signal_new ("timeline-started",
247 G_TYPE_FROM_CLASS (gobject_class),
248 G_SIGNAL_RUN_LAST,
249 G_STRUCT_OFFSET (ClutterScoreClass, timeline_started),
250 NULL, NULL,
251 _clutter_marshal_VOID__OBJECT,
252 G_TYPE_NONE,
253 1, CLUTTER_TYPE_TIMELINE);
254 /**
255 * ClutterScore::timeline-completed:
256 * @score: the score which received the signal
257 * @timeline: the completed timeline
258 *
259 * The ::timeline-completed signal is emitted each time a timeline
260 * inside a #ClutterScore terminates.
261 *
262 * Since: 0.6
263 * Deprecated: 1.8
264 */
265 score_signals[TIMELINE_COMPLETED] =
266 g_signal_new ("timeline-completed",
267 G_TYPE_FROM_CLASS (gobject_class),
268 G_SIGNAL_RUN_LAST,
269 G_STRUCT_OFFSET (ClutterScoreClass, timeline_completed),
270 NULL, NULL,
271 _clutter_marshal_VOID__OBJECT,
272 G_TYPE_NONE, 1,
273 CLUTTER_TYPE_TIMELINE);
274 /**
275 * ClutterScore::completed:
276 * @score: the score which received the signal
277 *
278 * The ::completed signal is emitted each time a #ClutterScore terminates.
279 *
280 * Since: 0.6
281 * Deprecated: 1.8
282 */
283 score_signals[COMPLETED] =
284 g_signal_new ("completed",
285 G_TYPE_FROM_CLASS (gobject_class),
286 G_SIGNAL_RUN_LAST,
287 G_STRUCT_OFFSET (ClutterScoreClass, completed),
288 NULL, NULL,
289 _clutter_marshal_VOID__VOID,
290 G_TYPE_NONE, 0);
291 /**
292 * ClutterScore::started:
293 * @score: the score which received the signal
294 *
295 * The ::started signal is emitted each time a #ClutterScore starts playing.
296 *
297 * Since: 0.6
298 * Deprecated: 1.8
299 */
300 score_signals[STARTED] =
301 g_signal_new ("started",
302 G_TYPE_FROM_CLASS (gobject_class),
303 G_SIGNAL_RUN_LAST,
304 G_STRUCT_OFFSET (ClutterScoreClass, started),
305 NULL, NULL,
306 _clutter_marshal_VOID__VOID,
307 G_TYPE_NONE, 0);
308 /**
309 * ClutterScore::paused:
310 * @score: the score which received the signal
311 *
312 * The ::paused signal is emitted each time a #ClutterScore
313 * is paused.
314 *
315 * Since: 0.6
316 * Deprecated: 1.8
317 */
318 score_signals[PAUSED] =
319 g_signal_new ("paused",
320 G_TYPE_FROM_CLASS (gobject_class),
321 G_SIGNAL_RUN_LAST,
322 G_STRUCT_OFFSET (ClutterScoreClass, paused),
323 NULL, NULL,
324 _clutter_marshal_VOID__VOID,
325 G_TYPE_NONE, 0);
326 }
327
328 static void
329 clutter_score_init (ClutterScore *self)
330 {
331 ClutterScorePrivate *priv;
332
333 self->priv = priv = clutter_score_get_instance_private (self);
334
335 /* sentinel */
336 priv->root = g_node_new (NULL);
337
338 priv->running_timelines = NULL;
339
340 priv->is_paused = FALSE;
341 priv->loop = FALSE;
342
343 priv->last_id = 1;
344 }
345
346 /**
347 * clutter_score_new:
348 *
349 * Creates a new #ClutterScore. A #ClutterScore is an object that can
350 * hold multiple #ClutterTimeline<!-- -->s in a sequential order.
351 *
352 * Return value: the newly created #ClutterScore. Use g_object_unref()
353 * when done.
354 *
355 * Since: 0.6
356 * Deprecated: 1.8
357 */
358 ClutterScore *
359 clutter_score_new (void)
360 {
361 return g_object_new (CLUTTER_TYPE_SCORE, NULL);
362 }
363
364 /**
365 * clutter_score_set_loop:
366 * @score: a #ClutterScore
367 * @loop: %TRUE for enable looping
368 *
369 * Sets whether @score should loop. A looping #ClutterScore will start
370 * from its initial state after the ::complete signal has been fired.
371 *
372 * Since: 0.6
373 * Deprecated: 1.8
374 */
375 void
376 clutter_score_set_loop (ClutterScore *score,
377 gboolean loop)
378 {
379 g_return_if_fail (CLUTTER_IS_SCORE (score));
380
381 if (score->priv->loop != loop)
382 {
383 score->priv->loop = loop;
384
385 g_object_notify (G_OBJECT (score), "loop");
386 }
387 }
388
389 /**
390 * clutter_score_get_loop:
391 * @score: a #ClutterScore
392 *
393 * Gets whether @score is looping
394 *
395 * Return value: %TRUE if the score is looping
396 *
397 * Since: 0.6
398 * Deprecated: 1.8
399 */
400 gboolean
401 clutter_score_get_loop (ClutterScore *score)
402 {
403 g_return_val_if_fail (CLUTTER_IS_SCORE (score), FALSE);
404
405 return score->priv->loop;
406 }
407
408 /**
409 * clutter_score_is_playing:
410 * @score: A #ClutterScore
411 *
412 * Query state of a #ClutterScore instance.
413 *
414 * Return Value: %TRUE if score is currently playing
415 *
416 * Since: 0.6
417 * Deprecated: 1.8
418 */
419 gboolean
420 clutter_score_is_playing (ClutterScore *score)
421 {
422 g_return_val_if_fail (CLUTTER_IS_SCORE (score), FALSE);
423
424 if (score->priv->is_paused)
425 return FALSE;
426
427 return score->priv->running_timelines
428 && g_hash_table_size (score->priv->running_timelines) != 0;
429 }
430
431 /* destroy_entry:
432 * @node: a #GNode
433 *
434 * Frees the #ClutterScoreEntry attached to @node.
435 */
436 static gboolean
437 destroy_entry (GNode *node,
438 G_GNUC_UNUSED gpointer data)
439 {
440 ClutterScoreEntry *entry = node->data;
441
442 if (G_LIKELY (entry != NULL))
443 {
444 if (entry->marker_id)
445 {
446 g_signal_handler_disconnect (entry->parent, entry->marker_id);
447 entry->marker_id = 0;
448 }
449
450 if (entry->complete_id)
451 {
452 g_signal_handler_disconnect (entry->timeline, entry->complete_id);
453 entry->complete_id = 0;
454 }
455
456 g_object_unref (entry->timeline);
457 g_free (entry->marker);
458 g_slice_free (ClutterScoreEntry, entry);
459
460 node->data = NULL;
461 }
462
463 /* continue */
464 return FALSE;
465 }
466
467 typedef enum {
468 FIND_BY_TIMELINE,
469 FIND_BY_ID,
470 REMOVE_BY_ID,
471 LIST_TIMELINES
472 } TraverseAction;
473
474 typedef struct {
475 TraverseAction action;
476
477 ClutterScore *score;
478
479 /* parameters */
480 union {
481 ClutterTimeline *timeline;
482 gulong id;
483 ClutterScoreEntry *entry;
484 } d;
485
486 gpointer result;
487 } TraverseClosure;
488
489 /* multi-purpose traversal function for the N-ary tree used by the score */
490 static gboolean
491 traverse_children (GNode *node,
492 gpointer data)
493 {
494 TraverseClosure *closure = data;
495 ClutterScoreEntry *entry = node->data;
496 gboolean retval = FALSE;
497
498 /* root */
499 if (!entry)
500 return TRUE;
501
502 switch (closure->action)
503 {
504 case FIND_BY_TIMELINE:
505 if (closure->d.timeline == entry->timeline)
506 {
507 closure->result = node;
508 retval = TRUE;
509 }
510 break;
511
512 case FIND_BY_ID:
513 if (closure->d.id == entry->id)
514 {
515 closure->result = node;
516 retval = TRUE;
517 }
518 break;
519
520 case REMOVE_BY_ID:
521 if (closure->d.id == entry->id)
522 {
523 /* Destroy all the child entries of this node */
524 g_node_traverse (node,
525 G_POST_ORDER,
526 G_TRAVERSE_ALL,
527 -1,
528 destroy_entry, NULL);
529
530 /* Keep track of this node so that it will be destroyed
531 further up */
532 closure->result = node;
533
534 retval = TRUE;
535 }
536 break;
537
538 case LIST_TIMELINES:
539 closure->result = g_slist_prepend (closure->result, entry->timeline);
540 retval = FALSE;
541 break;
542 }
543
544 return retval;
545 }
546
547 static GNode *
548 find_entry_by_timeline (ClutterScore *score,
549 ClutterTimeline *timeline)
550 {
551 ClutterScorePrivate *priv = score->priv;
552 TraverseClosure closure;
553
554 closure.action = FIND_BY_TIMELINE;
555 closure.score = score;
556 closure.d.timeline = timeline;
557 closure.result = NULL;
558
559 g_node_traverse (priv->root,
560 G_POST_ORDER,
561 G_TRAVERSE_ALL,
562 -1,
563 traverse_children, &closure);
564
565 if (closure.result)
566 return closure.result;
567
568 return NULL;
569 }
570
571 static GNode *
572 find_entry_by_id (ClutterScore *score,
573 gulong id_)
574 {
575 ClutterScorePrivate *priv = score->priv;
576 TraverseClosure closure;
577
578 closure.action = FIND_BY_ID;
579 closure.score = score;
580 closure.d.id = id_;
581 closure.result = NULL;
582
583 g_node_traverse (priv->root,
584 G_POST_ORDER,
585 G_TRAVERSE_ALL,
586 -1,
587 traverse_children, &closure);
588
589 if (closure.result)
590 return closure.result;
591
592 return NULL;
593 }
594
595 /* forward declaration */
596 static void start_entry (ClutterScoreEntry *entry);
597
598 static void
599 start_children_entries (GNode *node,
600 gpointer data)
601 {
602 ClutterScoreEntry *entry = node->data;
603
604 /* If data is NULL, start all entries that have no marker, otherwise
605 only start entries that have the same marker */
606 if (data == NULL
607 ? entry->marker == NULL
608 : (entry->marker && !strcmp (data, entry->marker)))
609 start_entry (entry);
610 }
611
612 static void
613 on_timeline_marker (ClutterTimeline *timeline,
614 const gchar *marker_name,
615 gint frame_num,
616 ClutterScoreEntry *entry)
617 {
618 GNode *parent;
619 CLUTTER_NOTE (SCHEDULER, "timeline [%p] marker ('%s') reached",
620 entry->timeline,
621 entry->marker);
622
623 parent = find_entry_by_timeline (entry->score, timeline);
624 if (!parent)
625 return;
626
627 /* start every child */
628 if (parent->children)
629 {
630 g_node_children_foreach (parent,
631 G_TRAVERSE_ALL,
632 start_children_entries,
633 (gpointer) marker_name);
634 }
635 }
636
637 static void
638 on_timeline_completed (ClutterTimeline *timeline,
639 ClutterScoreEntry *entry)
640 {
641 ClutterScorePrivate *priv = entry->score->priv;
642
643 g_hash_table_remove (priv->running_timelines,
644 GUINT_TO_POINTER (entry->id));
645
646 g_signal_handler_disconnect (timeline, entry->complete_id);
647 entry->complete_id = 0;
648
649 CLUTTER_NOTE (SCHEDULER, "timeline [%p] ('%lu') completed",
650 entry->timeline,
651 entry->id);
652
653 g_signal_emit (entry->score, score_signals[TIMELINE_COMPLETED], 0,
654 entry->timeline);
655
656 /* start every child */
657 if (entry->node->children)
658 {
659 g_node_children_foreach (entry->node,
660 G_TRAVERSE_ALL,
661 start_children_entries,
662 NULL);
663 }
664
665 /* score has finished - fire 'completed' signal */
666 if (g_hash_table_size (priv->running_timelines) == 0)
667 {
668 CLUTTER_NOTE (SCHEDULER, "looks like we finished");
669
670 g_signal_emit (entry->score, score_signals[COMPLETED], 0);
671
672 clutter_score_stop (entry->score);
673
674 if (priv->loop)
675 clutter_score_start (entry->score);
676 }
677 }
678
679 static void
680 start_entry (ClutterScoreEntry *entry)
681 {
682 ClutterScorePrivate *priv = entry->score->priv;
683
684 /* timelines attached to a marker might already be playing when we
685 * end up here from the ::completed handler, so we need to perform
686 * this check to avoid restarting those timelines
687 */
688 if (clutter_timeline_is_playing (entry->timeline))
689 return;
690
691 entry->complete_id = g_signal_connect (entry->timeline,
692 "completed",
693 G_CALLBACK (on_timeline_completed),
694 entry);
695
696 CLUTTER_NOTE (SCHEDULER, "timeline [%p] ('%lu') started",
697 entry->timeline,
698 entry->id);
699
700 if (G_UNLIKELY (priv->running_timelines == NULL))
701 priv->running_timelines = g_hash_table_new (NULL, NULL);
702
703 g_hash_table_insert (priv->running_timelines,
704 GUINT_TO_POINTER (entry->id),
705 entry);
706
707 clutter_timeline_start (entry->timeline);
708
709 g_signal_emit (entry->score, score_signals[TIMELINE_STARTED], 0,
710 entry->timeline);
711 }
712
713 enum
714 {
715 ACTION_START,
716 ACTION_PAUSE,
717 ACTION_STOP
718 };
719
720 static void
721 foreach_running_timeline (gpointer key,
722 gpointer value,
723 gpointer user_data)
724 {
725 ClutterScoreEntry *entry = value;
726 gint action = GPOINTER_TO_INT (user_data);
727
728 switch (action)
729 {
730 case ACTION_START:
731 clutter_timeline_start (entry->timeline);
732 break;
733
734 case ACTION_PAUSE:
735 clutter_timeline_pause (entry->timeline);
736 break;
737
738 case ACTION_STOP:
739 if (entry->complete_id)
740 {
741 g_signal_handler_disconnect (entry->timeline, entry->complete_id);
742 entry->complete_id = 0;
743 }
744 clutter_timeline_stop (entry->timeline);
745 break;
746 }
747 }
748
749 /**
750 * clutter_score_start:
751 * @score: A #ClutterScore
752 *
753 * Starts the score.
754 *
755 * Since: 0.6
756 * Deprecated: 1.8
757 */
758 void
759 clutter_score_start (ClutterScore *score)
760 {
761 ClutterScorePrivate *priv;
762
763 g_return_if_fail (CLUTTER_IS_SCORE (score));
764
765 priv = score->priv;
766
767 if (priv->is_paused)
768 {
769 g_hash_table_foreach (priv->running_timelines,
770 foreach_running_timeline,
771 GINT_TO_POINTER (ACTION_START));
772 priv->is_paused = FALSE;
773 }
774 else
775 {
776 g_signal_emit (score, score_signals[STARTED], 0);
777 g_node_children_foreach (priv->root,
778 G_TRAVERSE_ALL,
779 start_children_entries,
780 NULL);
781 }
782 }
783
784 /**
785 * clutter_score_stop:
786 * @score: A #ClutterScore
787 *
788 * Stops and rewinds a playing #ClutterScore instance.
789 *
790 * Since: 0.6
791 * Deprecated: 1.8
792 */
793 void
794 clutter_score_stop (ClutterScore *score)
795 {
796 ClutterScorePrivate *priv;
797
798 g_return_if_fail (CLUTTER_IS_SCORE (score));
799
800 priv = score->priv;
801
802 if (priv->running_timelines)
803 {
804 g_hash_table_foreach (priv->running_timelines,
805 foreach_running_timeline,
806 GINT_TO_POINTER (ACTION_STOP));
807 g_hash_table_destroy (priv->running_timelines);
808 priv->running_timelines = NULL;
809 }
810 }
811
812 /**
813 * clutter_score_pause:
814 * @score: a #ClutterScore
815 *
816 * Pauses a playing score @score.
817 *
818 * Since: 0.6
819 * Deprecated: 1.8
820 */
821 void
822 clutter_score_pause (ClutterScore *score)
823 {
824 ClutterScorePrivate *priv;
825
826 g_return_if_fail (CLUTTER_IS_SCORE (score));
827
828 priv = score->priv;
829
830 if (!clutter_score_is_playing (score))
831 return;
832
833 g_hash_table_foreach (priv->running_timelines,
834 foreach_running_timeline,
835 GINT_TO_POINTER (ACTION_PAUSE));
836
837 priv->is_paused = TRUE;
838
839 g_signal_emit (score, score_signals[PAUSED], 0);
840 }
841
842 /**
843 * clutter_score_rewind:
844 * @score: A #ClutterScore
845 *
846 * Rewinds a #ClutterScore to its initial state.
847 *
848 * Since: 0.6
849 * Deprecated: 1.8
850 */
851 void
852 clutter_score_rewind (ClutterScore *score)
853 {
854 gboolean was_playing;
855
856 g_return_if_fail (CLUTTER_IS_SCORE (score));
857
858 was_playing = clutter_score_is_playing (score);
859
860 clutter_score_stop (score);
861
862 if (was_playing)
863 clutter_score_start (score);
864 }
865
866 static inline void
867 clutter_score_clear (ClutterScore *score)
868 {
869 ClutterScorePrivate *priv = score->priv;
870
871 g_node_traverse (priv->root,
872 G_POST_ORDER,
873 G_TRAVERSE_ALL,
874 -1,
875 destroy_entry, NULL);
876 g_node_destroy (priv->root);
877 }
878
879 /**
880 * clutter_score_append:
881 * @score: a #ClutterScore
882 * @parent: (allow-none): a #ClutterTimeline in the score, or %NULL
883 * @timeline: a #ClutterTimeline
884 *
885 * Appends a timeline to another one existing in the score; the newly
886 * appended timeline will be started when @parent is complete.
887 *
888 * If @parent is %NULL, the new #ClutterTimeline will be started when
889 * clutter_score_start() is called.
890 *
891 * #ClutterScore will take a reference on @timeline.
892 *
893 * Return value: the id of the #ClutterTimeline inside the score, or
894 * 0 on failure. The returned id can be used with clutter_score_remove()
895 * or clutter_score_get_timeline().
896 *
897 * Since: 0.6
898 * Deprecated: 1.8
899 */
900 gulong
901 clutter_score_append (ClutterScore *score,
902 ClutterTimeline *parent,
903 ClutterTimeline *timeline)
904 {
905 ClutterScorePrivate *priv;
906 ClutterScoreEntry *entry;
907
908 g_return_val_if_fail (CLUTTER_IS_SCORE (score), 0);
909 g_return_val_if_fail (parent == NULL || CLUTTER_IS_TIMELINE (parent), 0);
910 g_return_val_if_fail (CLUTTER_IS_TIMELINE (timeline), 0);
911
912 priv = score->priv;
913
914 if (!parent)
915 {
916 entry = g_slice_new (ClutterScoreEntry);
917 entry->timeline = g_object_ref (timeline);
918 entry->parent = NULL;
919 entry->id = priv->last_id;
920 entry->marker = NULL;
921 entry->marker_id = 0;
922 entry->complete_id = 0;
923 entry->score = score;
924
925 entry->node = g_node_append_data (priv->root, entry);
926 }
927 else
928 {
929 GNode *node;
930
931 node = find_entry_by_timeline (score, parent);
932 if (G_UNLIKELY (!node))
933 {
934 g_warning ("Unable to find the parent timeline inside the score.");
935 return 0;
936 }
937
938 entry = g_slice_new (ClutterScoreEntry);
939 entry->timeline = g_object_ref (timeline);
940 entry->parent = parent;
941 entry->id = priv->last_id;
942 entry->marker = NULL;
943 entry->marker_id = 0;
944 entry->complete_id = 0;
945 entry->score = score;
946
947 entry->node = g_node_append_data (node, entry);
948 }
949
950 priv->last_id += 1;
951
952 return entry->id;
953 }
954
955 /**
956 * clutter_score_append_at_marker:
957 * @score: a #ClutterScore
958 * @parent: the parent #ClutterTimeline
959 * @marker_name: the name of the marker to use
960 * @timeline: the #ClutterTimeline to append
961 *
962 * Appends @timeline at the given @marker_name on the @parent
963 * #ClutterTimeline.
964 *
965 * If you want to append @timeline at the end of @parent, use
966 * clutter_score_append().
967 *
968 * The #ClutterScore will take a reference on @timeline.
969 *
970 * Return value: the id of the #ClutterTimeline inside the score, or
971 * 0 on failure. The returned id can be used with clutter_score_remove()
972 * or clutter_score_get_timeline().
973 *
974 * Since: 0.8
975 * Deprecated: 1.8
976 */
977 gulong
978 clutter_score_append_at_marker (ClutterScore *score,
979 ClutterTimeline *parent,
980 const gchar *marker_name,
981 ClutterTimeline *timeline)
982 {
983 ClutterScorePrivate *priv;
984 GNode *node;
985 ClutterScoreEntry *entry;
986 gchar *marker_reached_signal;
987
988 g_return_val_if_fail (CLUTTER_IS_SCORE (score), 0);
989 g_return_val_if_fail (CLUTTER_IS_TIMELINE (parent), 0);
990 g_return_val_if_fail (marker_name != NULL, 0);
991 g_return_val_if_fail (CLUTTER_IS_TIMELINE (timeline), 0);
992
993 if (!clutter_timeline_has_marker (parent, marker_name))
994 {
995 g_warning ("The parent timeline has no marker '%s'", marker_name);
996 return 0;
997 }
998
999 priv = score->priv;
1000
1001 node = find_entry_by_timeline (score, parent);
1002 if (G_UNLIKELY (!node))
1003 {
1004 g_warning ("Unable to find the parent timeline inside the score.");
1005 return 0;
1006 }
1007
1008 entry = g_slice_new (ClutterScoreEntry);
1009 entry->timeline = g_object_ref (timeline);
1010 entry->parent = parent;
1011 entry->marker = g_strdup (marker_name);
1012 entry->id = priv->last_id;
1013 entry->score = score;
1014 entry->complete_id = 0;
1015
1016 marker_reached_signal = g_strdup_printf ("marker-reached::%s", marker_name);
1017 entry->marker_id = g_signal_connect (entry->parent,
1018 marker_reached_signal,
1019 G_CALLBACK (on_timeline_marker),
1020 entry);
1021
1022 entry->node = g_node_append_data (node, entry);
1023
1024 g_free (marker_reached_signal);
1025
1026 priv->last_id += 1;
1027
1028 return entry->id;
1029 }
1030
1031 /**
1032 * clutter_score_remove:
1033 * @score: a #ClutterScore
1034 * @id_: the id of the timeline to remove
1035 *
1036 * Removes the #ClutterTimeline with the given id inside @score. If
1037 * the timeline has other timelines attached to it, those are removed
1038 * as well.
1039 *
1040 * Since: 0.6
1041 * Deprecated: 1.8
1042 */
1043 void
1044 clutter_score_remove (ClutterScore *score,
1045 gulong id_)
1046 {
1047 ClutterScorePrivate *priv;
1048 TraverseClosure closure;
1049
1050 g_return_if_fail (CLUTTER_IS_SCORE (score));
1051 g_return_if_fail (id_ > 0);
1052
1053 priv = score->priv;
1054
1055 closure.action = REMOVE_BY_ID;
1056 closure.score = score;
1057 closure.d.id = id_;
1058 closure.result = NULL;
1059
1060 g_node_traverse (priv->root,
1061 G_POST_ORDER,
1062 G_TRAVERSE_ALL,
1063 -1,
1064 traverse_children, &closure);
1065
1066 if (closure.result)
1067 g_node_destroy (closure.result);
1068 }
1069
1070 /**
1071 * clutter_score_remove_all:
1072 * @score: a #ClutterScore
1073 *
1074 * Removes all the timelines inside @score.
1075 *
1076 * Since: 0.6
1077 * Deprecated: 1.8
1078 */
1079 void
1080 clutter_score_remove_all (ClutterScore *score)
1081 {
1082 ClutterScorePrivate *priv;
1083
1084 g_return_if_fail (CLUTTER_IS_SCORE (score));
1085
1086 priv = score->priv;
1087
1088 /* this will take care of the running timelines */
1089 clutter_score_stop (score);
1090
1091 /* destroy all the contents of the tree */
1092 clutter_score_clear (score);
1093
1094 /* recreate the sentinel */
1095 priv->root = g_node_new (NULL);
1096 }
1097
1098 /**
1099 * clutter_score_get_timeline:
1100 * @score: a #ClutterScore
1101 * @id_: the id of the timeline
1102 *
1103 * Retrieves the #ClutterTimeline for @id_ inside @score.
1104 *
1105 * Return value: (transfer none): the requested timeline, or %NULL. This
1106 * function does not increase the reference count on the returned
1107 * #ClutterTimeline
1108 *
1109 * Since: 0.6
1110 * Deprecated: 1.8
1111 */
1112 ClutterTimeline *
1113 clutter_score_get_timeline (ClutterScore *score,
1114 gulong id_)
1115 {
1116 GNode *node;
1117 ClutterScoreEntry *entry;
1118
1119 g_return_val_if_fail (CLUTTER_IS_SCORE (score), NULL);
1120 g_return_val_if_fail (id_ > 0, NULL);
1121
1122 node = find_entry_by_id (score, id_);
1123 if (G_UNLIKELY (!node))
1124 return NULL;
1125
1126 entry = node->data;
1127
1128 return entry->timeline;
1129 }
1130
1131 /**
1132 * clutter_score_list_timelines:
1133 * @score: a #ClutterScore
1134 *
1135 * Retrieves a list of all the #ClutterTimelines managed by @score.
1136 *
1137 * Return value: (transfer container) (element-type Clutter.Timeline): a
1138 * #GSList containing all the timelines in the score. This function does
1139 * not increase the reference count of the returned timelines. Use
1140 * g_slist_free() on the returned list to deallocate its resources.
1141 *
1142 * Since: 0.6
1143 * Deprecated: 1.8
1144 */
1145 GSList *
1146 clutter_score_list_timelines (ClutterScore *score)
1147 {
1148 ClutterScorePrivate *priv;
1149 TraverseClosure closure;
1150 GSList *retval;
1151
1152 g_return_val_if_fail (CLUTTER_IS_SCORE (score), NULL);
1153
1154 priv = score->priv;
1155
1156 closure.action = LIST_TIMELINES;
1157 closure.result = NULL;
1158
1159 g_node_traverse (priv->root,
1160 G_POST_ORDER,
1161 G_TRAVERSE_ALL,
1162 -1,
1163 traverse_children, &closure);
1164
1165 retval = closure.result;
1166
1167 return retval;
1168 }