mirror of
https://github.com/brl/mutter.git
synced 2024-12-24 12:02:04 +00:00
docs: Update the actor invariants
• 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:
parent
4b6156a57a
commit
242de47c03
@ -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$
|
|
||||||
|
Loading…
Reference in New Issue
Block a user