actor: add clutter_actor_contains()

It is often useful to determine if one actor is an ancestor of
another. Add a method to do that.

http://bugzilla.openedhand.com/show_bug.cgi?id=2162

Signed-off-by: Emmanuele Bassi <ebassi@linux.intel.com>

clutter/clutter-actor.c

@@ -7568,6 +7568,31 @@ clutter_actor_reparent (ClutterActor *self,
       clutter_actor_update_map_state (self, MAP_STATE_CHECK);
    }
 }
+
+/**
+ * clutter_actor_contains:
+ * @self: A #ClutterActor
+ * @descendant: A #ClutterActor, possibly contained in @self
+ *
+ * Determines if @descendant is contained inside @self (either as an
+ * immediate child, or as a deeper descendant).
+ *
+ * Return value: whether @descendent is contained within @self
+ *
+ * Since: 1.4
+ */
+gboolean
+clutter_actor_contains (ClutterActor *self,
+			ClutterActor *descendant)
+{
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
+  g_return_val_if_fail (CLUTTER_IS_ACTOR (descendant), FALSE);
+
+  while (descendant != NULL && descendant != self)
+    descendant = descendant->priv->parent_actor;
+  return descendant == self;
+}
+
 /**
  * clutter_actor_raise:
  * @self: A #ClutterActor

clutter/clutter-actor.h

@@ -458,6 +458,8 @@ ClutterActor *        clutter_actor_get_parent                (ClutterActor
 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);
 
 void                  clutter_actor_raise                     (ClutterActor          *self,

doc/reference/clutter/clutter-sections.txt

@@ -355,6 +355,7 @@ clutter_actor_set_parent
 clutter_actor_get_parent
 clutter_actor_reparent
 clutter_actor_unparent
+clutter_actor_contains
 clutter_actor_raise
 clutter_actor_lower
 clutter_actor_raise_top