actor: Add children iteration methods

Instead of requiring every consumer of the ClutterActor API that wishes
to iterate over the children of an actor to use the get_children()
method, we should provide an iteration API directly inside ClutterActor
itself.

clutter/clutter-actor.c

@@ -9485,7 +9485,8 @@ insert_child_above (ClutterActor *self,
   child->priv->prev_sibling = sibling;
   child->priv->next_sibling = NULL;
 
-  sibling->priv->next_sibling = child;
+  if (sibling != NULL)
+    sibling->priv->next_sibling = child;
 
   if (self->priv->last_child == sibling)
     self->priv->last_child = child;
@@ -9504,7 +9505,8 @@ insert_child_below (ClutterActor *self,
   child->priv->prev_sibling = NULL;
   child->priv->next_sibling = sibling;
 
-  sibling->priv->prev_sibling = child;
+  if (sibling != NULL)
+    sibling->priv->prev_sibling = child;
 
   if (self->priv->first_child == sibling)
     self->priv->first_child = child;
@@ -15352,3 +15354,86 @@ clutter_actor_get_background_color (ClutterActor *self,
 
   *color = self->priv->bg_color;
 }
+
+/**
+ * clutter_actor_get_previous_sibling:
+ * @self: a #ClutterActor
+ *
+ * Retrieves the sibling of @self that comes before it in the list
+ * of children of @self's parent.
+ *
+ * The returned pointer is only valid until the scene graph changes; it
+ * is guaranteed to remain the same during the paint sequence.
+ *
+ * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
+ *
+ * Since: 1.10
+ */
+ClutterActor *
+clutter_actor_get_previous_sibling (ClutterActor *self)
+{
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
+
+  return self->priv->prev_sibling;
+}
+
+/**
+ * clutter_actor_get_next_sibling:
+ * @self: a #ClutterActor
+ *
+ * Retrieves the sibling of @self that comes after it in the list
+ * of children of @self's parent.
+ *
+ * The returned pointer is only valid until the scene graph changes.
+ *
+ * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
+ *
+ * Since: 1.10
+ */
+ClutterActor *
+clutter_actor_get_next_sibling (ClutterActor *self)
+{
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
+
+  return self->priv->next_sibling;
+}
+
+/**
+ * clutter_actor_get_first_child:
+ * @self: a #ClutterActor
+ *
+ * Retrieves the first child of @self.
+ *
+ * The returned pointer is only valid until the scene graph changes.
+ *
+ * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
+ *
+ * Since: 1.10
+ */
+ClutterActor *
+clutter_actor_get_first_child (ClutterActor *self)
+{
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
+
+  return self->priv->first_child;
+}
+
+/**
+ * clutter_actor_get_last_child:
+ * @self: a #ClutterActor
+ *
+ * Retrieves the last child of @self.
+ *
+ * The returned pointer is only valid until the scene graph changes.
+ *
+ * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
+ *
+ * Since: 1.10
+ */
+ClutterActor *
+clutter_actor_get_last_child (ClutterActor *self)
+{
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
+
+  return self->priv->last_child;
+}

clutter/clutter-actor.h

@@ -467,12 +467,11 @@ GList *               clutter_actor_get_children              (ClutterActor
 gint                  clutter_actor_get_n_children            (ClutterActor          *self);
 ClutterActor *        clutter_actor_get_child_at_index        (ClutterActor          *self,
                                                                gint                   index_);
-void                  clutter_actor_set_parent                (ClutterActor          *self,
+ClutterActor *        clutter_actor_get_previous_sibling      (ClutterActor          *self);
-                                                               ClutterActor          *parent);
+ClutterActor *        clutter_actor_get_next_sibling          (ClutterActor          *self);
+ClutterActor *        clutter_actor_get_first_child           (ClutterActor          *self);
+ClutterActor *        clutter_actor_get_last_child            (ClutterActor          *self);
 ClutterActor *        clutter_actor_get_parent                (ClutterActor          *self);
-void                  clutter_actor_reparent                  (ClutterActor          *self,
-                                                               ClutterActor          *new_parent);
-void                  clutter_actor_unparent                  (ClutterActor          *self);
 gboolean              clutter_actor_contains                  (ClutterActor          *self,
 							       ClutterActor          *descendant);
 ClutterActor*         clutter_actor_get_stage                 (ClutterActor          *actor);
@@ -483,6 +482,12 @@ void                  clutter_actor_lower                     (ClutterActor
 void                  clutter_actor_raise_top                 (ClutterActor          *self);
 void                  clutter_actor_lower_bottom              (ClutterActor          *self);
 
+void                  clutter_actor_reparent                  (ClutterActor          *self,
+                                                               ClutterActor          *new_parent);
+void                  clutter_actor_set_parent                (ClutterActor          *self,
+                                                               ClutterActor          *parent);
+void                  clutter_actor_unparent                  (ClutterActor          *self);
+
 void                  clutter_actor_push_internal             (ClutterActor          *self);
 void                  clutter_actor_pop_internal              (ClutterActor          *self);