From 6227f7a0f55fdf3f6a0cc7b5fe83c2387bc1280f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 4 Jul 2013 21:53:38 +0100 Subject: [PATCH] actor: Deprecate realize and unrealize There is no reasonable use case for having the functions, the virtual functions, and the signals for realization and unrealization; the concept belongs to an older era, when we though it would have been possible to migrate actors across different GL contexts, of in case a GL context would not have been available until the main loop started spinning. That is most definitely not possible today, and too much code would utterly break if we ever supported that. --- clutter/clutter-actor.c | 56 +++++++++++++++++++++++++++++------------ clutter/clutter-actor.h | 13 +++++++--- 2 files changed, 49 insertions(+), 20 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 5d378a0be..b51a7b755 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -1066,6 +1066,9 @@ static void clutter_actor_set_child_transform_internal (ClutterActor *sel static inline gboolean clutter_actor_has_mapped_clones (ClutterActor *self); +static void clutter_actor_realize_internal (ClutterActor *self); +static void clutter_actor_unrealize_internal (ClutterActor *self); + /* Helper macro which translates by the anchor coord, applies the given transformation and then translates back */ #define TRANSFORM_ABOUT_ANCHOR_COORD(a,m,c,_transform) G_STMT_START { \ @@ -1879,15 +1882,22 @@ clutter_actor_hide_all (ClutterActor *self) * This function does not realize child actors, except in the special * case that realizing the stage, when the stage is visible, will * suddenly map (and thus realize) the children of the stage. - **/ + * + * Deprecated: 1.16: Actors are automatically realized, and nothing + * requires explicit realization. + */ void clutter_actor_realize (ClutterActor *self) { - ClutterActorPrivate *priv; - g_return_if_fail (CLUTTER_IS_ACTOR (self)); - priv = self->priv; + clutter_actor_realize_internal (self); +} + +static void +clutter_actor_realize_internal (ClutterActor *self) +{ + ClutterActorPrivate *priv = self->priv; #ifdef CLUTTER_ENABLE_DEBUG clutter_actor_verify_map_state (self); @@ -1959,14 +1969,8 @@ clutter_actor_real_unrealize (ClutterActor *self) * may not be expecting. * * This function should not be called by application code. - */ -void -clutter_actor_unrealize (ClutterActor *self) -{ - g_return_if_fail (CLUTTER_IS_ACTOR (self)); - g_return_if_fail (!CLUTTER_ACTOR_IS_MAPPED (self)); - -/* This function should not really be in the public API, because + * + * This function should not really be in the public API, because * there isn't a good reason to call it. ClutterActor will already * unrealize things for you when it's important to do so. * @@ -1978,12 +1982,26 @@ clutter_actor_unrealize (ClutterActor *self) * unrealizing children of your container, then don't, ClutterActor * will already take care of that. * - * If you were using clutter_actor_unrealize() to re-realize to + * Deprecated: 1.16: Actors are automatically unrealized, and nothing + * requires explicit realization. + */ +void +clutter_actor_unrealize (ClutterActor *self) +{ + g_return_if_fail (CLUTTER_IS_ACTOR (self)); + g_return_if_fail (!CLUTTER_ACTOR_IS_MAPPED (self)); + + clutter_actor_unrealize_internal (self); +} + +/* If you were using clutter_actor_unrealize() to re-realize to * create your resources in a different way, then use * _clutter_actor_rerealize() (inside Clutter) or just call your * code that recreates your resources directly (outside Clutter). */ - +static void +clutter_actor_unrealize_internal (ClutterActor *self) +{ #ifdef CLUTTER_ENABLE_DEBUG clutter_actor_verify_map_state (self); #endif @@ -8169,11 +8187,14 @@ clutter_actor_class_init (ClutterActorClass *klass) * realized. * * Since: 0.8 + * + * Deprecated: 1.16: The signal should not be used in newly + * written code */ actor_signals[REALIZE] = g_signal_new (I_("realize"), G_TYPE_FROM_CLASS (object_class), - G_SIGNAL_RUN_LAST, + G_SIGNAL_RUN_LAST | G_SIGNAL_DEPRECATED, G_STRUCT_OFFSET (ClutterActorClass, realize), NULL, NULL, _clutter_marshal_VOID__VOID, @@ -8186,11 +8207,14 @@ clutter_actor_class_init (ClutterActorClass *klass) * unrealized. * * Since: 0.8 + * + * Deprecated: 1.16: The signal should not be used in newly + * written code */ actor_signals[UNREALIZE] = g_signal_new (I_("unrealize"), G_TYPE_FROM_CLASS (object_class), - G_SIGNAL_RUN_LAST, + G_SIGNAL_RUN_LAST | G_SIGNAL_DEPRECATED, G_STRUCT_OFFSET (ClutterActorClass, unrealize), NULL, NULL, _clutter_marshal_VOID__VOID, diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h index 50e9e04d5..9ba1018ab 100644 --- a/clutter/clutter-actor.h +++ b/clutter/clutter-actor.h @@ -129,9 +129,13 @@ struct _ClutterActor * clutter_actor_hide(). This virtual function is deprecated and it * should not be overridden. * @realize: virtual function, used to allocate resources for the actor; - * it should chain up to the parent's implementation + * it should chain up to the parent's implementation. This virtual + * function is deprecated and should not be overridden in newly + * written code. * @unrealize: virtual function, used to deallocate resources allocated - * in ::realize; it should chain up to the parent's implementation + * in ::realize; it should chain up to the parent's implementation. This + * function is deprecated and should not be overridden in newly + * written code. * @map: virtual function for containers and composite actors, to * map their children; it must chain up to the parent's implementation. * Overriding this function is optional. @@ -147,12 +151,13 @@ struct _ClutterActor * clutter_actor_get_preferred_height() * @allocate: virtual function, used when settings the coordinates of an * actor; it is used by clutter_actor_allocate(); it must chain up to - * the parent's implementation + * the parent's implementation, or call clutter_actor_set_allocation() * @apply_transform: virtual function, used when applying the transformations * to an actor before painting it or when transforming coordinates or * the allocation; it must chain up to the parent's implementation * @parent_set: signal class handler for the #ClutterActor::parent-set - * @destroy: signal class handler for #ClutterActor::destroy + * @destroy: signal class handler for #ClutterActor::destroy. It must + * chain up to the parent's implementation * @pick: virtual function, used to draw an outline of the actor with * the given color * @queue_redraw: class handler for #ClutterActor::queue-redraw