2dbbee28d5
* clutter/clutter-actor.c:
* clutter/clutter-actor.h:
Clean up of parenting code (see #972)
Doc updates to section intro.
Add clutter_actor_allocate_preferred_size () utility call
* clutter/clutter-group.c: (clutter_fixed_layout_allocate):
Use clutter_actor_allocate_preferred_size ()
* doc/clutter-actor-invariants.txt:
Add some more notes
197 lines
6.1 KiB
Plaintext
197 lines
6.1 KiB
Plaintext
ClutterActor Invariants
|
|
===============================================================================
|
|
|
|
ClutterActor behaviour has invariants that will be kept with the same API and
|
|
ABI guarantees as the whole Clutter library.
|
|
|
|
This document refers to the 0.8 release of Clutter.
|
|
|
|
Sections:
|
|
|
|
i. Flags
|
|
a. Public ClutterActor Flags
|
|
b. Private ClutterActor Flags
|
|
c. Private Pick Modes
|
|
ii. Invariants
|
|
iii. State changes
|
|
iv. Responsibilities of a ClutterActor
|
|
a. Adding to a container
|
|
b. Removing from a container
|
|
c. Initial state
|
|
|
|
i. Flags
|
|
-------------------------------------------------------------------------------
|
|
|
|
This section describes the various flags and enumerations used by
|
|
ClutterActor.
|
|
|
|
a. Public ClutterActor Flags
|
|
|
|
CLUTTER_ACTOR_REALIZED
|
|
Set by clutter_actor_realize(), unset by clutter_actor_unrealize().
|
|
Means: the actor has GPU resources associated to its paint cycle.
|
|
Once realized an actor needs to be explicitly unrealized unless
|
|
being destroyed. Hide, reparent etc will not unrealize.
|
|
|
|
CLUTTER_ACTOR_MAPPED
|
|
Set by clutter_actor_show(), unset by clutter_actor_hide()
|
|
May only be set if CLUTTER_ACTOR_IS_REALIZED (actor).
|
|
Means: the actor has been set as visible
|
|
|
|
CLUTTER_ACTOR_VISIBLE
|
|
Implies: CLUTTER_ACTOR_IS_REALIZED (actor)
|
|
&&
|
|
CLUTTER_ACTOR_IS_MAPPED (actor)
|
|
|
|
CLUTTER_ACTOR_REACTIVE
|
|
Set and unset by clutter_actor_set_reactive()
|
|
Means: the actor is now reactive to events.
|
|
Notes:
|
|
* If parents need to be reactive for child its up to the
|
|
parent implementation. In the case of ClutterGroup it
|
|
being marked unreactive does not mark all children unreactive.
|
|
* Clutter stage is always reactive.
|
|
|
|
|
|
b. Private ClutterActor flags
|
|
|
|
CLUTTER_ACTOR_IN_DESTRUCTION
|
|
Set internally by clutter_actor_destroy().
|
|
Used to avoid uneeded overhead when freeing GPU resources on unrealize
|
|
|
|
CLUTTER_ACTOR_IS_TOPLEVEL
|
|
Set internally by the initialization of ClutterStage
|
|
|
|
CLUTTER_ACTOR_IN_REPARENT
|
|
Set internally by clutter_actor_reparent()
|
|
|
|
CLUTTER_ACTOR_SYNC_MATRICES
|
|
Set internally by ClutterStage implementations
|
|
Means: the size of the stage changed and the viewport must be
|
|
synchronized to the new size
|
|
|
|
CLUTTER_ACTOR_IN_PAINT:
|
|
Set internally by clutter_actor_paint()
|
|
|
|
CLUTTER_ACTOR_IN_RELAYOUT
|
|
Set internally by clutter_relayout()
|
|
|
|
c. Private Pick Modes
|
|
|
|
CLUTTER_PICK_NONE
|
|
No pick operation is performed during the paint
|
|
|
|
CLUTTER_PICK_REACTIVE
|
|
Only reactive actors will be picked
|
|
|
|
CLUTTER_PICK_ALL
|
|
All visible actors will be picked
|
|
|
|
ii. Invariants
|
|
-------------------------------------------------------------------------------
|
|
|
|
This section describes the various constraints and invariants on ClutterActor.
|
|
|
|
In the following
|
|
|
|
A => B means if A is true then B is true
|
|
A <=> B means A is true if and only if B is true
|
|
(equivalent to A => B && A <= B)
|
|
|
|
1) CLUTTER_ACTOR_IN_DESTRUCTION => !CLUTTER_ACTOR_IS_MAPPED (actor) &&
|
|
!CLUTTER_ACTOR_IS_REALIZED (actor)
|
|
|
|
clutter_actor_destroy() will cause an actor to be hidden
|
|
and unrealized.
|
|
|
|
2) CLUTTER_ACTOR_IS_MAPPED (actor) => CLUTTER_ACTOR_IS_REALIZED (actor)
|
|
|
|
calling clutter_actor_show() on an unrealized actor will cause
|
|
a realization to happen.
|
|
|
|
3) if clutter_actor_set_parent (actor, parent):
|
|
CLUTTER_ACTOR_IS_REALIZED (parent) => CLUTTER_ACTOR_IS_REALIZED (actor)
|
|
|
|
calling clutter_actor_set_parent() on an actor and a realized
|
|
parent will cause a realization on the actor.
|
|
|
|
4) if clutter_actor_unparent (actor):
|
|
CLUTTER_ACTOR_IS_MAPPED (actor) <=> CLUTTER_ACTOR_IN_REPARENT
|
|
|
|
calling clutter_actor_unparent() on an actor will hide the actor;
|
|
calling clutter_actor_reparent() on an actor will leave the actor
|
|
in the same state.
|
|
Niether will unrealize.
|
|
|
|
iii. State changes
|
|
-------------------------------------------------------------------------------
|
|
|
|
clutter_actor_show:
|
|
1. if !CLUTTER_ACTOR_REALIZED calls clutter_actor_realize
|
|
2. sets CLUTTER_ACTOR_MAPPED
|
|
|
|
clutter_actor_hide:
|
|
1. sets !CLUTTER_ACTOR_MAPPED
|
|
|
|
clutter_actor_destroy:
|
|
1. sets CLUTTER_ACTOR_IN_DESTRUCTION
|
|
|
|
clutter_actor_realize:
|
|
sets CLUTTER_ACTOR_REALIZED
|
|
|
|
clutter_actor_unrealized:
|
|
1. if CLUTTER_ACTOR_MAPPED calls clutter_actor_hide
|
|
2. sets !CLUTTER_ACTOR_REALIZED
|
|
|
|
clutter_actor_set_parent:
|
|
1. sets actor->parent
|
|
2. if parent is CLUTTER_ACTOR_REALIZED calls clutter_actor_realize
|
|
3. if actor->show_on_set_parent is TRUE calls clutter_actor_show
|
|
|
|
clutter_actor_unset_parent:
|
|
1. unsets actor->parent
|
|
2. if !CLUTTER_ACTOR_IN_REPARENT calls clutter_actor_hide
|
|
|
|
clutter_actor_reparent:
|
|
sets CLUTTER_ACTOR_IN_REPARENT
|
|
equivalent to:
|
|
clutter_actor_unparent
|
|
clutter_actor_set_parent
|
|
|
|
iv. Responsibilities of a ClutterActor
|
|
-------------------------------------------------------------------------------
|
|
|
|
a. Adding to a container
|
|
|
|
When adding an actor to a container, the container must:
|
|
|
|
1. call clutter_actor_set_parent (actor, container)
|
|
2. call clutter_actor_queue_relayout (container)
|
|
|
|
b. Removing from a container
|
|
|
|
When removing an actor from a container, the container must:
|
|
|
|
1. call clutter_actor_unparent (actor)
|
|
2. call clutter_actor_queue_relayout (container)
|
|
|
|
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 hide 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
|
|
|
|
When creating an actor, the initial state is:
|
|
|
|
1. !CLUTTER_ACTOR_REALIZED
|
|
2. !CLUTTER_ACTOR_MAPPED
|
|
3. !CLUTTER_ACTOR_REACTIVE
|
|
===============================================================================
|
|
$LastChangedDate$
|