brl/mutter
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: Clarify actor map and unmap methods

Browse Source 
ClutterActor stopped requiring to override the map and unmap virtual
functions some time ago.

Now that ClutterActor implements the Container interface, overriding map
and unmap to control the MAPPED state of the children is pretty much
going to be a source of bugs and misunderstandings.

Plus, the ordering of the unmap, destroy, dispose, and finalize calls
should be be documented properly.

The documentation should clarify all that.
This commit is contained in:
Emmanuele Bassi 2012-02-02 11:18:00 +00:00
parent 242de47c03
commit 9872d7eb1b
1 changed files with 14 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
clutter/clutter-actor.c
View File

@ -1135,11 +1135,9 @@ clutter_actor_real_map (ClutterActor *self)
* and realizes its children if they are visible. Does nothing if the * and realizes its children if they are visible. Does nothing if the
* actor is not visible. * actor is not visible.
* *
* Calling this is allowed in only one case: you are implementing the * Calling this function is strongly disencouraged: the default
* #ClutterActor <function>map()</function> virtual function in an actor * implementation of #ClutterActorClass.map() will map all the children
* and you need to map the children of that actor. It is not necessary * of an actor when mapping its parent.
* to call this if you implement #ClutterContainer because the default
* implementation will automatically map children of containers.
* *
* When overriding map, it is mandatory to chain up to the parent * When overriding map, it is mandatory to chain up to the parent
* implementation. * implementation.
@ -1218,14 +1216,18 @@ clutter_actor_real_unmap (ClutterActor *self)
* Unsets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly * Unsets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly
* unmaps its children if they were mapped. * unmaps its children if they were mapped.
* *
* Calling this is allowed in only one case: you are implementing the * Calling this function is not encouraged: the default #ClutterActor
* #ClutterActor <function>unmap()</function> virtual function in an actor * implementation of #ClutterActorClass.unmap() will also unmap any
* and you need to unmap the children of that actor. It is not necessary * eventual children by default when their parent is unmapped.
* to call this if you implement #ClutterContainer because the default
* implementation will automatically unmap children of containers.
* *
* When overriding unmap, it is mandatory to chain up to the parent * When overriding #ClutterActorClass.unmap(), it is mandatory to
* implementation. * chain up to the parent implementation.
*
* <note>It is important to note that the implementation of the
* #ClutterActorClass.unmap() virtual function may be called after
* the #ClutterActorClass.destroy() or the #GObjectClass.dispose()
* implementation, but it is guaranteed to be called before the
* #GObjectClass.finalize() implementation.</note>
* *
* Since: 1.0 * Since: 1.0
*/ */