From 242de47c032eb750bd825a1d26b4b911e80527b9 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 2 Feb 2012 11:07:14 +0000 Subject: [PATCH] docs: Update the actor invariants MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit • 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. --- doc/actor-invariants.txt | 55 ++++++++++++---------------------------- 1 file changed, 16 insertions(+), 39 deletions(-) diff --git a/doc/actor-invariants.txt b/doc/actor-invariants.txt index ed66f1759..801a9fb6c 100644 --- a/doc/actor-invariants.txt +++ b/doc/actor-invariants.txt @@ -67,6 +67,9 @@ CLUTTER_ACTOR_MAPPED the "normal" way for realization to occur, though explicit 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 Means: the actor's "visible" property was set to true by the application programmer. @@ -101,27 +104,19 @@ CLUTTER_ACTOR_IN_DESTRUCTION CLUTTER_ACTOR_IS_TOPLEVEL Set internally by the initialization of ClutterStage -CLUTTER_ACTOR_IN_REPARENT +CLUTTER_ACTOR_IN_REPARENT [DEPRECATED] Set internally by clutter_actor_reparent(). This flag optimizes the reparent process by avoiding the need to pass through an unrealized state when the actor is 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: Set internally by clutter_actor_paint() 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 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. -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_toplevel && CLUTTER_ACTOR_IS_VISIBLE(parent))) && CLUTTER_ACTOR_IS_VISIBLE (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. -4) if clutter_actor_unparent (actor): +4) if clutter_actor_remove_child (parent, actor): 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. calling clutter_actor_reparent() on an actor will leave the actor mapped and realized (if it was before) until it has a 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) @@ -235,21 +230,21 @@ clutter_actor_unrealize: 3. !MAPPED and !REALIZED forces unmap and unrealize of all children -clutter_actor_set_parent: +clutter_actor_add_child: 1. sets actor->parent 2. if actor->show_on_set_parent is TRUE calls clutter_actor_show 3. sets MAPPED if all prerequisites are now met for map 4. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with old_parent set to NULL -clutter_actor_unparent: +clutter_actor_remove_child: 1. unsets actor->parent 2. if !CLUTTER_ACTOR_IN_REPARENT, sets !MAPPED and !REALIZED since the invariants for those flags are no longer met 3. if !CLUTTER_ACTOR_IN_REPARENT emits ::parent-set with old_parent set to the previous parent -clutter_actor_reparent: +clutter_actor_reparent: [DEPRECATED] 1. sets CLUTTER_ACTOR_IN_REPARENT 2. emits ::parent-set with old_parent set to the previous parent equivalent to: @@ -267,28 +262,13 @@ clutter_actor_reparent: 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) if - adding the actor changes the container's preferred - size + 1. call clutter_actor_add_child (container, actor) 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) 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. + 1. call clutter_actor_remove_child (container, actor) c. Initial state @@ -296,6 +276,3 @@ When creating an actor, the initial state is: 1. !CLUTTER_ACTOR_REALIZED 2. !CLUTTER_ACTOR_MAPPED - -=============================================================================== -$LastChangedDate$