[clutter] actor: Deprecate the old parent modifiers

[Emmanuele Bassi <ebassi src gnome org>]

commit 238a6eb03de549249ff02dd3b3b82b9626f142cf
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Dec 18 21:18:27 2011 +0000

    actor: Deprecate the old parent modifiers
    
    The old API should not be used in newly written code; we have better
    methods for setting up and modifying the scene graph, now.

 clutter/clutter-actor.c            |   30 +++++++++++++++++++++---------
 clutter/clutter-actor.h            |    6 ------
 clutter/deprecated/clutter-actor.h |   11 +++++++++++
 3 files changed, 32 insertions(+), 15 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 9ca4a67..7643339 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -9816,7 +9816,7 @@ clutter_actor_insert_child_below (ClutterActor *self,
  * This function should only be called by legacy #ClutterActor<!-- -->s
  * implementing the #ClutterContainer interface.
  *
- * Newly written code should use clutter_actor_add_child() instead.
+ * Deprecated: 1.10: Use clutter_actor_add_child() instead.
  */
 void
 clutter_actor_set_parent (ClutterActor *self,
@@ -10029,9 +10029,9 @@ clutter_actor_remove_child (ClutterActor *self,
  * This function should only be called by legacy #ClutterActor<!-- -->s
  * implementing the #ClutterContainer interface.
  *
- * Newly written code should use clutter_actor_remove_child() instead.
- *
  * Since: 0.1.1
+ *
+ * Deprecated: 1.10: Use clutter_actor_remove_child() instead.
  */
 void
 clutter_actor_unparent (ClutterActor *self)
@@ -10051,14 +10051,26 @@ clutter_actor_unparent (ClutterActor *self)
  * @self: a #ClutterActor
  * @new_parent: the new #ClutterActor parent
  *
- * This function resets the parent actor of @self.  It is
- * logically equivalent to calling clutter_actor_unparent()
- * and clutter_actor_set_parent(), but more efficiently
- * implemented, as it ensures the child is not finalized
- * when unparented, and emits the parent-set signal only
- * one time.
+ * Resets the parent actor of @self.
+ *
+ * This function is logically equivalent to calling clutter_actor_unparent()
+ * and clutter_actor_set_parent(), but more efficiently implemented, as it
+ * ensures the child is not finalized when unparented, and emits the
+ * #ClutterActor::parent-set signal only once.
+ *
+ * In reality, calling this function is less useful than it sounds, as some
+ * application code may rely on changes in the intermediate state between
+ * removal and addition of the actor from its old parent to the @new_parent.
+ * Thus, it is strongly encouraged to avoid using this function in application
+ * code.
  *
  * Since: 0.2
+ *
+ * Deprecated: 1.10: Use clutter_actor_remove_child() and
+ *   clutter_actor_add_child() instead; remember to take a reference on
+ *   the actor being removed before calling clutter_actor_remove_child()
+ *   to avoid the reference count dropping to zero and the actor being
+ *   destroyed.
  */
 void
 clutter_actor_reparent (ClutterActor *self,
diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h
index 76cb923..54aadaa 100644
--- a/clutter/clutter-actor.h
+++ b/clutter/clutter-actor.h
@@ -482,12 +482,6 @@ 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);
 
diff --git a/clutter/deprecated/clutter-actor.h b/clutter/deprecated/clutter-actor.h
index c752e51..fb2b4a7 100644
--- a/clutter/deprecated/clutter-actor.h
+++ b/clutter/deprecated/clutter-actor.h
@@ -18,6 +18,17 @@ guint32         clutter_actor_get_gid           (ClutterActor          *self);
 CLUTTER_DEPRECATED
 ClutterActor *  clutter_get_actor_by_gid        (guint32                id_);
 
+CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child() and clutter_actor_add_child())
+void            clutter_actor_reparent          (ClutterActor          *self,
+                                                 ClutterActor          *new_parent);
+
+CLUTTER_DEPRECATED_FOR(clutter_actor_add_child)
+void            clutter_actor_set_parent        (ClutterActor          *self,
+                                                 ClutterActor          *parent);
+
+CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child)
+void            clutter_actor_unparent          (ClutterActor          *self);
+
 G_END_DECLS
 
 #endif /* __CLUTTER_ACTOR_DEPRECATED_H__ */