actor: Add new methods for changing the paint sequence

ClutterActor provides four methods for changing the paint sequence order
of its children:

  raise_top()
  raise()
  lower()
  lower_bottom()

The first and last one being just wrappers around raise() and lower(),
respectively. These methods have various issues: they omit the parent,
preferring to retrieve it from the actor passed as the first argument;
this does not match the new style of API introduced to operate on the
list of children of an actor.

Additionally, the raise() and lower() methods of ClutterActor call into
the Container interface, and are not really aptly named (raise() in
particular collides with the completely unrelated 'raise' keyword in
Python, and usually needs to be wrapped in order to be used at all).

Furthermore, we need public methods that Container can call from its
default implementation, as well as methods to port current Container
implementations.

Finally, since we have insert_child_at_index(), we should also have an
equivalent set_child_at_index() as well.

clutter/clutter-actor.c

@@ -10250,6 +10250,108 @@ clutter_actor_contains (ClutterActor *self,
   return FALSE;
 }
 
+/**
+ * clutter_actor_set_above_sibling:
+ * @self: a #ClutterActor
+ * @child: a #ClutterActor child of @self
+ * @sibling: (allow-none): a #ClutterActor child of @self, or %NULL
+ *
+ * Sets @child to be above @sibling in the list of children of @self.
+ *
+ * If @sibling is %NULL, @child will be the new last child of @self.
+ *
+ * This function is logically equivalent to removing @child and using
+ * clutter_actor_insert_child_above(), but it will not emit signals
+ * or change state on @child.
+ *
+ * Since: 1.10
+ */
+void
+clutter_actor_set_child_above_sibling (ClutterActor *self,
+                                       ClutterActor *child,
+                                       ClutterActor *sibling)
+{
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
+  g_return_if_fail (CLUTTER_IS_ACTOR (child));
+  g_return_if_fail (child->priv->parent == self);
+  g_return_if_fail (child != sibling);
+  g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
+
+  if (sibling != NULL)
+    g_return_if_fail (sibling->priv->parent == self);
+
+  remove_child (self, child);
+  insert_child_above (self, child, sibling);
+
+  clutter_actor_queue_relayout (self);
+}
+
+/**
+ * clutter_actor_set_child_below_sibling:
+ * @self: a #ClutterActor
+ * @child: a #ClutterActor child of @self
+ * @sibling: (allow-none): a #ClutterActor child of @self, or %NULL
+ *
+ * Sets @child to be below @sibling in the list of children of @self.
+ *
+ * If @sibling is %NULL, @child will be the new first child of @self.
+ *
+ * This function is logically equivalent to removing @self and using
+ * clutter_actor_insert_child_below(), but it will not emit signals
+ * or change state on @child.
+ *
+ * Since: 1.10
+ */
+void
+clutter_actor_set_child_below_sibling (ClutterActor *self,
+                                       ClutterActor *child,
+                                       ClutterActor *sibling)
+{
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
+  g_return_if_fail (CLUTTER_IS_ACTOR (child));
+  g_return_if_fail (child->priv->parent == self);
+  g_return_if_fail (child != sibling);
+  g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
+
+  if (sibling != NULL)
+    g_return_if_fail (sibling->priv->parent == self);
+
+  remove_child (self, child);
+  insert_child_below (self, child, sibling);
+
+  clutter_actor_queue_relayout (self);
+}
+
+/**
+ * clutter_actor_set_child_at_index:
+ * @self: a #ClutterActor
+ * @child: a #ClutterActor child of @self
+ * @index_: the new index for @child
+ *
+ * Changes the index of @child in the list of children of @self.
+ *
+ * This function is logically equivalent to removing @child and
+ * calling clutter_actor_insert_child_at_index(), but it will not
+ * emit signals or change state on @child.
+ *
+ * Since: 1.10
+ */
+void
+clutter_actor_set_child_at_index (ClutterActor *self,
+                                  ClutterActor *child,
+                                  gint          index_)
+{
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
+  g_return_if_fail (CLUTTER_IS_ACTOR (child));
+  g_return_if_fail (child->priv->parent == self);
+  g_return_if_fail (index_ <= self->priv->n_children);
+
+  remove_child (self, child);
+  insert_child_at_index (self, child, GINT_TO_POINTER (index_));
+
+  clutter_actor_queue_relayout (self);
+}
+
 /**
  * clutter_actor_raise:
  * @self: A #ClutterActor

clutter/clutter-actor.h

@@ -469,6 +469,16 @@ ClutterActor *        clutter_actor_get_parent                (ClutterActor
 gboolean              clutter_actor_contains                  (ClutterActor          *self,
 							       ClutterActor          *descendant);
 ClutterActor*         clutter_actor_get_stage                 (ClutterActor          *actor);
+void                  clutter_actor_set_child_below_sibling   (ClutterActor          *self,
+                                                               ClutterActor          *child,
+                                                               ClutterActor          *sibling);
+void                  clutter_actor_set_child_above_sibling   (ClutterActor          *self,
+                                                               ClutterActor          *child,
+                                                               ClutterActor          *sibling);
+void                  clutter_actor_set_child_at_index        (ClutterActor          *self,
+                                                               ClutterActor          *child,
+                                                               gint                   index_);
+
 void                  clutter_actor_raise                     (ClutterActor          *self,
                                                                ClutterActor          *below);
 void                  clutter_actor_lower                     (ClutterActor          *self,

tests/conform/test-actor-graph.c

@@ -170,7 +170,8 @@ actor_raise_child (TestConformSimpleFixture *fixture,
   iter = clutter_actor_get_child_at_index (actor, 1);
   g_assert_cmpstr (clutter_actor_get_name (iter), ==, "bar");
 
-  clutter_actor_raise (iter, clutter_actor_get_child_at_index (actor, 2));
+  clutter_actor_set_child_above_sibling (actor, iter,
+                                         clutter_actor_get_child_at_index (actor, 2));
 
   g_assert_cmpstr (clutter_actor_get_name (clutter_actor_get_child_at_index (actor, 0)),
                    ==,
@@ -183,7 +184,7 @@ actor_raise_child (TestConformSimpleFixture *fixture,
                    "bar");
 
   iter = clutter_actor_get_child_at_index (actor, 0);
-  clutter_actor_raise_top (iter);
+  clutter_actor_set_child_above_sibling (actor, iter, NULL);
 
   g_assert_cmpstr (clutter_actor_get_name (clutter_actor_get_child_at_index (actor, 0)),
                    ==,
@@ -223,7 +224,8 @@ actor_lower_child (TestConformSimpleFixture *fixture,
   iter = clutter_actor_get_child_at_index (actor, 1);
   g_assert_cmpstr (clutter_actor_get_name (iter), ==, "bar");
 
-  clutter_actor_lower (iter, clutter_actor_get_child_at_index (actor, 0));
+  clutter_actor_set_child_below_sibling (actor, iter,
+                                         clutter_actor_get_child_at_index (actor, 0));
 
   g_assert_cmpstr (clutter_actor_get_name (clutter_actor_get_child_at_index (actor, 0)),
                    ==,
@@ -236,7 +238,7 @@ actor_lower_child (TestConformSimpleFixture *fixture,
                    "baz");
 
   iter = clutter_actor_get_child_at_index (actor, 2);
-  clutter_actor_lower_bottom (iter);
+  clutter_actor_set_child_below_sibling (actor, iter, NULL);
 
   g_assert_cmpstr (clutter_actor_get_name (clutter_actor_get_child_at_index (actor, 0)),
                    ==,