clutter/timeline: Deprecate timelines without an actor or frame clock

Without an associated actor, or explicit frame clock set, in the future
a timeline will not know how to progress, as there will be no singe
frame clock to assume is the main one. Thus, deprecate the construction
of timelines without either an actor or frame clock set.

https://gitlab.gnome.org/GNOME/mutter/-/merge_requests/1285

clutter/clutter/clutter-actor.c

@@ -311,7 +311,7 @@
  * |[<!-- language="C" -->
  * ClutterTransition *transition;
  *
- * transition = clutter_property_transition_new ("opacity");
+ * transition = clutter_property_transition_new_for_actor (actor, "opacity");
  * clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
  * clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2);
  * clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
@@ -344,7 +344,7 @@
  * ClutterTransition *transition;
  * ClutterInterval *interval;
  *
- * transition = clutter_property_transition_new ("opacity");
+ * transition = clutter_property_transition_new_for_actor (actor, "opacity");
  *
  * // we want to animate the opacity between 0 and 255
  * clutter_transition_set_from (transition, G_TYPE_UINT, 0);
@@ -505,7 +505,7 @@
  *   const char *prop = "@constraints.bind-x.offset";
  *
  *   // create a new transition for the given property
- *   transition = clutter_property_transition_new (prop);
+ *   transition = clutter_property_transition_new_for_actor (rect, prop);
  *
  *   // set the easing mode and duration
  *   clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
