From b835e1f8c4101c668589c2c760e251853c20474a Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 27 Dec 2011 18:57:32 +0000 Subject: [PATCH] Deprecate the old raise/lower API We have a replacement in ClutterActor, now. The old ClutterContainer API needs to be deprecated, and the raise() and lower() virtual functions need a default implementation, so we can check for implementations overriding them, by using the diagnostic mode like we do for add(), remove(), and foreach(). The sort_depth_order() virtual function just doesn't do anything, as it should have been made ages ago. The Actor wrappers for the Container methods also need to be deprecated. --- clutter/clutter-actor.c | 51 ++++-------- clutter/clutter-actor.h | 7 -- clutter/clutter-container.c | 111 +++++++++++++++++++------ clutter/clutter-container.h | 20 ++--- clutter/deprecated/clutter-actor.h | 14 ++++ clutter/deprecated/clutter-container.h | 47 +++++++---- 6 files changed, 154 insertions(+), 96 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 15bf6ddc9..be0dd443c 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -10362,7 +10362,9 @@ clutter_actor_set_child_at_index (ClutterActor *self, * Both actors must have the same parent, and the parent must implement * the #ClutterContainer interface * - * This function is the equivalent of clutter_container_raise_child(). + * This function calls clutter_container_raise_child() internally. + * + * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() instead. */ void clutter_actor_raise (ClutterActor *self, @@ -10407,7 +10409,9 @@ clutter_actor_raise (ClutterActor *self, * Both actors must have the same parent, and the parent must implement * the #ClutterContainer interface. * - * This function is the equivalent of clutter_container_lower_child(). + * This function calls clutter_container_lower_child() internally. + * + * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() instead. */ void clutter_actor_lower (ClutterActor *self, @@ -10449,6 +10453,9 @@ clutter_actor_lower (ClutterActor *self, * Raises @self to the top. * * This function calls clutter_actor_raise() internally. + * + * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() with + * a %NULL sibling, instead. */ void clutter_actor_raise_top (ClutterActor *self) @@ -10463,6 +10470,9 @@ clutter_actor_raise_top (ClutterActor *self) * Lowers @self to the bottom. * * This function calls clutter_actor_lower() internally. + * + * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() with + * a %NULL sibling, instead. */ void clutter_actor_lower_bottom (ClutterActor *self) @@ -10854,43 +10864,12 @@ clutter_actor_set_anchor_point_from_gravity (ClutterActor *self, } } -static void -container_raise (ClutterContainer *container, - ClutterActor *child, - ClutterActor *sibling) -{ - ClutterActor *self = CLUTTER_ACTOR (container); - - remove_child (self, child); - insert_child_above (self, child, sibling); - - clutter_actor_queue_relayout (self); -} - -static void -container_lower (ClutterContainer *container, - ClutterActor *child, - ClutterActor *sibling) -{ - ClutterActor *self = CLUTTER_ACTOR (container); - - remove_child (self, child); - insert_child_below (self, child, sibling); - - clutter_actor_queue_relayout (self); -} - -static void -container_sort_by_depth (ClutterContainer *container) -{ -} - static void clutter_container_iface_init (ClutterContainerIface *iface) { - iface->raise = container_raise; - iface->lower = container_lower; - iface->sort_depth_order = container_sort_by_depth; + /* we don't override anything, as ClutterContainer already has a default + * implementation that we can use, and which calls into our own API. + */ } typedef enum diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h index 53949b7df..c1199ce7e 100644 --- a/clutter/clutter-actor.h +++ b/clutter/clutter-actor.h @@ -479,13 +479,6 @@ void clutter_actor_set_child_at_index (ClutterActor ClutterActor *child, gint index_); -void clutter_actor_raise (ClutterActor *self, - ClutterActor *below); -void clutter_actor_lower (ClutterActor *self, - ClutterActor *above); -void clutter_actor_raise_top (ClutterActor *self); -void clutter_actor_lower_bottom (ClutterActor *self); - void clutter_actor_push_internal (ClutterActor *self); void clutter_actor_pop_internal (ClutterActor *self); diff --git a/clutter/clutter-container.c b/clutter/clutter-container.c index 7d1bf3309..9059b0db3 100644 --- a/clutter/clutter-container.c +++ b/clutter/clutter-container.c @@ -142,6 +142,31 @@ container_real_foreach (ClutterContainer *container, &clos); } +static void +container_real_raise (ClutterContainer *container, + ClutterActor *child, + ClutterActor *sibling) +{ + ClutterActor *self = CLUTTER_ACTOR (container); + + clutter_actor_set_child_above_sibling (self, child, sibling); +} + +static void +container_real_lower (ClutterContainer *container, + ClutterActor *child, + ClutterActor *sibling) +{ + ClutterActor *self = CLUTTER_ACTOR (container); + + clutter_actor_set_child_below_sibling (self, child, sibling); +} + +static void +container_real_sort_depth_order (ClutterContainer *container) +{ +} + static void clutter_container_default_init (ClutterContainerInterface *iface) { @@ -214,6 +239,9 @@ clutter_container_default_init (ClutterContainerInterface *iface) iface->add = container_real_add; iface->remove = container_real_remove; iface->foreach = container_real_foreach; + iface->raise = container_real_raise; + iface->lower = container_real_lower; + iface->sort_depth_order = container_real_sort_depth_order; iface->child_meta_type = G_TYPE_INVALID; iface->create_child_meta = create_child_meta; @@ -615,6 +643,8 @@ clutter_container_foreach_with_internals (ClutterContainer *container, * Virtual: raise * * Since: 0.6 + * + * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() instead. */ void clutter_container_raise_child (ClutterContainer *container, @@ -622,22 +652,18 @@ clutter_container_raise_child (ClutterContainer *container, ClutterActor *sibling) { ClutterContainerIface *iface; + ClutterActor *self; g_return_if_fail (CLUTTER_IS_CONTAINER (container)); g_return_if_fail (CLUTTER_IS_ACTOR (actor)); g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling)); - iface = CLUTTER_CONTAINER_GET_IFACE (container); - if (!iface->raise) - { - CLUTTER_CONTAINER_NOTE_NOT_IMPLEMENTED (container, "raise"); - return; - }; - if (actor == sibling) return; - if (clutter_actor_get_parent (actor) != CLUTTER_ACTOR (container)) + self = CLUTTER_ACTOR (container); + + if (clutter_actor_get_parent (actor) != self) { g_warning ("Actor of type '%s' is not a child of the container " "of type '%s'", @@ -646,8 +672,8 @@ clutter_container_raise_child (ClutterContainer *container, return; } - if (sibling && - clutter_actor_get_parent (sibling) != CLUTTER_ACTOR (container)) + if (sibling != NULL && + clutter_actor_get_parent (sibling) != self) { g_warning ("Actor of type '%s' is not a child of the container " "of type '%s'", @@ -656,6 +682,19 @@ clutter_container_raise_child (ClutterContainer *container, return; } + iface = CLUTTER_CONTAINER_GET_IFACE (container); + +#ifdef CLUTTER_ENABLE_DEBUG + if (G_UNLIKELY (_clutter_diagnostic_enabled ())) + { + if (iface->raise != container_real_raise) + _clutter_diagnostic_message ("The ClutterContainer::raise() " + "virtual function has been deprecated " + "and it should not be overridden by " + "newly written code"); + } +#endif /* CLUTTER_ENABLE_DEBUG */ + iface->raise (container, actor, sibling); } @@ -671,6 +710,8 @@ clutter_container_raise_child (ClutterContainer *container, * Virtual: lower * * Since: 0.6 + * + * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() instead. */ void clutter_container_lower_child (ClutterContainer *container, @@ -678,22 +719,18 @@ clutter_container_lower_child (ClutterContainer *container, ClutterActor *sibling) { ClutterContainerIface *iface; + ClutterActor *self; g_return_if_fail (CLUTTER_IS_CONTAINER (container)); g_return_if_fail (CLUTTER_IS_ACTOR (actor)); g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling)); - iface = CLUTTER_CONTAINER_GET_IFACE (container); - if (!iface->lower) - { - CLUTTER_CONTAINER_NOTE_NOT_IMPLEMENTED (container, "lower"); - return; - } - if (actor == sibling) return; - if (clutter_actor_get_parent (actor) != CLUTTER_ACTOR (container)) + self = CLUTTER_ACTOR (container); + + if (clutter_actor_get_parent (actor) != self) { g_warning ("Actor of type '%s' is not a child of the container " "of type '%s'", @@ -702,8 +739,8 @@ clutter_container_lower_child (ClutterContainer *container, return; } - if (sibling && - clutter_actor_get_parent (sibling) != CLUTTER_ACTOR (container)) + if (sibling != NULL&& + clutter_actor_get_parent (sibling) != self) { g_warning ("Actor of type '%s' is not a child of the container " "of type '%s'", @@ -712,6 +749,19 @@ clutter_container_lower_child (ClutterContainer *container, return; } + iface = CLUTTER_CONTAINER_GET_IFACE (container); + +#ifdef CLUTTER_ENABLE_DEBUG + if (G_UNLIKELY (_clutter_diagnostic_enabled ())) + { + if (iface->lower != container_real_lower) + _clutter_diagnostic_message ("The ClutterContainer::lower() " + "virtual function has been deprecated " + "and it should not be overridden by " + "newly written code"); + } +#endif /* CLUTTER_ENABLE_DEBUG */ + iface->lower (container, actor, sibling); } @@ -723,6 +773,10 @@ clutter_container_lower_child (ClutterContainer *container, * be normally used by applications. * * Since: 0.6 + * + * Deprecated: 1.10: The #ClutterContainerIface.sort_depth_order() virtual + * function should not be used any more; the default implementation in + * #ClutterContainer does not do anything. */ void clutter_container_sort_depth_order (ClutterContainer *container) @@ -732,10 +786,19 @@ clutter_container_sort_depth_order (ClutterContainer *container) g_return_if_fail (CLUTTER_IS_CONTAINER (container)); iface = CLUTTER_CONTAINER_GET_IFACE (container); - if (iface->sort_depth_order) - iface->sort_depth_order (container); - else - CLUTTER_CONTAINER_NOTE_NOT_IMPLEMENTED (container, "sort_depth_order"); + +#ifdef CLUTTER_ENABLE_DEBUG + if (G_UNLIKELY (_clutter_diagnostic_enabled ())) + { + if (iface->sort_depth_order != container_real_sort_depth_order) + _clutter_diagnostic_message ("The ClutterContainer::sort_depth_order() " + "virtual function has been deprecated " + "and it should not be overridden by " + "newly written code"); + } +#endif /* CLUTTER_ENABLE_DEBUG */ + + iface->sort_depth_order (container); } /** diff --git a/clutter/clutter-container.h b/clutter/clutter-container.h index 2f2690fa6..b7e3f2b6c 100644 --- a/clutter/clutter-container.h +++ b/clutter/clutter-container.h @@ -65,11 +65,15 @@ typedef struct _ClutterContainerIface ClutterContainerIface; * container's children, both added using the #ClutterContainer API * and internal children. The implementation of this virtual function * is required only if the #ClutterContainer implementation has - * internal children. - * @raise: virtual function for raising a child - * @lower: virtual function for lowering a child + * internal children. This virtual function is deprecated, and it should + * not be overridden. + * @raise: virtual function for raising a child. This virtual function is + * deprecated and it should not be overridden. + * @lower: virtual function for lowering a child. This virtual function is + * deprecated and it should not be overridden. * @sort_depth_order: virtual function for sorting the children of a - * container depending on their depth + * container depending on their depth. This virtual function is deprecated + * and it should not be overridden. * @child_meta_type: The GType used for storing auxiliary information about * each of the containers children. * @create_child_meta: virtual function that gets called for each added @@ -141,14 +145,6 @@ GType clutter_container_get_type (void) G_GNUC_CONST; ClutterActor *clutter_container_find_child_by_name (ClutterContainer *container, const gchar *child_name); -void clutter_container_raise_child (ClutterContainer *container, - ClutterActor *actor, - ClutterActor *sibling); -void clutter_container_lower_child (ClutterContainer *container, - ClutterActor *actor, - ClutterActor *sibling); -void clutter_container_sort_depth_order (ClutterContainer *container); - GParamSpec * clutter_container_class_find_child_property (GObjectClass *klass, const gchar *property_name); diff --git a/clutter/deprecated/clutter-actor.h b/clutter/deprecated/clutter-actor.h index fb2b4a74b..2dee81f33 100644 --- a/clutter/deprecated/clutter-actor.h +++ b/clutter/deprecated/clutter-actor.h @@ -29,6 +29,20 @@ void clutter_actor_set_parent (ClutterActor *self, CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child) void clutter_actor_unparent (ClutterActor *self); +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_above_sibling) +void clutter_actor_raise (ClutterActor *self, + ClutterActor *below); + +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_below_sibling) +void clutter_actor_lower (ClutterActor *self, + ClutterActor *above); + +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_above_sibling() with NULL sibling) +void clutter_actor_raise_top (ClutterActor *self); + +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_below_sibling() with NULL sibling) +void clutter_actor_lower_bottom (ClutterActor *self); + G_END_DECLS #endif /* __CLUTTER_ACTOR_DEPRECATED_H__ */ diff --git a/clutter/deprecated/clutter-container.h b/clutter/deprecated/clutter-container.h index f924aca2f..e85cd1fa0 100644 --- a/clutter/deprecated/clutter-container.h +++ b/clutter/deprecated/clutter-container.h @@ -32,35 +32,35 @@ G_BEGIN_DECLS CLUTTER_DEPRECATED_FOR(clutter_actor_add_child) -void clutter_container_add (ClutterContainer *container, - ClutterActor *first_actor, - ...) G_GNUC_NULL_TERMINATED; +void clutter_container_add (ClutterContainer *container, + ClutterActor *first_actor, + ...) G_GNUC_NULL_TERMINATED; CLUTTER_DEPRECATED_FOR(clutter_actor_add_child) -void clutter_container_add_actor (ClutterContainer *container, - ClutterActor *actor); +void clutter_container_add_actor (ClutterContainer *container, + ClutterActor *actor); CLUTTER_DEPRECATED_FOR(clutter_actor_add_child) -void clutter_container_add_valist (ClutterContainer *container, - ClutterActor *first_actor, - va_list var_args); +void clutter_container_add_valist (ClutterContainer *container, + ClutterActor *first_actor, + va_list var_args); CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child) -void clutter_container_remove (ClutterContainer *container, - ClutterActor *first_actor, - ...) G_GNUC_NULL_TERMINATED; +void clutter_container_remove (ClutterContainer *container, + ClutterActor *first_actor, + ...) G_GNUC_NULL_TERMINATED; CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child) -void clutter_container_remove_actor (ClutterContainer *container, - ClutterActor *actor); +void clutter_container_remove_actor (ClutterContainer *container, + ClutterActor *actor); CLUTTER_DEPRECATED_FOR(clutter_actor_remove_child) -void clutter_container_remove_valist (ClutterContainer *container, - ClutterActor *first_actor, - va_list var_args); +void clutter_container_remove_valist (ClutterContainer *container, + ClutterActor *first_actor, + va_list var_args); CLUTTER_DEPRECATED_FOR(clutter_actor_get_children) -GList * clutter_container_get_children (ClutterContainer *container); +GList * clutter_container_get_children (ClutterContainer *container); CLUTTER_DEPRECATED void clutter_container_foreach (ClutterContainer *container, @@ -72,6 +72,19 @@ void clutter_container_foreach_with_internals (ClutterContaine ClutterCallback callback, gpointer user_data); +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_above_sibling) +void clutter_container_raise_child (ClutterContainer *container, + ClutterActor *actor, + ClutterActor *sibling); + +CLUTTER_DEPRECATED_FOR(clutter_actor_set_child_below_sibling) +void clutter_container_lower_child (ClutterContainer *container, + ClutterActor *actor, + ClutterActor *sibling); + +CLUTTER_DEPRECATED +void clutter_container_sort_depth_order (ClutterContainer *container); + G_END_DECLS #endif /* __CLUTTER_CONTAINER_DEPRECATED_H__ */