isa/mutter
1
0
Fork 0
mirror of https://github.com/brl/mutter.git synced 2024-12-25 04:22:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update the actor invariants

Browse Source 
• Clear up what's deprecated.
• Remove mentions of set_parent/unparent, and use add_child/remove_child
  instead.
• Clarify that reparent may not touch the MAPPED state.
This commit is contained in:
Emmanuele Bassi 2012-02-02 11:07:14 +00:00
parent 4b6156a57a
commit 242de47c03
1 changed files with 16 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
doc/actor-invariants.txt
View File

@ -67,6 +67,9 @@ CLUTTER_ACTOR_MAPPED
the "normal" way for realization to occur, though explicit the "normal" way for realization to occur, though explicit
realization with clutter_actor_realize() is permitted. realization with clutter_actor_realize() is permitted.
Reparent may not change the MAPPED flag if the old and the
new parent are both MAPPED.
CLUTTER_ACTOR_VISIBLE CLUTTER_ACTOR_VISIBLE
Means: the actor's "visible" property was set to true by Means: the actor's "visible" property was set to true by
the application programmer. the application programmer.
@ -101,27 +104,19 @@ CLUTTER_ACTOR_IN_DESTRUCTION
CLUTTER_ACTOR_IS_TOPLEVEL CLUTTER_ACTOR_IS_TOPLEVEL
Set internally by the initialization of ClutterStage Set internally by the initialization of ClutterStage
CLUTTER_ACTOR_IN_REPARENT CLUTTER_ACTOR_IN_REPARENT [DEPRECATED]
Set internally by clutter_actor_reparent(). This flag Set internally by clutter_actor_reparent(). This flag
optimizes the reparent process by avoiding the need optimizes the reparent process by avoiding the need
to pass through an unrealized state when the actor is to pass through an unrealized state when the actor is
removed from the old parent. removed from the old parent.
CLUTTER_ACTOR_ABOUT_TO_UNPARENT
Set internally during part of clutter_actor_unparent().
Causes the actor to pretend it has no parent, then
update invariants; which effectively forces the actor
to unrealize. The purpose of this is to unrealize _before_ the
actor is removed from the stage, so unrealize implementations
can use clutter_actor_get_stage().
CLUTTER_ACTOR_IN_PAINT: CLUTTER_ACTOR_IN_PAINT:
Set internally by clutter_actor_paint() Set internally by clutter_actor_paint()
CLUTTER_ACTOR_IN_RELAYOUT CLUTTER_ACTOR_IN_RELAYOUT
Set internally by clutter_relayout() Set internally by clutter_actor_allocate()
c. Private Pick Modes c. Pick Modes
CLUTTER_PICK_NONE CLUTTER_PICK_NONE
No pick operation is performed during the paint No pick operation is performed during the paint
@ -156,25 +151,25 @@ In the following
This is the most common way an actor becomes realized. This is the most common way an actor becomes realized.
3) if clutter_actor_set_parent (actor, parent): 3) if clutter_actor_add_child (parent, actor):
((parent_is_not_toplevel && CLUTTER_ACTOR_IS_MAPPED (parent)) || ((parent_is_not_toplevel && CLUTTER_ACTOR_IS_MAPPED (parent)) ||
(parent_is_toplevel && CLUTTER_ACTOR_IS_VISIBLE(parent))) && (parent_is_toplevel && CLUTTER_ACTOR_IS_VISIBLE(parent))) &&
CLUTTER_ACTOR_IS_VISIBLE (actor) CLUTTER_ACTOR_IS_VISIBLE (actor)
=> CLUTTER_ACTOR_IS_MAPPED (actor) => CLUTTER_ACTOR_IS_MAPPED (actor)
calling clutter_actor_set_parent() on an actor and a mapped calling clutter_actor_add_child() on an actor and a mapped
parent will map the actor if it has been shown. parent will map the actor if it has been shown.
4) if clutter_actor_unparent (actor): 4) if clutter_actor_remove_child (parent, actor):
CLUTTER_ACTOR_IS_MAPPED (actor) <=> CLUTTER_ACTOR_IN_REPARENT CLUTTER_ACTOR_IS_MAPPED (actor) <=> CLUTTER_ACTOR_IN_REPARENT
calling clutter_actor_unparent() on an actor will unmap and calling clutter_actor_remove_child() on an actor will unmap and
unrealize the actor since it no longer has a toplevel. unrealize the actor since it no longer has a toplevel.
calling clutter_actor_reparent() on an actor will leave the calling clutter_actor_reparent() on an actor will leave the
actor mapped and realized (if it was before) until it has a actor mapped and realized (if it was before) until it has a
new parent, at which point the invariants implied by the new new parent, at which point the invariants implied by the new
parent's state are applied. parent's state are applied. [DEPRECATED]
5) CLUTTER_ACTOR_IS_REALIZED(actor) => CLUTTER_ACTOR_IS_REALIZED(parent) 5) CLUTTER_ACTOR_IS_REALIZED(actor) => CLUTTER_ACTOR_IS_REALIZED(parent)
@ -235,21 +230,21 @@ clutter_actor_unrealize:
3. !MAPPED and !REALIZED forces unmap and unrealize of all 3. !MAPPED and !REALIZED forces unmap and unrealize of all
children children
clutter_actor_set_parent: clutter_actor_add_child:
1. sets actor->parent 1. sets actor->parent
2. if actor->show_on_set_parent is TRUE calls clutter_actor_show 2. if actor->show_on_set_parent is TRUE calls clutter_actor_show
3. sets MAPPED if all prerequisites are now met for map 3. sets MAPPED if all prerequisites are now met for map
4. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with 4. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with
old_parent set to NULL old_parent set to NULL
clutter_actor_unparent: clutter_actor_remove_child:
1. unsets actor->parent 1. unsets actor->parent
2. if !CLUTTER_ACTOR_IN_REPARENT, sets !MAPPED and !REALIZED 2. if !CLUTTER_ACTOR_IN_REPARENT, sets !MAPPED and !REALIZED
since the invariants for those flags are no longer met since the invariants for those flags are no longer met
3. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with 3. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with
old_parent set to the previous parent old_parent set to the previous parent
clutter_actor_reparent: clutter_actor_reparent: [DEPRECATED]
1. sets CLUTTER_ACTOR_IN_REPARENT 1. sets CLUTTER_ACTOR_IN_REPARENT
2. emits ::parent-set with old_parent set to the previous parent 2. emits ::parent-set with old_parent set to the previous parent
equivalent to: equivalent to:
@ -267,28 +262,13 @@ clutter_actor_reparent:
When adding an actor to a container, the container must: When adding an actor to a container, the container must:
1. call clutter_actor_set_parent (actor, container) 1. call clutter_actor_add_child (container, actor)
2. call clutter_actor_queue_relayout (container) if
adding the actor changes the container's preferred
size
b. Removing from a container b. Removing from a container
When removing an actor from a container, the container must: When removing an actor from a container, the container must:
1. call clutter_actor_unparent (actor) 1. call clutter_actor_remove_child (container, actor)
2. call clutter_actor_queue_relayout (container) if removing
the actor changes the container's preferred size
Notes:
* here a container actor is any actor that contains children actors; it
does not imply the implementation of the ClutterContainer interface.
* clutter_actor_unparent() will unmap and unrealize the actor except
in the special case when CLUTTER_ACTOR_IN_REPARENT is set.
* 'Composite' Clutter actors need to pass down any allocations to children.
c. Initial state c. Initial state
@ -296,6 +276,3 @@ When creating an actor, the initial state is:
1. !CLUTTER_ACTOR_REALIZED 1. !CLUTTER_ACTOR_REALIZED
2. !CLUTTER_ACTOR_MAPPED 2. !CLUTTER_ACTOR_MAPPED
===============================================================================
$LastChangedDate$