@@ -17865,7 +17865,7 @@ _clutter_actor_create_transition (ClutterActor *actor,
   clos = g_hash_table_lookup (info->transitions, pspec->name);
   if (clos == NULL)
     {
-      res = clutter_property_transition_new (pspec->name);
+      res = clutter_property_transition_new_for_actor (actor, pspec->name);
 
       clutter_transition_set_remove_on_complete (res, TRUE);
 

clutter/clutter/clutter-pan-action.c

@@ -326,8 +326,12 @@ gesture_end (ClutterGestureAction *gesture,
   if (ABS (velocity) * priv->acceleration_factor > min_velocity &&
       duration > FLOAT_EPSILON)
     {
+      ClutterActor *pan_actor =
+        clutter_actor_meta_get_actor (CLUTTER_ACTOR_META (gesture));
+
       priv->interpolated_x = priv->interpolated_y = 0.0f;
-      priv->deceleration_timeline = clutter_timeline_new (duration);
+      priv->deceleration_timeline = clutter_timeline_new_for_actor (pan_actor,
+                                                                    duration);
       clutter_timeline_set_progress_mode (priv->deceleration_timeline,
                                           CLUTTER_EASE_OUT_EXPO);
 
@@ -458,6 +462,8 @@ clutter_pan_action_set_actor (ClutterActorMeta *meta,
       /* make sure we reset the state */
       if (priv->state == PAN_STATE_INTERPOLATING)
         g_clear_object (&priv->deceleration_timeline);
+      else if (priv->deceleration_timeline)
+        clutter_timeline_set_actor (priv->deceleration_timeline, actor);
     }
 
   CLUTTER_ACTOR_META_CLASS (clutter_pan_action_parent_class)->set_actor (meta,

clutter/clutter/clutter-property-transition.h

@@ -82,6 +82,7 @@ CLUTTER_EXPORT
 ClutterTransition *     clutter_property_transition_new_for_actor       (ClutterActor              *actor,
                                                                          const char                *property_name);
 
+CLUTTER_DEPRECATED_FOR(clutter_transition_new_for_actor)
 ClutterTransition *     clutter_property_transition_new                 (const char                *property_name);
 
 CLUTTER_EXPORT

clutter/clutter/clutter-scroll-actor.c

@@ -369,7 +369,9 @@ clutter_scroll_actor_scroll_to_point (ClutterScrollActor     *actor,
 
   if (priv->transition == NULL)
     {
-      priv->transition = clutter_property_transition_new ("scroll-to");
+      priv->transition =
+        clutter_property_transition_new_for_actor (CLUTTER_ACTOR (actor),
+                                                   "scroll-to");
       clutter_transition_set_animatable (priv->transition,
                                          CLUTTER_ANIMATABLE (actor));
       clutter_transition_set_remove_on_complete (priv->transition, TRUE);

clutter/clutter/clutter-text.c

@@ -3662,7 +3662,8 @@ clutter_text_set_color_animated (ClutterText        *self,
 
   if (transition == NULL)
     {
-      transition = clutter_property_transition_new (pspec->name);
+      transition = clutter_property_transition_new_for_actor (actor,
+                                                              pspec->name);
       clutter_transition_set_animatable (transition,
                                          CLUTTER_ANIMATABLE (self));
       clutter_transition_set_remove_on_complete (transition, TRUE);

clutter/clutter/clutter-timeline.c

@@ -95,6 +95,7 @@
 #include "clutter-build-config.h"
 
 #include "clutter-timeline.h"
+#include "deprecated/clutter-timeline.h"
 
 #include "clutter-debug.h"
 #include "clutter-easing.h"
@@ -614,6 +615,17 @@ remove_timeline (ClutterTimeline *timeline)
     }
 }
 
+static void
+clutter_timeline_constructed (GObject *object)
+{
+  ClutterTimeline *timeline = CLUTTER_TIMELINE (object);
+  ClutterTimelinePrivate *priv = timeline->priv;
+
+  g_warn_if_fail (priv->actor || priv->frame_clock);
+
+  G_OBJECT_CLASS (clutter_timeline_parent_class)->constructed (object);
+}
+
 static void
 clutter_timeline_finalize (GObject *object)
 {
@@ -787,6 +799,7 @@ clutter_timeline_class_init (ClutterTimelineClass *klass)
 
   object_class->dispose = clutter_timeline_dispose;
   object_class->finalize = clutter_timeline_finalize;
+  object_class->constructed = clutter_timeline_constructed;
   object_class->set_property = clutter_timeline_set_property;
   object_class->get_property = clutter_timeline_get_property;
   g_object_class_install_properties (object_class, PROP_LAST, obj_props);

clutter/clutter/clutter-timeline.h

@@ -118,9 +118,6 @@ struct _ClutterTimelineClass
 CLUTTER_EXPORT
 GType clutter_timeline_get_type (void) G_GNUC_CONST;
 
-CLUTTER_EXPORT
-ClutterTimeline *               clutter_timeline_new                            (guint                     duration_ms);
-
 CLUTTER_EXPORT
 ClutterTimeline *               clutter_timeline_new_for_actor                  (ClutterActor             *actor,
                                                                                  unsigned int              duration_ms);

clutter/clutter/deprecated/clutter-timeline.h

@@ -0,0 +1,34 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2012 Intel Corp
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef __CLUTTER_TIMELINE_PRIVATE_H__
+#define __CLUTTER_TIMELINE_PRIVATE_H__
+
+#include <clutter/clutter-timeline.h>
+
+G_BEGIN_DECLS
+
+CLUTTER_DEPRECATED_FOR(clutter_timeline_new_for_actor)
+ClutterTimeline * clutter_timeline_new (guint duration_ms);
+
+G_END_DECLS
+
+#endif /* __CLUTTER_TIMELINE_PRIVATE_H__ */

clutter/clutter/meson.build

@@ -223,6 +223,7 @@ clutter_nonintrospected_sources = [
 
 clutter_deprecated_headers = [
   'deprecated/clutter-container.h',
+  'deprecated/clutter-timeline.h',
 ]
 
 clutter_backend_sources = []

src/tests/clutter/conform/scripts/test-script-timeline-markers.json

@@ -1,7 +1,10 @@
+[
+  { "id" : "actor0", "type" : "ClutterActor" },
   {
     "id" : "timeline0",
     "type" : "ClutterTimeline",
     "duration" : 1000,
+    "actor" : "actor0",
 
     "markers" : [
       { "name" : "marker0", "time" : 250 },
@@ -10,3 +13,4 @@
       { "name" : "marker3", "progress" : 0.5 }
     ]
   }
+]

src/tests/clutter/conform/timeline-interpolate.c

@@ -139,7 +139,7 @@ timeline_interpolation (void)
   stage = clutter_test_get_stage ();
 
   state.timeline = 
-    clutter_timeline_new (TEST_TIMELINE_DURATION);
+    clutter_timeline_new_for_actor (stage, TEST_TIMELINE_DURATION);
   clutter_timeline_set_repeat_count (state.timeline, -1);
   g_signal_connect (G_OBJECT(state.timeline),
 		    "new-frame",

src/tests/clutter/conform/timeline-progress.c

@@ -7,9 +7,10 @@
 static void
 timeline_progress_step (void)
 {
+  ClutterActor *stage = clutter_test_get_stage ();
   ClutterTimeline *timeline;
 
-  timeline = clutter_timeline_new (1000);
+  timeline = clutter_timeline_new_for_actor (stage, 1000);
 
   if (!g_test_quiet ())
     g_print ("mode: step(3, end)\n");
@@ -90,9 +91,10 @@ timeline_progress_step (void)
 static void
 timeline_progress_mode (void)
 {
+  ClutterActor *stage = clutter_test_get_stage ();
   ClutterTimeline *timeline;
 
-  timeline = clutter_timeline_new (1000);
+  timeline = clutter_timeline_new_for_actor (stage, 1000);
 
   g_assert (clutter_timeline_get_progress_mode (timeline) == CLUTTER_LINEAR);
   g_assert_cmpfloat (clutter_timeline_get_progress (timeline), ==, 0.0);

src/tests/clutter/conform/timeline-rewind.c

@@ -76,7 +76,7 @@ timeline_rewind (void)
   stage = clutter_test_get_stage ();
 
   state.timeline = 
-    clutter_timeline_new (TEST_TIMELINE_DURATION);
+    clutter_timeline_new_for_actor (stage, TEST_TIMELINE_DURATION);
   g_signal_connect (G_OBJECT(state.timeline),
                     "new-frame",
                     G_CALLBACK(new_frame_cb),

src/tests/clutter/conform/timeline.c

@@ -198,7 +198,7 @@ timeline_base (void)
   stage = clutter_test_get_stage ();
 
   timeline_data_init (&data_1, 1);
-  timeline_1 = clutter_timeline_new (FRAME_COUNT * 1000 / FPS);
+  timeline_1 = clutter_timeline_new_for_actor (stage, FRAME_COUNT * 1000 / FPS);
   clutter_timeline_add_marker_at_time (timeline_1, "start-marker",
                                        0 * 1000 / FPS);
   clutter_timeline_add_marker_at_time (timeline_1, "foo", 5 * 1000 / FPS);
@@ -215,7 +215,7 @@ timeline_base (void)
   g_strfreev (markers);
 
   timeline_data_init (&data_2, 2);
-  timeline_2 = clutter_timeline_new (FRAME_COUNT * 1000 / FPS);
+  timeline_2 = clutter_timeline_new_for_actor (stage, FRAME_COUNT * 1000 / FPS);
   clutter_timeline_add_marker_at_time (timeline_2, "bar", 2 * 1000 / FPS);
   markers = clutter_timeline_list_markers (timeline_2, -1, &n_markers);
   g_assert (markers != NULL);
@@ -224,7 +224,7 @@ timeline_base (void)
   g_strfreev (markers);
 
   timeline_data_init (&data_3, 3);
-  timeline_3 = clutter_timeline_new (FRAME_COUNT * 1000 / FPS);
+  timeline_3 = clutter_timeline_new_for_actor (stage, FRAME_COUNT * 1000 / FPS);
   clutter_timeline_set_direction (timeline_3, CLUTTER_TIMELINE_BACKWARD);
   clutter_timeline_add_marker_at_time (timeline_3, "start-marker",
                                        FRAME_COUNT * 1000 / FPS);

src/tests/clutter/interactive/test-actors.c

@@ -184,7 +184,7 @@ test_actors_main (int argc, char *argv[])
   clutter_stage_set_title (CLUTTER_STAGE (oh->stage), "Actors");
 
   /* Create a timeline to manage animation */
-  oh->timeline = clutter_timeline_new (6000);
+  oh->timeline = clutter_timeline_new_for_actor (oh->stage, 6000);
   clutter_timeline_set_repeat_count (oh->timeline, -1);
 
   /* fire a callback for frame change */

src/tests/clutter/interactive/test-cairo-flowers.c

@@ -209,12 +209,12 @@ test_cairo_flowers_main (int argc, char **argv)
   if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
     return 1;
 
-  /* Create a timeline to manage animation */
-  timeline = clutter_timeline_new (6000);
-  clutter_timeline_set_repeat_count (timeline, -1);
-
   stage = clutter_stage_new ();
   clutter_stage_set_title (CLUTTER_STAGE (stage), "Cairo Flowers");
+
+  /* Create a timeline to manage animation */
+  timeline = clutter_timeline_new_for_actor (stage, 6000);
+  clutter_timeline_set_repeat_count (timeline, -1);
   g_signal_connect (stage, "destroy", G_CALLBACK (stop_and_quit), timeline);
 
   clutter_actor_set_background_color (stage, CLUTTER_COLOR_Black);

src/tests/clutter/interactive/test-cogl-multitexture.c

@@ -212,7 +212,7 @@ test_cogl_multitexture_main (int argc, char *argv[])
   clutter_container_add_actor (CLUTTER_CONTAINER(stage),
 			       state->group);
 
-  state->timeline = clutter_timeline_new (2812);
+  state->timeline = clutter_timeline_new_for_actor (stage, 2812);
 
   g_signal_connect (state->timeline, "new-frame", G_CALLBACK (frame_cb), state);
 

src/tests/clutter/interactive/test-cogl-tex-polygon.c

@@ -409,7 +409,7 @@ test_cogl_tex_polygon_main (int argc, char *argv[])
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), coglbox);
 
   /* Timeline for animation */
-  timeline = clutter_timeline_new (6000);
+  timeline = clutter_timeline_new_for_actor (stage, 6000);
   clutter_timeline_set_repeat_count (timeline, -1);
   g_signal_connect (timeline, "new-frame", G_CALLBACK (frame_cb), coglbox);
   clutter_timeline_start (timeline);

src/tests/clutter/interactive/test-cogl-tex-tile.c

@@ -215,7 +215,7 @@ test_cogl_tex_tile_main (int argc, char *argv[])
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), coglbox);
 
   /* Timeline for animation */
-  timeline = clutter_timeline_new (6000); /* 6 second duration */
+  timeline = clutter_timeline_new_for_actor (stage, 6000); /* 6 second duration */
   clutter_timeline_set_repeat_count (timeline, -1);
   g_signal_connect (timeline, "new-frame", G_CALLBACK (frame_cb), coglbox);
   clutter_timeline_start (timeline);

src/tests/clutter/interactive/test-layout.c

@@ -607,7 +607,7 @@ test_layout_main (int argc, char *argv[])
   clutter_stage_set_title (CLUTTER_STAGE (stage), "Layout");
   g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
 
-  main_timeline = clutter_timeline_new (2000);
+  main_timeline = clutter_timeline_new_for_actor (stage, 2000);
   clutter_timeline_set_repeat_count (main_timeline, -1);
   clutter_timeline_set_auto_reverse (main_timeline, TRUE);
   g_signal_connect (main_timeline, "new-frame",

src/tests/clutter/interactive/test-paint-wrapper.c

@@ -241,7 +241,7 @@ test_paint_wrapper_main (int argc, char *argv[])
   oh->stage = stage;
 
   /* Create a timeline to manage animation */
-  oh->timeline = clutter_timeline_new (6000);
+  oh->timeline = clutter_timeline_new_for_actor (oh->stage, 6000);
   clutter_timeline_set_repeat_count (oh->timeline, -1);
 
   /* fire a callback for frame change */

src/tests/clutter/interactive/test-shader-effects.c

@@ -21,15 +21,15 @@ test_shader_effects_main (int argc, char *argv[])
   if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
     return 1;
 
-  /* Make a timeline */
-  timeline = clutter_timeline_new (7692);
-  clutter_timeline_set_repeat_count (timeline, -1);
-
   stage = clutter_stage_new ();
   clutter_stage_set_title (CLUTTER_STAGE (stage), "Rotations");
   clutter_actor_set_background_color (stage, CLUTTER_COLOR_Aluminium3);
   g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
 
+  /* Make a timeline */
+  timeline = clutter_timeline_new_for_actor (stage, 7692);
+  clutter_timeline_set_repeat_count (timeline, -1);
+
   /* Make a hand */
   file = g_build_filename (TESTS_DATADIR, "redhand.png", NULL);
   hand = clutter_test_utils_create_texture_from_file (file, NULL);