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
* actor is not visible.
*
* Calling this is allowed in only one case: you are implementing the
* #ClutterActor <function>map()</function> virtual function in an actor
* and you need to map the children of that actor. It is not necessary
* to call this if you implement #ClutterContainer because the default
* implementation will automatically map children of containers.
* Calling this function is strongly disencouraged: the default
* implementation of #ClutterActorClass.map() will map all the children
* of an actor when mapping its parent.
*
* When overriding map, it is mandatory to chain up to the parent
* implementation.
@ -1218,14 +1216,18 @@ clutter_actor_real_unmap (ClutterActor *self)
* Unsets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly
* unmaps its children if they were mapped.
*
* Calling this is allowed in only one case: you are implementing the
* #ClutterActor <function>unmap()</function> virtual function in an actor
* and you need to unmap the children of that actor. It is not necessary
* to call this if you implement #ClutterContainer because the default
* implementation will automatically unmap children of containers.
* Calling this function is not encouraged: the default #ClutterActor
* implementation of #ClutterActorClass.unmap() will also unmap any
* eventual children by default when their parent is unmapped.
*
* When overriding unmap, it is mandatory to chain up to the parent
* implementation.
* When overriding #ClutterActorClass.unmap(), it is mandatory to
* 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
*/