4 * An OpenGL based 'interactive canvas' library.
6 * Authored By Matthew Allum <mallum@openedhand.com>
8 * Copyright (C) 2006, 2007, 2008 OpenedHand Ltd
9 * Copyright (C) 2009, 2010 Intel Corp
11 * This library is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU Lesser General Public
13 * License as published by the Free Software Foundation; either
14 * version 2 of the License, or (at your option) any later version.
16 * This library is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * Lesser General Public License for more details.
21 * You should have received a copy of the GNU Lesser General Public
22 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
26 * SECTION:clutter-actor
27 * @short_description: Base abstract class for all visual stage actors.
29 * The ClutterActor class is the basic element of the scene graph in Clutter,
30 * and it encapsulates the position, size, and transformations of a node in
33 * <refsect2 id="ClutterActor-transformations">
34 * <title>Actor transformations</title>
35 * <para>Each actor can be transformed using methods like
36 * clutter_actor_set_scale() or clutter_actor_set_rotation(). The order
37 * in which the transformations are applied is decided by Clutter and it is
38 * the following:</para>
40 * <listitem><para>translation by the origin of the #ClutterActor:allocation;</para></listitem>
41 * <listitem><para>translation by the actor's #ClutterActor:depth;</para></listitem>
42 * <listitem><para>scaling by the #ClutterActor:scale-x and #ClutterActor:scale-y factors;</para></listitem>
43 * <listitem><para>rotation around the #ClutterActor:rotation-z-angle and #ClutterActor:rotation-z-center;</para></listitem>
44 * <listitem><para>rotation around the #ClutterActor:rotation-y-angle and #ClutterActor:rotation-y-center;</para></listitem>
45 * <listitem><para>rotation around the #ClutterActor:rotation-x-angle and #ClutterActor:rotation-x-center;</para></listitem>
46 * <listitem><para>negative translation by the #ClutterActor:anchor-x and #ClutterActor:anchor-y point.</para></listitem>
50 * <refsect2 id="ClutterActor-geometry">
51 * <title>Modifying an actor's geometry</title>
52 * <para>Each actor has a bounding box, called #ClutterActor:allocation
53 * which is either set by its parent or explicitly through the
54 * clutter_actor_set_position() and clutter_actor_set_size() methods.
55 * Each actor also has an implicit preferred size.</para>
56 * <para>An actor’s preferred size can be defined by any subclass by
57 * overriding the #ClutterActorClass.get_preferred_width() and the
58 * #ClutterActorClass.get_preferred_height() virtual functions, or it can
59 * be explicitly set by using clutter_actor_set_width() and
60 * clutter_actor_set_height().</para>
61 * <para>An actor’s position can be set explicitly by using
62 * clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are
63 * relative to the origin of the actor’s parent.</para>
66 * <refsect2 id="ClutterActor-children">
67 * <title>Managing actor children</title>
68 * <para>Each actor can have multiple children, by calling
69 * clutter_actor_add_child() to add a new child actor, and
70 * clutter_actor_remove_child() to remove an existing child. #ClutterActor
71 * will hold a reference on each child actor, which will be released when
72 * the child is removed from its parent, or destroyed using
73 * clutter_actor_destroy().</para>
74 * <informalexample><programlisting>
75 * ClutterActor *actor = clutter_actor_new ();
77 * /* set the bounding box of the actor */
78 * clutter_actor_set_position (actor, 0, 0);
79 * clutter_actor_set_size (actor, 480, 640);
81 * /* set the background color of the actor */
82 * clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);
84 * /* set the bounding box of the child, relative to the parent */
85 * ClutterActor *child = clutter_actor_new ();
86 * clutter_actor_set_position (child, 20, 20);
87 * clutter_actor_set_size (child, 80, 240);
89 * /* set the background color of the child */
90 * clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);
92 * /* add the child to the actor */
93 * clutter_actor_add_child (actor, child);
94 * </programlisting></informalexample>
95 * <para>Children can be inserted at a given index, or above and below
96 * another child actor. The order of insertion determines the order of the
97 * children when iterating over them. Iterating over children is performed
98 * by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(),
99 * clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is
100 * also possible to retrieve a list of children by using
101 * clutter_actor_get_children(), as well as retrieving a specific child at a
102 * given index by using clutter_actor_get_child_at_index().</para>
103 * <para>If you need to track additions of children to a #ClutterActor, use
104 * the #ClutterContainer::actor-added signal; similarly, to track removals
105 * of children from a ClutterActor, use the #ClutterContainer::actor-removed
107 * <informalexample><programlisting>
108 * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../tests/interactive/test-actor.c">
109 * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
111 * </programlisting></informalexample>
112 * <figure id="actor-example-image">
113 * <title>Actors</title>
114 * <graphic fileref="actor-example.png" format="PNG"/>
118 * <refsect2 id="ClutterActor-events">
119 * <title>Handling events on an actor</title>
120 * <para>A #ClutterActor can receive and handle input device events, for
121 * instance pointer events and key events, as long as its
122 * #ClutterActor:reactive property is set to %TRUE.</para>
123 * <para>Once an actor has been determined to be the source of an event,
124 * Clutter will traverse the scene graph from the top-level actor towards the
125 * event source, emitting the #ClutterActor::captured-event signal on each
126 * ancestor until it reaches the source; this phase is also called
127 * <emphasis>the capture phase</emphasis>. If the event propagation was not
128 * stopped, the graph is walked backwards, from the source actor to the
129 * top-level, and the #ClutterActor::event signal, along with other event
130 * signals if needed, is emitted; this phase is also called <emphasis>the
131 * bubble phase</emphasis>. At any point of the signal emission, signal
132 * handlers can stop the propagation through the scene graph by returning
133 * %CLUTTER_EVENT_STOP; otherwise, they can continue the propagation by
134 * returning %CLUTTER_EVENT_PROPAGATE.</para>
137 * <refsect2 id="ClutterActor-subclassing">
138 * <title>Implementing an actor</title>
139 * <para>Careful consideration should be given when deciding to implement
140 * a #ClutterActor sub-class. It is generally recommended to implement a
141 * sub-class of #ClutterActor only for actors that should be used as leaf
142 * nodes of a scene graph.</para>
143 * <para>If your actor should be painted in a custom way, you should
144 * override the #ClutterActor::paint signal class handler. You can either
145 * opt to chain up to the parent class implementation or decide to fully
146 * override the default paint implementation; Clutter will set up the
147 * transformations and clip regions prior to emitting the #ClutterActor::paint
149 * <para>By overriding the #ClutterActorClass.get_preferred_width() and
150 * #ClutterActorClass.get_preferred_height() virtual functions it is
151 * possible to change or provide the preferred size of an actor; similarly,
152 * by overriding the #ClutterActorClass.allocate() virtual function it is
153 * possible to control the layout of the children of an actor. Make sure to
154 * always chain up to the parent implementation of the
155 * #ClutterActorClass.allocate() virtual function.</para>
156 * <para>In general, it is strongly encouraged to use delegation and
157 * composition instead of direct subclassing.</para>
160 * <refsect2 id="ClutterActor-script">
161 * <title>ClutterActor custom properties for #ClutterScript</title>
162 * <para>#ClutterActor defines a custom "rotation" property which
163 * allows a short-hand description of the rotations to be applied
164 * to an actor.</para>
165 * <para>The syntax of the "rotation" property is the following:</para>
169 * { "<axis>" : [ <angle>, [ <center> ] ] }
173 * <para>where the <emphasis>axis</emphasis> is the name of an enumeration
174 * value of type #ClutterRotateAxis and <emphasis>angle</emphasis> is a
175 * floating point value representing the rotation angle on the given axis,
177 * <para>The <emphasis>center</emphasis> array is optional, and if present
178 * it must contain the center of rotation as described by two coordinates:
179 * Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for
181 * <para>#ClutterActor will also parse every positional and dimensional
182 * property defined as a string through clutter_units_from_string(); you
183 * should read the documentation for the #ClutterUnits parser format for
184 * the valid units and syntax.</para>
187 * <refsect2 id="ClutterActor-animating">
188 * <title>Custom animatable properties</title>
189 * <para>#ClutterActor allows accessing properties of #ClutterAction
190 * and #ClutterConstraint instances associated to an actor instance
191 * for animation purposes.</para>
192 * <para>In order to access a specific #ClutterAction or a #ClutterConstraint
193 * property it is necessary to set the #ClutterActorMeta:name property on the
194 * given action or constraint.</para>
195 * <para>The property can be accessed using the following syntax:</para>
198 * @<section>.<meta-name>.<property-name>
201 * <para>The initial <emphasis>@</emphasis> is mandatory.</para>
202 * <para>The <emphasis>section</emphasis> fragment can be one between
203 * "actions", "constraints" and "effects".</para>
204 * <para>The <emphasis>meta-name</emphasis> fragment is the name of the
205 * action or constraint, as specified by the #ClutterActorMeta:name
207 * <para>The <emphasis>property-name</emphasis> fragment is the name of the
208 * action or constraint property to be animated.</para>
209 * <para>The example below animates a #ClutterBindConstraint applied to an
210 * actor using clutter_actor_animate(). The <emphasis>rect</emphasis> has
211 * a binding constraint for the <emphasis>origin</emphasis> actor, and in
212 * its initial state is fully transparent and overlapping the actor to
213 * which is bound to. </para>
214 * <informalexample><programlisting>
215 * constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
216 * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
217 * clutter_actor_add_constraint (rect, constraint);
219 * constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_Y, 0.0);
220 * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y");
221 * clutter_actor_add_constraint (rect, constraint);
223 * clutter_actor_set_reactive (rect, TRUE);
224 * clutter_actor_set_opacity (rect, 0);
226 * g_signal_connect (rect, "button-press-event",
227 * G_CALLBACK (on_button_press),
229 * </programlisting></informalexample>
230 * <para>On button press, the rectangle "slides" from behind the actor to
231 * which is bound to, using the #ClutterBindConstraint:offset property and
232 * the #ClutterActor:opacity property.</para>
233 * <informalexample><programlisting>
234 * float new_offset = clutter_actor_get_width (origin) + h_padding;
236 * clutter_actor_animate (rect, CLUTTER_EASE_OUT_CUBIC, 500,
238 * "@constraints.bind-x.offset", new_offset,
240 * </programlisting></informalexample>
245 * CLUTTER_ACTOR_IS_MAPPED:
246 * @a: a #ClutterActor
248 * Evaluates to %TRUE if the %CLUTTER_ACTOR_MAPPED flag is set.
250 * The mapped state is set when the actor is visible and all its parents up
251 * to a top-level (e.g. a #ClutterStage) are visible, realized, and mapped.
253 * This check can be used to see if an actor is going to be painted, as only
254 * actors with the %CLUTTER_ACTOR_MAPPED flag set are going to be painted.
256 * The %CLUTTER_ACTOR_MAPPED flag is managed by Clutter itself, and it should
257 * not be checked directly; instead, the recommended usage is to connect a
258 * handler on the #GObject::notify signal for the #ClutterActor:mapped
259 * property of #ClutterActor, and check the presence of
260 * the %CLUTTER_ACTOR_MAPPED flag on state changes.
262 * It is also important to note that Clutter may delay the changes of
263 * the %CLUTTER_ACTOR_MAPPED flag on top-levels due to backend-specific
264 * limitations, or during the reparenting of an actor, to optimize
265 * unnecessary (and potentially expensive) state changes.
271 * CLUTTER_ACTOR_IS_REALIZED:
272 * @a: a #ClutterActor
274 * Evaluates to %TRUE if the %CLUTTER_ACTOR_REALIZED flag is set.
276 * The realized state has an actor-dependant interpretation. If an
277 * actor wants to delay allocating resources until it is attached to a
278 * stage, it may use the realize state to do so. However it is
279 * perfectly acceptable for an actor to allocate Cogl resources before
280 * being realized because there is only one drawing context used by Clutter
281 * so any resources will work on any stage. If an actor is mapped it
282 * must also be realized, but an actor can be realized and unmapped
283 * (this is so hiding an actor temporarily doesn't do an expensive
284 * unrealize/realize).
286 * To be realized an actor must be inside a stage, and all its parents
293 * CLUTTER_ACTOR_IS_VISIBLE:
294 * @a: a #ClutterActor
296 * Evaluates to %TRUE if the actor has been shown, %FALSE if it's hidden.
297 * Equivalent to the ClutterActor::visible object property.
299 * Note that an actor is only painted onscreen if it's mapped, which
300 * means it's visible, and all its parents are visible, and one of the
301 * parents is a toplevel stage; see also %CLUTTER_ACTOR_IS_MAPPED.
307 * CLUTTER_ACTOR_IS_REACTIVE:
308 * @a: a #ClutterActor
310 * Evaluates to %TRUE if the %CLUTTER_ACTOR_REACTIVE flag is set.
312 * Only reactive actors will receive event-related signals.
323 #include "cogl/cogl.h"
325 #define CLUTTER_DISABLE_DEPRECATION_WARNINGS
326 #define CLUTTER_ENABLE_EXPERIMENTAL_API
328 #include "clutter-actor-private.h"
330 #include "clutter-action.h"
331 #include "clutter-actor-meta-private.h"
332 #include "clutter-animatable.h"
333 #include "clutter-color-static.h"
334 #include "clutter-color.h"
335 #include "clutter-constraint.h"
336 #include "clutter-container.h"
337 #include "clutter-debug.h"
338 #include "clutter-effect-private.h"
339 #include "clutter-enum-types.h"
340 #include "clutter-fixed-layout.h"
341 #include "clutter-flatten-effect.h"
342 #include "clutter-interval.h"
343 #include "clutter-main.h"
344 #include "clutter-marshal.h"
345 #include "clutter-paint-volume-private.h"
346 #include "clutter-private.h"
347 #include "clutter-profile.h"
348 #include "clutter-scriptable.h"
349 #include "clutter-script-private.h"
350 #include "clutter-stage-private.h"
351 #include "clutter-units.h"
353 #include "deprecated/clutter-actor.h"
354 #include "deprecated/clutter-behaviour.h"
355 #include "deprecated/clutter-container.h"
357 #define CLUTTER_ACTOR_GET_PRIVATE(obj) \
358 (G_TYPE_INSTANCE_GET_PRIVATE ((obj), CLUTTER_TYPE_ACTOR, ClutterActorPrivate))
360 /* Internal enum used to control mapped state update. This is a hint
361 * which indicates when to do something other than just enforce
365 MAP_STATE_CHECK, /* just enforce invariants. */
366 MAP_STATE_MAKE_UNREALIZED, /* force unrealize, ignoring invariants,
367 * used when about to unparent.
369 MAP_STATE_MAKE_MAPPED, /* set mapped, error if invariants not met;
370 * used to set mapped on toplevels.
372 MAP_STATE_MAKE_UNMAPPED /* set unmapped, even if parent is mapped,
373 * used just before unmapping parent.
377 /* 3 entries should be a good compromise, few layout managers
378 * will ask for 3 different preferred size in each allocation cycle */
379 #define N_CACHED_SIZE_REQUESTS 3
381 struct _ClutterActorPrivate
384 ClutterRequestMode request_mode;
386 /* our cached size requests for different width / height */
387 SizeRequest width_requests[N_CACHED_SIZE_REQUESTS];
388 SizeRequest height_requests[N_CACHED_SIZE_REQUESTS];
390 /* An age of 0 means the entry is not set */
391 guint cached_height_age;
392 guint cached_width_age;
394 /* the bounding box of the actor, relative to the parent's
397 ClutterActorBox allocation;
398 ClutterAllocationFlags allocation_flags;
403 /* clip, in actor coordinates */
404 cairo_rectangle_t clip;
406 /* the cached transformation matrix; see apply_transform() */
407 CoglMatrix transform;
410 gint opacity_override;
412 ClutterOffscreenRedirect offscreen_redirect;
414 /* This is an internal effect used to implement the
415 offscreen-redirect property */
416 ClutterEffect *flatten_effect;
419 ClutterActor *parent;
420 ClutterActor *prev_sibling;
421 ClutterActor *next_sibling;
422 ClutterActor *first_child;
423 ClutterActor *last_child;
427 /* tracks whenever the children of an actor are changed; the
428 * age is incremented by 1 whenever an actor is added or
429 * removed. the age is not incremented when the first or the
430 * last child pointers are changed, or when grandchildren of
431 * an actor are changed.
435 gchar *name; /* a non-unique name, used for debugging */
436 guint32 id; /* unique id, used for backward compatibility */
438 gint32 pick_id; /* per-stage unique id, used for picking */
440 /* a back-pointer to the Pango context that we can use
441 * to create pre-configured PangoLayout
443 PangoContext *pango_context;
445 /* the text direction configured for this child - either by
446 * application code, or by the actor's parent
448 ClutterTextDirection text_direction;
450 /* a counter used to toggle the CLUTTER_INTERNAL_CHILD flag */
454 ClutterMetaGroup *actions;
455 ClutterMetaGroup *constraints;
456 ClutterMetaGroup *effects;
458 /* delegate object used to allocate the children of this actor */
459 ClutterLayoutManager *layout_manager;
461 /* used when painting, to update the paint volume */
462 ClutterEffect *current_effect;
464 /* This is used to store an effect which needs to be redrawn. A
465 redraw can be queued to start from a particular effect. This is
466 used by parametrised effects that can cache an image of the
467 actor. If a parameter of the effect changes then it only needs to
468 redraw the cached image, not the actual actor. The pointer is
469 only valid if is_dirty == TRUE. If the pointer is NULL then the
470 whole actor is dirty. */
471 ClutterEffect *effect_to_redraw;
473 /* This is used when painting effects to implement the
474 clutter_actor_continue_paint() function. It points to the node in
475 the list of effects that is next in the chain */
476 const GList *next_effect_to_paint;
478 ClutterPaintVolume paint_volume;
480 /* NB: This volume isn't relative to this actor, it is in eye
481 * coordinates so that it can remain valid after the actor changes.
483 ClutterPaintVolume last_paint_volume;
485 ClutterStageQueueRedrawEntry *queue_redraw_entry;
487 ClutterColor bg_color;
491 /* fixed position and sizes */
492 guint position_set : 1;
493 guint min_width_set : 1;
494 guint min_height_set : 1;
495 guint natural_width_set : 1;
496 guint natural_height_set : 1;
497 /* cached request is invalid (implies allocation is too) */
498 guint needs_width_request : 1;
499 /* cached request is invalid (implies allocation is too) */
500 guint needs_height_request : 1;
501 /* cached allocation is invalid (request has changed, probably) */
502 guint needs_allocation : 1;
503 guint show_on_set_parent : 1;
505 guint clip_to_allocation : 1;
506 guint enable_model_view_transform : 1;
507 guint enable_paint_unmapped : 1;
508 guint has_pointer : 1;
509 guint propagated_one_redraw : 1;
510 guint paint_volume_valid : 1;
511 guint last_paint_volume_valid : 1;
512 guint in_clone_paint : 1;
513 guint transform_valid : 1;
514 /* This is TRUE if anything has queued a redraw since we were last
515 painted. In this case effect_to_redraw will point to an effect
516 the redraw was queued from or it will be NULL if the redraw was
517 queued without an effect. */
519 guint bg_color_set : 1;
528 /* X, Y, WIDTH, HEIGHT are "do what I mean" properties;
529 * when set they force a size request, when gotten they
530 * get the allocation if the allocation is valid, and the
538 /* Then the rest of these size-related properties are the "actual"
539 * underlying properties set or gotten by X, Y, WIDTH, HEIGHT
544 PROP_FIXED_POSITION_SET,
553 PROP_NATURAL_WIDTH_SET,
556 PROP_NATURAL_HEIGHT_SET,
560 /* Allocation properties are read-only */
567 PROP_CLIP_TO_ALLOCATION,
571 PROP_OFFSCREEN_REDIRECT,
584 PROP_ROTATION_ANGLE_X,
585 PROP_ROTATION_ANGLE_Y,
586 PROP_ROTATION_ANGLE_Z,
587 PROP_ROTATION_CENTER_X,
588 PROP_ROTATION_CENTER_Y,
589 PROP_ROTATION_CENTER_Z,
590 /* This property only makes sense for the z rotation because the
591 others would depend on the actor having a size along the
593 PROP_ROTATION_CENTER_Z_GRAVITY,
599 PROP_SHOW_ON_SET_PARENT,
617 PROP_BACKGROUND_COLOR,
618 PROP_BACKGROUND_COLOR_SET,
626 static GParamSpec *obj_props[PROP_LAST];
645 BUTTON_RELEASE_EVENT,
657 static guint actor_signals[LAST_SIGNAL] = { 0, };
659 static void clutter_container_iface_init (ClutterContainerIface *iface);
660 static void clutter_scriptable_iface_init (ClutterScriptableIface *iface);
661 static void clutter_animatable_iface_init (ClutterAnimatableIface *iface);
662 static void atk_implementor_iface_init (AtkImplementorIface *iface);
664 /* These setters are all static for now, maybe they should be in the
665 * public API, but they are perhaps obscure enough to leave only as
668 static void clutter_actor_set_min_width (ClutterActor *self,
670 static void clutter_actor_set_min_height (ClutterActor *self,
672 static void clutter_actor_set_natural_width (ClutterActor *self,
673 gfloat natural_width);
674 static void clutter_actor_set_natural_height (ClutterActor *self,
675 gfloat natural_height);
676 static void clutter_actor_set_min_width_set (ClutterActor *self,
677 gboolean use_min_width);
678 static void clutter_actor_set_min_height_set (ClutterActor *self,
679 gboolean use_min_height);
680 static void clutter_actor_set_natural_width_set (ClutterActor *self,
681 gboolean use_natural_width);
682 static void clutter_actor_set_natural_height_set (ClutterActor *self,
683 gboolean use_natural_height);
684 static void clutter_actor_update_map_state (ClutterActor *self,
685 MapStateChange change);
686 static void clutter_actor_unrealize_not_hiding (ClutterActor *self);
688 /* Helper routines for managing anchor coords */
689 static void clutter_anchor_coord_get_units (ClutterActor *self,
690 const AnchorCoord *coord,
694 static void clutter_anchor_coord_set_units (AnchorCoord *coord,
699 static ClutterGravity clutter_anchor_coord_get_gravity (const AnchorCoord *coord);
700 static void clutter_anchor_coord_set_gravity (AnchorCoord *coord,
701 ClutterGravity gravity);
703 static gboolean clutter_anchor_coord_is_zero (const AnchorCoord *coord);
705 static void _clutter_actor_queue_only_relayout (ClutterActor *self);
707 static void _clutter_actor_get_relative_transformation_matrix (ClutterActor *self,
708 ClutterActor *ancestor,
711 static ClutterPaintVolume *_clutter_actor_get_paint_volume_mutable (ClutterActor *self);
713 static guint8 clutter_actor_get_paint_opacity_internal (ClutterActor *self);
715 static void on_layout_manager_changed (ClutterLayoutManager *manager,
718 /* Helper macro which translates by the anchor coord, applies the
719 given transformation and then translates back */
720 #define TRANSFORM_ABOUT_ANCHOR_COORD(a,m,c,_transform) G_STMT_START { \
721 gfloat _tx, _ty, _tz; \
722 clutter_anchor_coord_get_units ((a), (c), &_tx, &_ty, &_tz); \
723 cogl_matrix_translate ((m), _tx, _ty, _tz); \
725 cogl_matrix_translate ((m), -_tx, -_ty, -_tz); } G_STMT_END
727 static GQuark quark_shader_data = 0;
728 static GQuark quark_actor_layout_info = 0;
729 static GQuark quark_actor_transform_info = 0;
731 G_DEFINE_TYPE_WITH_CODE (ClutterActor,
733 G_TYPE_INITIALLY_UNOWNED,
734 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_CONTAINER,
735 clutter_container_iface_init)
736 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_SCRIPTABLE,
737 clutter_scriptable_iface_init)
738 G_IMPLEMENT_INTERFACE (CLUTTER_TYPE_ANIMATABLE,
739 clutter_animatable_iface_init)
740 G_IMPLEMENT_INTERFACE (ATK_TYPE_IMPLEMENTOR,
741 atk_implementor_iface_init));
744 * clutter_actor_get_debug_name:
745 * @actor: a #ClutterActor
747 * Retrieves a printable name of @actor for debugging messages
749 * Return value: a string with a printable name
752 _clutter_actor_get_debug_name (ClutterActor *actor)
754 return actor->priv->name != NULL ? actor->priv->name
755 : G_OBJECT_TYPE_NAME (actor);
758 #ifdef CLUTTER_ENABLE_DEBUG
759 /* XXX - this is for debugging only, remove once working (or leave
760 * in only in some debug mode). Should leave it for a little while
761 * until we're confident in the new map/realize/visible handling.
764 clutter_actor_verify_map_state (ClutterActor *self)
766 ClutterActorPrivate *priv = self->priv;
768 if (CLUTTER_ACTOR_IS_REALIZED (self))
770 /* all bets are off during reparent when we're potentially realized,
771 * but should not be according to invariants
773 if (!CLUTTER_ACTOR_IN_REPARENT (self))
775 if (priv->parent == NULL)
777 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
781 g_warning ("Realized non-toplevel actor '%s' should "
783 _clutter_actor_get_debug_name (self));
785 else if (!CLUTTER_ACTOR_IS_REALIZED (priv->parent))
787 g_warning ("Realized actor %s has an unrealized parent %s",
788 _clutter_actor_get_debug_name (self),
789 _clutter_actor_get_debug_name (priv->parent));
794 if (CLUTTER_ACTOR_IS_MAPPED (self))
796 if (!CLUTTER_ACTOR_IS_REALIZED (self))
797 g_warning ("Actor '%s' is mapped but not realized",
798 _clutter_actor_get_debug_name (self));
800 /* remaining bets are off during reparent when we're potentially
801 * mapped, but should not be according to invariants
803 if (!CLUTTER_ACTOR_IN_REPARENT (self))
805 if (priv->parent == NULL)
807 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
809 if (!CLUTTER_ACTOR_IS_VISIBLE (self) &&
810 !CLUTTER_ACTOR_IN_DESTRUCTION (self))
812 g_warning ("Toplevel actor '%s' is mapped "
814 _clutter_actor_get_debug_name (self));
819 g_warning ("Mapped actor '%s' should have a parent",
820 _clutter_actor_get_debug_name (self));
825 ClutterActor *iter = self;
827 /* check for the enable_paint_unmapped flag on the actor
828 * and parents; if the flag is enabled at any point of this
829 * branch of the scene graph then all the later checks
834 if (iter->priv->enable_paint_unmapped)
837 iter = iter->priv->parent;
840 if (!CLUTTER_ACTOR_IS_VISIBLE (priv->parent))
842 g_warning ("Actor '%s' should not be mapped if parent '%s'"
844 _clutter_actor_get_debug_name (self),
845 _clutter_actor_get_debug_name (priv->parent));
848 if (!CLUTTER_ACTOR_IS_REALIZED (priv->parent))
850 g_warning ("Actor '%s' should not be mapped if parent '%s'"
852 _clutter_actor_get_debug_name (self),
853 _clutter_actor_get_debug_name (priv->parent));
856 if (!CLUTTER_ACTOR_IS_TOPLEVEL (priv->parent))
858 if (!CLUTTER_ACTOR_IS_MAPPED (priv->parent))
859 g_warning ("Actor '%s' is mapped but its non-toplevel "
860 "parent '%s' is not mapped",
861 _clutter_actor_get_debug_name (self),
862 _clutter_actor_get_debug_name (priv->parent));
869 #endif /* CLUTTER_ENABLE_DEBUG */
872 clutter_actor_set_mapped (ClutterActor *self,
875 if (CLUTTER_ACTOR_IS_MAPPED (self) == mapped)
880 CLUTTER_ACTOR_GET_CLASS (self)->map (self);
881 g_assert (CLUTTER_ACTOR_IS_MAPPED (self));
885 CLUTTER_ACTOR_GET_CLASS (self)->unmap (self);
886 g_assert (!CLUTTER_ACTOR_IS_MAPPED (self));
890 /* this function updates the mapped and realized states according to
891 * invariants, in the appropriate order.
894 clutter_actor_update_map_state (ClutterActor *self,
895 MapStateChange change)
899 was_mapped = CLUTTER_ACTOR_IS_MAPPED (self);
901 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
903 /* the mapped flag on top-level actors must be set by the
904 * per-backend implementation because it might be asynchronous.
906 * That is, the MAPPED flag on toplevels currently tracks the X
907 * server mapped-ness of the window, while the expected behavior
908 * (if used to GTK) may be to track WM_STATE!=WithdrawnState.
909 * This creates some weird complexity by breaking the invariant
910 * that if we're visible and all ancestors shown then we are
911 * also mapped - instead, we are mapped if all ancestors
912 * _possibly excepting_ the stage are mapped. The stage
913 * will map/unmap for example when it is minimized or
914 * moved to another workspace.
916 * So, the only invariant on the stage is that if visible it
917 * should be realized, and that it has to be visible to be
920 if (CLUTTER_ACTOR_IS_VISIBLE (self))
921 clutter_actor_realize (self);
925 case MAP_STATE_CHECK:
928 case MAP_STATE_MAKE_MAPPED:
929 g_assert (!was_mapped);
930 clutter_actor_set_mapped (self, TRUE);
933 case MAP_STATE_MAKE_UNMAPPED:
934 g_assert (was_mapped);
935 clutter_actor_set_mapped (self, FALSE);
938 case MAP_STATE_MAKE_UNREALIZED:
939 /* we only use MAKE_UNREALIZED in unparent,
940 * and unparenting a stage isn't possible.
941 * If someone wants to just unrealize a stage
942 * then clutter_actor_unrealize() doesn't
943 * go through this codepath.
945 g_warning ("Trying to force unrealize stage is not allowed");
949 if (CLUTTER_ACTOR_IS_MAPPED (self) &&
950 !CLUTTER_ACTOR_IS_VISIBLE (self) &&
951 !CLUTTER_ACTOR_IN_DESTRUCTION (self))
953 g_warning ("Clutter toplevel of type '%s' is not visible, but "
954 "it is somehow still mapped",
955 _clutter_actor_get_debug_name (self));
960 ClutterActorPrivate *priv = self->priv;
961 ClutterActor *parent = priv->parent;
962 gboolean should_be_mapped;
963 gboolean may_be_realized;
964 gboolean must_be_realized;
966 should_be_mapped = FALSE;
967 may_be_realized = TRUE;
968 must_be_realized = FALSE;
970 if (parent == NULL || change == MAP_STATE_MAKE_UNREALIZED)
972 may_be_realized = FALSE;
976 /* Maintain invariant that if parent is mapped, and we are
977 * visible, then we are mapped ... unless parent is a
978 * stage, in which case we map regardless of parent's map
979 * state but do require stage to be visible and realized.
981 * If parent is realized, that does not force us to be
982 * realized; but if parent is unrealized, that does force
983 * us to be unrealized.
985 * The reason we don't force children to realize with
986 * parents is _clutter_actor_rerealize(); if we require that
987 * a realized parent means children are realized, then to
988 * unrealize an actor we would have to unrealize its
989 * parents, which would end up meaning unrealizing and
990 * hiding the entire stage. So we allow unrealizing a
991 * child (as long as that child is not mapped) while that
992 * child still has a realized parent.
994 * Also, if we unrealize from leaf nodes to root, and
995 * realize from root to leaf, the invariants are never
996 * violated if we allow children to be unrealized
997 * while parents are realized.
999 * When unmapping, MAP_STATE_MAKE_UNMAPPED is specified
1000 * to force us to unmap, even though parent is still
1001 * mapped. This is because we're unmapping from leaf nodes
1004 if (CLUTTER_ACTOR_IS_VISIBLE (self) &&
1005 change != MAP_STATE_MAKE_UNMAPPED)
1007 gboolean parent_is_visible_realized_toplevel;
1009 parent_is_visible_realized_toplevel =
1010 (CLUTTER_ACTOR_IS_TOPLEVEL (parent) &&
1011 CLUTTER_ACTOR_IS_VISIBLE (parent) &&
1012 CLUTTER_ACTOR_IS_REALIZED (parent));
1014 if (CLUTTER_ACTOR_IS_MAPPED (parent) ||
1015 parent_is_visible_realized_toplevel)
1017 must_be_realized = TRUE;
1018 should_be_mapped = TRUE;
1022 /* if the actor has been set to be painted even if unmapped
1023 * then we should map it and check for realization as well;
1024 * this is an override for the branch of the scene graph
1025 * which begins with this node
1027 if (priv->enable_paint_unmapped)
1029 if (priv->parent == NULL)
1030 g_warning ("Attempting to map an unparented actor '%s'",
1031 _clutter_actor_get_debug_name (self));
1033 should_be_mapped = TRUE;
1034 must_be_realized = TRUE;
1037 if (!CLUTTER_ACTOR_IS_REALIZED (parent))
1038 may_be_realized = FALSE;
1041 if (change == MAP_STATE_MAKE_MAPPED && !should_be_mapped)
1044 g_warning ("Attempting to map a child that does not "
1045 "meet the necessary invariants: the actor '%s' "
1047 _clutter_actor_get_debug_name (self));
1049 g_warning ("Attempting to map a child that does not "
1050 "meet the necessary invariants: the actor '%s' "
1051 "is parented to an unmapped actor '%s'",
1052 _clutter_actor_get_debug_name (self),
1053 _clutter_actor_get_debug_name (priv->parent));
1056 /* If in reparent, we temporarily suspend unmap and unrealize.
1058 * We want to go in the order "realize, map" and "unmap, unrealize"
1062 if (!should_be_mapped && !CLUTTER_ACTOR_IN_REPARENT (self))
1063 clutter_actor_set_mapped (self, FALSE);
1066 if (must_be_realized)
1067 clutter_actor_realize (self);
1069 /* if we must be realized then we may be, presumably */
1070 g_assert (!(must_be_realized && !may_be_realized));
1073 if (!may_be_realized && !CLUTTER_ACTOR_IN_REPARENT (self))
1074 clutter_actor_unrealize_not_hiding (self);
1077 if (should_be_mapped)
1079 if (!must_be_realized)
1080 g_warning ("Somehow we think actor '%s' should be mapped but "
1081 "not realized, which isn't allowed",
1082 _clutter_actor_get_debug_name (self));
1084 /* realization is allowed to fail (though I don't know what
1085 * an app is supposed to do about that - shouldn't it just
1086 * be a g_error? anyway, we have to avoid mapping if this
1089 if (CLUTTER_ACTOR_IS_REALIZED (self))
1090 clutter_actor_set_mapped (self, TRUE);
1094 #ifdef CLUTTER_ENABLE_DEBUG
1095 /* check all invariants were kept */
1096 clutter_actor_verify_map_state (self);
1101 clutter_actor_real_map (ClutterActor *self)
1103 ClutterActorPrivate *priv = self->priv;
1104 ClutterActor *stage, *iter;
1106 g_assert (!CLUTTER_ACTOR_IS_MAPPED (self));
1108 CLUTTER_NOTE (ACTOR, "Mapping actor '%s'",
1109 _clutter_actor_get_debug_name (self));
1111 CLUTTER_ACTOR_SET_FLAGS (self, CLUTTER_ACTOR_MAPPED);
1113 stage = _clutter_actor_get_stage_internal (self);
1114 priv->pick_id = _clutter_stage_acquire_pick_id (CLUTTER_STAGE (stage), self);
1116 CLUTTER_NOTE (ACTOR, "Pick id '%d' for actor '%s'",
1118 _clutter_actor_get_debug_name (self));
1120 /* notify on parent mapped before potentially mapping
1121 * children, so apps see a top-down notification.
1123 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MAPPED]);
1125 for (iter = self->priv->first_child;
1127 iter = iter->priv->next_sibling)
1129 clutter_actor_map (iter);
1134 * clutter_actor_map:
1135 * @self: A #ClutterActor
1137 * Sets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly maps
1138 * and realizes its children if they are visible. Does nothing if the
1139 * actor is not visible.
1141 * Calling this function is strongly disencouraged: the default
1142 * implementation of #ClutterActorClass.map() will map all the children
1143 * of an actor when mapping its parent.
1145 * When overriding map, it is mandatory to chain up to the parent
1151 clutter_actor_map (ClutterActor *self)
1153 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1155 if (CLUTTER_ACTOR_IS_MAPPED (self))
1158 if (!CLUTTER_ACTOR_IS_VISIBLE (self))
1161 clutter_actor_update_map_state (self, MAP_STATE_MAKE_MAPPED);
1165 clutter_actor_real_unmap (ClutterActor *self)
1167 ClutterActorPrivate *priv = self->priv;
1170 g_assert (CLUTTER_ACTOR_IS_MAPPED (self));
1172 CLUTTER_NOTE (ACTOR, "Unmapping actor '%s'",
1173 _clutter_actor_get_debug_name (self));
1175 for (iter = self->priv->first_child;
1177 iter = iter->priv->next_sibling)
1179 clutter_actor_unmap (iter);
1182 CLUTTER_ACTOR_UNSET_FLAGS (self, CLUTTER_ACTOR_MAPPED);
1184 /* clear the contents of the last paint volume, so that hiding + moving +
1185 * showing will not result in the wrong area being repainted
1187 _clutter_paint_volume_init_static (&priv->last_paint_volume, NULL);
1188 priv->last_paint_volume_valid = TRUE;
1190 /* notify on parent mapped after potentially unmapping
1191 * children, so apps see a bottom-up notification.
1193 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MAPPED]);
1195 /* relinquish keyboard focus if we were unmapped while owning it */
1196 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
1198 ClutterStage *stage;
1200 stage = CLUTTER_STAGE (_clutter_actor_get_stage_internal (self));
1203 _clutter_stage_release_pick_id (stage, priv->pick_id);
1207 if (stage != NULL &&
1208 clutter_stage_get_key_focus (stage) == self)
1210 clutter_stage_set_key_focus (stage, NULL);
1216 * clutter_actor_unmap:
1217 * @self: A #ClutterActor
1219 * Unsets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly
1220 * unmaps its children if they were mapped.
1222 * Calling this function is not encouraged: the default #ClutterActor
1223 * implementation of #ClutterActorClass.unmap() will also unmap any
1224 * eventual children by default when their parent is unmapped.
1226 * When overriding #ClutterActorClass.unmap(), it is mandatory to
1227 * chain up to the parent implementation.
1229 * <note>It is important to note that the implementation of the
1230 * #ClutterActorClass.unmap() virtual function may be called after
1231 * the #ClutterActorClass.destroy() or the #GObjectClass.dispose()
1232 * implementation, but it is guaranteed to be called before the
1233 * #GObjectClass.finalize() implementation.</note>
1238 clutter_actor_unmap (ClutterActor *self)
1240 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1242 if (!CLUTTER_ACTOR_IS_MAPPED (self))
1245 clutter_actor_update_map_state (self, MAP_STATE_MAKE_UNMAPPED);
1249 clutter_actor_real_show (ClutterActor *self)
1251 if (!CLUTTER_ACTOR_IS_VISIBLE (self))
1253 ClutterActorPrivate *priv = self->priv;
1255 CLUTTER_ACTOR_SET_FLAGS (self, CLUTTER_ACTOR_VISIBLE);
1257 /* we notify on the "visible" flag in the clutter_actor_show()
1258 * wrapper so the entire show signal emission completes first
1261 clutter_actor_update_map_state (self, MAP_STATE_CHECK);
1263 /* we queue a relayout unless the actor is inside a
1264 * container that explicitly told us not to
1266 if (priv->parent != NULL &&
1267 (!(priv->parent->flags & CLUTTER_ACTOR_NO_LAYOUT)))
1269 /* While an actor is hidden the parent may not have
1270 * allocated/requested so we need to start from scratch
1271 * and avoid the short-circuiting in
1272 * clutter_actor_queue_relayout().
1274 priv->needs_width_request = FALSE;
1275 priv->needs_height_request = FALSE;
1276 priv->needs_allocation = FALSE;
1277 clutter_actor_queue_relayout (self);
1283 set_show_on_set_parent (ClutterActor *self,
1286 ClutterActorPrivate *priv = self->priv;
1288 set_show = !!set_show;
1290 if (priv->show_on_set_parent == set_show)
1293 if (priv->parent == NULL)
1295 priv->show_on_set_parent = set_show;
1296 g_object_notify_by_pspec (G_OBJECT (self),
1297 obj_props[PROP_SHOW_ON_SET_PARENT]);
1302 * clutter_actor_show:
1303 * @self: A #ClutterActor
1305 * Flags an actor to be displayed. An actor that isn't shown will not
1306 * be rendered on the stage.
1308 * Actors are visible by default.
1310 * If this function is called on an actor without a parent, the
1311 * #ClutterActor:show-on-set-parent will be set to %TRUE as a side
1315 clutter_actor_show (ClutterActor *self)
1317 ClutterActorPrivate *priv;
1319 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1321 /* simple optimization */
1322 if (CLUTTER_ACTOR_IS_VISIBLE (self))
1324 /* we still need to set the :show-on-set-parent property, in
1325 * case show() is called on an unparented actor
1327 set_show_on_set_parent (self, TRUE);
1331 #ifdef CLUTTER_ENABLE_DEBUG
1332 clutter_actor_verify_map_state (self);
1337 g_object_freeze_notify (G_OBJECT (self));
1339 set_show_on_set_parent (self, TRUE);
1341 g_signal_emit (self, actor_signals[SHOW], 0);
1342 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_VISIBLE]);
1344 if (priv->parent != NULL)
1345 clutter_actor_queue_redraw (priv->parent);
1347 g_object_thaw_notify (G_OBJECT (self));
1351 * clutter_actor_show_all:
1352 * @self: a #ClutterActor
1354 * Calls clutter_actor_show() on all children of an actor (if any).
1358 * Deprecated: 1.10: Actors are visible by default
1361 clutter_actor_show_all (ClutterActor *self)
1363 ClutterActorClass *klass;
1365 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1367 klass = CLUTTER_ACTOR_GET_CLASS (self);
1368 if (klass->show_all)
1369 klass->show_all (self);
1373 clutter_actor_real_hide (ClutterActor *self)
1375 if (CLUTTER_ACTOR_IS_VISIBLE (self))
1377 ClutterActorPrivate *priv = self->priv;
1379 CLUTTER_ACTOR_UNSET_FLAGS (self, CLUTTER_ACTOR_VISIBLE);
1381 /* we notify on the "visible" flag in the clutter_actor_hide()
1382 * wrapper so the entire hide signal emission completes first
1385 clutter_actor_update_map_state (self, MAP_STATE_CHECK);
1387 /* we queue a relayout unless the actor is inside a
1388 * container that explicitly told us not to
1390 if (priv->parent != NULL &&
1391 (!(priv->parent->flags & CLUTTER_ACTOR_NO_LAYOUT)))
1392 clutter_actor_queue_relayout (priv->parent);
1397 * clutter_actor_hide:
1398 * @self: A #ClutterActor
1400 * Flags an actor to be hidden. A hidden actor will not be
1401 * rendered on the stage.
1403 * Actors are visible by default.
1405 * If this function is called on an actor without a parent, the
1406 * #ClutterActor:show-on-set-parent property will be set to %FALSE
1410 clutter_actor_hide (ClutterActor *self)
1412 ClutterActorPrivate *priv;
1414 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1416 /* simple optimization */
1417 if (!CLUTTER_ACTOR_IS_VISIBLE (self))
1419 /* we still need to set the :show-on-set-parent property, in
1420 * case hide() is called on an unparented actor
1422 set_show_on_set_parent (self, FALSE);
1426 #ifdef CLUTTER_ENABLE_DEBUG
1427 clutter_actor_verify_map_state (self);
1432 g_object_freeze_notify (G_OBJECT (self));
1434 set_show_on_set_parent (self, FALSE);
1436 g_signal_emit (self, actor_signals[HIDE], 0);
1437 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_VISIBLE]);
1439 if (priv->parent != NULL)
1440 clutter_actor_queue_redraw (priv->parent);
1442 g_object_thaw_notify (G_OBJECT (self));
1446 * clutter_actor_hide_all:
1447 * @self: a #ClutterActor
1449 * Calls clutter_actor_hide() on all child actors (if any).
1453 * Deprecated: 1.10: Using clutter_actor_hide() on the actor will
1454 * prevent its children from being painted as well.
1457 clutter_actor_hide_all (ClutterActor *self)
1459 ClutterActorClass *klass;
1461 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1463 klass = CLUTTER_ACTOR_GET_CLASS (self);
1464 if (klass->hide_all)
1465 klass->hide_all (self);
1469 * clutter_actor_realize:
1470 * @self: A #ClutterActor
1472 * Realization informs the actor that it is attached to a stage. It
1473 * can use this to allocate resources if it wanted to delay allocation
1474 * until it would be rendered. However it is perfectly acceptable for
1475 * an actor to create resources before being realized because Clutter
1476 * only ever has a single rendering context so that actor is free to
1477 * be moved from one stage to another.
1479 * This function does nothing if the actor is already realized.
1481 * Because a realized actor must have realized parent actors, calling
1482 * clutter_actor_realize() will also realize all parents of the actor.
1484 * This function does not realize child actors, except in the special
1485 * case that realizing the stage, when the stage is visible, will
1486 * suddenly map (and thus realize) the children of the stage.
1489 clutter_actor_realize (ClutterActor *self)
1491 ClutterActorPrivate *priv;
1493 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1497 #ifdef CLUTTER_ENABLE_DEBUG
1498 clutter_actor_verify_map_state (self);
1501 if (CLUTTER_ACTOR_IS_REALIZED (self))
1504 /* To be realized, our parent actors must be realized first.
1505 * This will only succeed if we're inside a toplevel.
1507 if (priv->parent != NULL)
1508 clutter_actor_realize (priv->parent);
1510 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
1512 /* toplevels can be realized at any time */
1516 /* "Fail" the realization if parent is missing or unrealized;
1517 * this should really be a g_warning() not some kind of runtime
1518 * failure; how can an app possibly recover? Instead it's a bug
1519 * in the app and the app should get an explanatory warning so
1520 * someone can fix it. But for now it's too hard to fix this
1521 * because e.g. ClutterTexture needs reworking.
1523 if (priv->parent == NULL ||
1524 !CLUTTER_ACTOR_IS_REALIZED (priv->parent))
1528 CLUTTER_NOTE (ACTOR, "Realizing actor '%s'", _clutter_actor_get_debug_name (self));
1530 CLUTTER_ACTOR_SET_FLAGS (self, CLUTTER_ACTOR_REALIZED);
1531 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_REALIZED]);
1533 g_signal_emit (self, actor_signals[REALIZE], 0);
1535 /* Stage actor is allowed to unset the realized flag again in its
1536 * default signal handler, though that is a pathological situation.
1539 /* If realization "failed" we'll have to update child state. */
1540 clutter_actor_update_map_state (self, MAP_STATE_CHECK);
1544 clutter_actor_real_unrealize (ClutterActor *self)
1546 /* we must be unmapped (implying our children are also unmapped) */
1547 g_assert (!CLUTTER_ACTOR_IS_MAPPED (self));
1551 * clutter_actor_unrealize:
1552 * @self: A #ClutterActor
1554 * Unrealization informs the actor that it may be being destroyed or
1555 * moved to another stage. The actor may want to destroy any
1556 * underlying graphics resources at this point. However it is
1557 * perfectly acceptable for it to retain the resources until the actor
1558 * is destroyed because Clutter only ever uses a single rendering
1559 * context and all of the graphics resources are valid on any stage.
1561 * Because mapped actors must be realized, actors may not be
1562 * unrealized if they are mapped. This function hides the actor to be
1563 * sure it isn't mapped, an application-visible side effect that you
1564 * may not be expecting.
1566 * This function should not be called by application code.
1569 clutter_actor_unrealize (ClutterActor *self)
1571 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1572 g_return_if_fail (!CLUTTER_ACTOR_IS_MAPPED (self));
1574 /* This function should not really be in the public API, because
1575 * there isn't a good reason to call it. ClutterActor will already
1576 * unrealize things for you when it's important to do so.
1578 * If you were using clutter_actor_unrealize() in a dispose
1579 * implementation, then don't, just chain up to ClutterActor's
1582 * If you were using clutter_actor_unrealize() to implement
1583 * unrealizing children of your container, then don't, ClutterActor
1584 * will already take care of that.
1586 * If you were using clutter_actor_unrealize() to re-realize to
1587 * create your resources in a different way, then use
1588 * _clutter_actor_rerealize() (inside Clutter) or just call your
1589 * code that recreates your resources directly (outside Clutter).
1592 #ifdef CLUTTER_ENABLE_DEBUG
1593 clutter_actor_verify_map_state (self);
1596 clutter_actor_hide (self);
1598 clutter_actor_unrealize_not_hiding (self);
1601 static ClutterActorTraverseVisitFlags
1602 unrealize_actor_before_children_cb (ClutterActor *self,
1606 /* If an actor is already unrealized we know its children have also
1607 * already been unrealized... */
1608 if (!CLUTTER_ACTOR_IS_REALIZED (self))
1609 return CLUTTER_ACTOR_TRAVERSE_VISIT_SKIP_CHILDREN;
1611 g_signal_emit (self, actor_signals[UNREALIZE], 0);
1613 return CLUTTER_ACTOR_TRAVERSE_VISIT_CONTINUE;
1616 static ClutterActorTraverseVisitFlags
1617 unrealize_actor_after_children_cb (ClutterActor *self,
1621 /* We want to unset the realized flag only _after_
1622 * child actors are unrealized, to maintain invariants.
1624 CLUTTER_ACTOR_UNSET_FLAGS (self, CLUTTER_ACTOR_REALIZED);
1625 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_REALIZED]);
1626 return CLUTTER_ACTOR_TRAVERSE_VISIT_CONTINUE;
1630 * clutter_actor_unrealize_not_hiding:
1631 * @self: A #ClutterActor
1633 * Unrealization informs the actor that it may be being destroyed or
1634 * moved to another stage. The actor may want to destroy any
1635 * underlying graphics resources at this point. However it is
1636 * perfectly acceptable for it to retain the resources until the actor
1637 * is destroyed because Clutter only ever uses a single rendering
1638 * context and all of the graphics resources are valid on any stage.
1640 * Because mapped actors must be realized, actors may not be
1641 * unrealized if they are mapped. You must hide the actor or one of
1642 * its parents before attempting to unrealize.
1644 * This function is separate from clutter_actor_unrealize() because it
1645 * does not automatically hide the actor.
1646 * Actors need not be hidden to be unrealized, they just need to
1647 * be unmapped. In fact we don't want to mess up the application's
1648 * setting of the "visible" flag, so hiding is very undesirable.
1650 * clutter_actor_unrealize() does a clutter_actor_hide() just for
1651 * backward compatibility.
1654 clutter_actor_unrealize_not_hiding (ClutterActor *self)
1656 _clutter_actor_traverse (self,
1657 CLUTTER_ACTOR_TRAVERSE_DEPTH_FIRST,
1658 unrealize_actor_before_children_cb,
1659 unrealize_actor_after_children_cb,
1664 * _clutter_actor_rerealize:
1665 * @self: A #ClutterActor
1666 * @callback: Function to call while unrealized
1667 * @data: data for callback
1669 * If an actor is already unrealized, this just calls the callback.
1671 * If it is realized, it unrealizes temporarily, calls the callback,
1672 * and then re-realizes the actor.
1674 * As a side effect, leaves all children of the actor unrealized if
1675 * the actor was realized but not showing. This is because when we
1676 * unrealize the actor temporarily we must unrealize its children
1677 * (e.g. children of a stage can't be realized if stage window is
1678 * gone). And we aren't clever enough to save the realization state of
1679 * all children. In most cases this should not matter, because
1680 * the children will automatically realize when they next become mapped.
1683 _clutter_actor_rerealize (ClutterActor *self,
1684 ClutterCallback callback,
1687 gboolean was_mapped;
1688 gboolean was_showing;
1689 gboolean was_realized;
1691 g_return_if_fail (CLUTTER_IS_ACTOR (self));
1693 #ifdef CLUTTER_ENABLE_DEBUG
1694 clutter_actor_verify_map_state (self);
1697 was_realized = CLUTTER_ACTOR_IS_REALIZED (self);
1698 was_mapped = CLUTTER_ACTOR_IS_MAPPED (self);
1699 was_showing = CLUTTER_ACTOR_IS_VISIBLE (self);
1701 /* Must be unmapped to unrealize. Note we only have to hide this
1702 * actor if it was mapped (if all parents were showing). If actor
1703 * is merely visible (but not mapped), then that's fine, we can
1707 clutter_actor_hide (self);
1709 g_assert (!CLUTTER_ACTOR_IS_MAPPED (self));
1711 /* unrealize self and all children */
1712 clutter_actor_unrealize_not_hiding (self);
1714 if (callback != NULL)
1716 (* callback) (self, data);
1720 clutter_actor_show (self); /* will realize only if mapping implies it */
1721 else if (was_realized)
1722 clutter_actor_realize (self); /* realize self and all parents */
1726 clutter_actor_real_pick (ClutterActor *self,
1727 const ClutterColor *color)
1729 /* the default implementation is just to paint a rectangle
1730 * with the same size of the actor using the passed color
1732 if (clutter_actor_should_pick_paint (self))
1734 ClutterActorBox box = { 0, };
1735 float width, height;
1737 clutter_actor_get_allocation_box (self, &box);
1739 width = box.x2 - box.x1;
1740 height = box.y2 - box.y1;
1742 cogl_set_source_color4ub (color->red,
1747 cogl_rectangle (0, 0, width, height);
1750 /* XXX - this thoroughly sucks, but we need to maintain compatibility
1751 * with existing container classes that override the pick() virtual
1752 * and chain up to the default implementation - otherwise we'll end up
1753 * painting our children twice.
1755 * this has to go away for 2.0; hopefully along the pick() itself.
1757 if (CLUTTER_ACTOR_GET_CLASS (self)->pick == clutter_actor_real_pick)
1761 for (iter = self->priv->first_child;
1763 iter = iter->priv->next_sibling)
1764 clutter_actor_paint (iter);
1769 * clutter_actor_should_pick_paint:
1770 * @self: A #ClutterActor
1772 * Should be called inside the implementation of the
1773 * #ClutterActor::pick virtual function in order to check whether
1774 * the actor should paint itself in pick mode or not.
1776 * This function should never be called directly by applications.
1778 * Return value: %TRUE if the actor should paint its silhouette,
1782 clutter_actor_should_pick_paint (ClutterActor *self)
1784 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
1786 if (CLUTTER_ACTOR_IS_MAPPED (self) &&
1787 (_clutter_context_get_pick_mode () == CLUTTER_PICK_ALL ||
1788 CLUTTER_ACTOR_IS_REACTIVE (self)))
1795 clutter_actor_real_get_preferred_width (ClutterActor *self,
1797 gfloat *min_width_p,
1798 gfloat *natural_width_p)
1800 ClutterActorPrivate *priv = self->priv;
1802 if (priv->n_children != 0 &&
1803 priv->layout_manager != NULL)
1805 ClutterContainer *container = CLUTTER_CONTAINER (self);
1807 CLUTTER_NOTE (LAYOUT, "Querying the layout manager '%s'[%p] "
1808 "for the preferred width",
1809 G_OBJECT_TYPE_NAME (priv->layout_manager),
1810 priv->layout_manager);
1812 clutter_layout_manager_get_preferred_width (priv->layout_manager,
1821 /* Default implementation is always 0x0, usually an actor
1822 * using this default is relying on someone to set the
1825 CLUTTER_NOTE (LAYOUT, "Default preferred width: 0, 0");
1830 if (natural_width_p)
1831 *natural_width_p = 0;
1835 clutter_actor_real_get_preferred_height (ClutterActor *self,
1837 gfloat *min_height_p,
1838 gfloat *natural_height_p)
1840 ClutterActorPrivate *priv = self->priv;
1842 if (priv->n_children != 0 &&
1843 priv->layout_manager != NULL)
1845 ClutterContainer *container = CLUTTER_CONTAINER (self);
1847 CLUTTER_NOTE (LAYOUT, "Querying the layout manager '%s'[%p] "
1848 "for the preferred height",
1849 G_OBJECT_TYPE_NAME (priv->layout_manager),
1850 priv->layout_manager);
1852 clutter_layout_manager_get_preferred_height (priv->layout_manager,
1860 /* Default implementation is always 0x0, usually an actor
1861 * using this default is relying on someone to set the
1864 CLUTTER_NOTE (LAYOUT, "Default preferred height: 0, 0");
1869 if (natural_height_p)
1870 *natural_height_p = 0;
1874 clutter_actor_store_old_geometry (ClutterActor *self,
1875 ClutterActorBox *box)
1877 *box = self->priv->allocation;
1881 clutter_actor_notify_if_geometry_changed (ClutterActor *self,
1882 const ClutterActorBox *old)
1884 ClutterActorPrivate *priv = self->priv;
1885 GObject *obj = G_OBJECT (self);
1887 g_object_freeze_notify (obj);
1889 /* to avoid excessive requisition or allocation cycles we
1890 * use the cached values.
1892 * - if we don't have an allocation we assume that we need
1894 * - if we don't have a width or a height request we notify
1896 * - if we have a valid allocation then we check the old
1897 * bounding box with the current allocation and we notify
1900 if (priv->needs_allocation)
1902 g_object_notify_by_pspec (obj, obj_props[PROP_X]);
1903 g_object_notify_by_pspec (obj, obj_props[PROP_Y]);
1904 g_object_notify_by_pspec (obj, obj_props[PROP_WIDTH]);
1905 g_object_notify_by_pspec (obj, obj_props[PROP_HEIGHT]);
1907 else if (priv->needs_width_request || priv->needs_height_request)
1909 g_object_notify_by_pspec (obj, obj_props[PROP_WIDTH]);
1910 g_object_notify_by_pspec (obj, obj_props[PROP_HEIGHT]);
1915 gfloat widthu, heightu;
1917 xu = priv->allocation.x1;
1918 yu = priv->allocation.y1;
1919 widthu = priv->allocation.x2 - priv->allocation.x1;
1920 heightu = priv->allocation.y2 - priv->allocation.y1;
1923 g_object_notify_by_pspec (obj, obj_props[PROP_X]);
1926 g_object_notify_by_pspec (obj, obj_props[PROP_Y]);
1928 if (widthu != (old->x2 - old->x1))
1929 g_object_notify_by_pspec (obj, obj_props[PROP_WIDTH]);
1931 if (heightu != (old->y2 - old->y1))
1932 g_object_notify_by_pspec (obj, obj_props[PROP_HEIGHT]);
1935 g_object_thaw_notify (obj);
1939 * clutter_actor_set_allocation_internal:
1940 * @self: a #ClutterActor
1941 * @box: a #ClutterActorBox
1942 * @flags: allocation flags
1944 * Stores the allocation of @self.
1946 * This function only performs basic storage and property notification.
1948 * This function should be called by clutter_actor_set_allocation()
1949 * and by the default implementation of #ClutterActorClass.allocate().
1951 * Return value: %TRUE if the allocation of the #ClutterActor has been
1952 * changed, and %FALSE otherwise
1954 static inline gboolean
1955 clutter_actor_set_allocation_internal (ClutterActor *self,
1956 const ClutterActorBox *box,
1957 ClutterAllocationFlags flags)
1959 ClutterActorPrivate *priv = self->priv;
1961 gboolean x1_changed, y1_changed, x2_changed, y2_changed;
1962 gboolean flags_changed;
1964 ClutterActorBox old_alloc = { 0, };
1966 obj = G_OBJECT (self);
1968 g_object_freeze_notify (obj);
1970 clutter_actor_store_old_geometry (self, &old_alloc);
1972 x1_changed = priv->allocation.x1 != box->x1;
1973 y1_changed = priv->allocation.y1 != box->y1;
1974 x2_changed = priv->allocation.x2 != box->x2;
1975 y2_changed = priv->allocation.y2 != box->y2;
1977 flags_changed = priv->allocation_flags != flags;
1979 priv->allocation = *box;
1980 priv->allocation_flags = flags;
1982 /* allocation is authoritative */
1983 priv->needs_width_request = FALSE;
1984 priv->needs_height_request = FALSE;
1985 priv->needs_allocation = FALSE;
1987 if (x1_changed || y1_changed || x2_changed || y2_changed || flags_changed)
1989 CLUTTER_NOTE (LAYOUT, "Allocation for '%s' changed",
1990 _clutter_actor_get_debug_name (self));
1992 priv->transform_valid = FALSE;
1994 g_object_notify_by_pspec (obj, obj_props[PROP_ALLOCATION]);
2001 clutter_actor_notify_if_geometry_changed (self, &old_alloc);
2003 g_object_thaw_notify (obj);
2008 static void clutter_actor_real_allocate (ClutterActor *self,
2009 const ClutterActorBox *box,
2010 ClutterAllocationFlags flags);
2013 clutter_actor_maybe_layout_children (ClutterActor *self,
2014 const ClutterActorBox *allocation,
2015 ClutterAllocationFlags flags)
2017 ClutterActorPrivate *priv = self->priv;
2019 /* this is going to be a bit hard to follow, so let's put an explanation
2022 * we want ClutterActor to have a default layout manager if the actor was
2023 * created using "g_object_new (CLUTTER_TYPE_ACTOR, NULL)".
2025 * we also want any subclass of ClutterActor that does not override the
2026 * ::allocate() virtual function to delegate to a layout manager.
2028 * finally, we want to allow people subclassing ClutterActor and overriding
2029 * the ::allocate() vfunc to let Clutter delegate to the layout manager.
2031 * on the other hand, we want existing actor subclasses overriding the
2032 * ::allocate() virtual function and chaining up to the parent's
2033 * implementation to continue working without allocating their children
2034 * twice, or without entering an allocation loop.
2036 * for the first two points, we check if the class of the actor is
2037 * overridding the ::allocate() virtual function; if it isn't, then we
2038 * follow through with checking whether we have children and a layout
2039 * manager, and eventually calling clutter_layout_manager_allocate().
2041 * for the third point, we check the CLUTTER_DELEGATE_LAYOUT flag in the
2042 * allocation flags that we got passed, and if it is present, we continue
2043 * with the check above.
2045 * if neither of these two checks yields a positive result, we just
2046 * assume that the ::allocate() virtual function that resulted in this
2047 * function being called will also allocate the children of the actor.
2050 if (CLUTTER_ACTOR_GET_CLASS (self)->allocate == clutter_actor_real_allocate)
2053 if ((flags & CLUTTER_DELEGATE_LAYOUT) != 0)
2059 if (priv->n_children != 0 &&
2060 priv->layout_manager != NULL)
2062 ClutterContainer *container = CLUTTER_CONTAINER (self);
2063 ClutterAllocationFlags children_flags;
2064 ClutterActorBox children_box;
2066 /* normalize the box passed to the layout manager */
2067 children_box.x1 = children_box.y1 = 0.f;
2068 children_box.x2 = (allocation->x2 - allocation->x1);
2069 children_box.y2 = (allocation->y2 - allocation->y1);
2071 /* remove the DELEGATE_LAYOUT flag; this won't be passed to
2072 * the actor's children, since it refers only to the current
2073 * actor's allocation.
2075 children_flags = flags;
2076 children_flags &= ~CLUTTER_DELEGATE_LAYOUT;
2078 CLUTTER_NOTE (LAYOUT,
2079 "Allocating %d children of %s "
2080 "at { %.2f, %.2f - %.2f x %.2f } "
2083 _clutter_actor_get_debug_name (self),
2086 (allocation->x2 - allocation->x1),
2087 (allocation->y2 - allocation->y1),
2088 G_OBJECT_TYPE_NAME (priv->layout_manager));
2090 clutter_layout_manager_allocate (priv->layout_manager,
2098 clutter_actor_real_allocate (ClutterActor *self,
2099 const ClutterActorBox *box,
2100 ClutterAllocationFlags flags)
2102 ClutterActorPrivate *priv = self->priv;
2105 g_object_freeze_notify (G_OBJECT (self));
2107 changed = clutter_actor_set_allocation_internal (self, box, flags);
2109 /* we allocate our children before we notify changes in our geometry,
2110 * so that people connecting to properties will be able to get valid
2111 * data out of the sub-tree of the scene graph that has this actor at
2114 clutter_actor_maybe_layout_children (self, box, flags);
2118 ClutterActorBox signal_box = priv->allocation;
2119 ClutterAllocationFlags signal_flags = priv->allocation_flags;
2121 g_signal_emit (self, actor_signals[ALLOCATION_CHANGED], 0,
2126 g_object_thaw_notify (G_OBJECT (self));
2130 _clutter_actor_signal_queue_redraw (ClutterActor *self,
2131 ClutterActor *origin)
2133 /* no point in queuing a redraw on a destroyed actor */
2134 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
2137 /* NB: We can't bail out early here if the actor is hidden in case
2138 * the actor bas been cloned. In this case the clone will need to
2139 * receive the signal so it can queue its own redraw.
2142 /* calls klass->queue_redraw in default handler */
2143 g_signal_emit (self, actor_signals[QUEUE_REDRAW], 0, origin);
2147 clutter_actor_real_queue_redraw (ClutterActor *self,
2148 ClutterActor *origin)
2150 ClutterActor *parent;
2152 CLUTTER_NOTE (PAINT, "Redraw queued on '%s' (from: '%s')",
2153 _clutter_actor_get_debug_name (self),
2154 origin != NULL ? _clutter_actor_get_debug_name (origin)
2157 /* no point in queuing a redraw on a destroyed actor */
2158 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
2161 /* If the queue redraw is coming from a child then the actor has
2162 become dirty and any queued effect is no longer valid */
2165 self->priv->is_dirty = TRUE;
2166 self->priv->effect_to_redraw = NULL;
2169 /* If the actor isn't visible, we still had to emit the signal
2170 * to allow for a ClutterClone, but the appearance of the parent
2171 * won't change so we don't have to propagate up the hierarchy.
2173 if (!CLUTTER_ACTOR_IS_VISIBLE (self))
2176 /* Although we could determine here that a full stage redraw
2177 * has already been queued and immediately bail out, we actually
2178 * guarantee that we will propagate a queue-redraw signal to our
2179 * parent at least once so that it's possible to implement a
2180 * container that tracks which of its children have queued a
2183 if (self->priv->propagated_one_redraw)
2185 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
2186 if (stage != NULL &&
2187 _clutter_stage_has_full_redraw_queued (CLUTTER_STAGE (stage)))
2191 self->priv->propagated_one_redraw = TRUE;
2193 /* notify parents, if they are all visible eventually we'll
2194 * queue redraw on the stage, which queues the redraw idle.
2196 parent = clutter_actor_get_parent (self);
2199 /* this will go up recursively */
2200 _clutter_actor_signal_queue_redraw (parent, origin);
2205 clutter_actor_real_queue_relayout (ClutterActor *self)
2207 ClutterActorPrivate *priv = self->priv;
2209 /* no point in queueing a redraw on a destroyed actor */
2210 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
2213 priv->needs_width_request = TRUE;
2214 priv->needs_height_request = TRUE;
2215 priv->needs_allocation = TRUE;
2217 /* reset the cached size requests */
2218 memset (priv->width_requests, 0,
2219 N_CACHED_SIZE_REQUESTS * sizeof (SizeRequest));
2220 memset (priv->height_requests, 0,
2221 N_CACHED_SIZE_REQUESTS * sizeof (SizeRequest));
2223 /* We need to go all the way up the hierarchy */
2224 if (priv->parent != NULL)
2225 _clutter_actor_queue_only_relayout (priv->parent);
2229 * clutter_actor_apply_relative_transform_to_point:
2230 * @self: A #ClutterActor
2231 * @ancestor: (allow-none): A #ClutterActor ancestor, or %NULL to use the
2232 * default #ClutterStage
2233 * @point: A point as #ClutterVertex
2234 * @vertex: (out caller-allocates): The translated #ClutterVertex
2236 * Transforms @point in coordinates relative to the actor into
2237 * ancestor-relative coordinates using the relevant transform
2238 * stack (i.e. scale, rotation, etc).
2240 * If @ancestor is %NULL the ancestor will be the #ClutterStage. In
2241 * this case, the coordinates returned will be the coordinates on
2242 * the stage before the projection is applied. This is different from
2243 * the behaviour of clutter_actor_apply_transform_to_point().
2248 clutter_actor_apply_relative_transform_to_point (ClutterActor *self,
2249 ClutterActor *ancestor,
2250 const ClutterVertex *point,
2251 ClutterVertex *vertex)
2256 g_return_if_fail (CLUTTER_IS_ACTOR (self));
2257 g_return_if_fail (ancestor == NULL || CLUTTER_IS_ACTOR (ancestor));
2258 g_return_if_fail (point != NULL);
2259 g_return_if_fail (vertex != NULL);
2264 if (ancestor == NULL)
2265 ancestor = _clutter_actor_get_stage_internal (self);
2267 if (ancestor == NULL)
2273 _clutter_actor_get_relative_transformation_matrix (self, ancestor, &matrix);
2274 cogl_matrix_transform_point (&matrix, &vertex->x, &vertex->y, &vertex->z, &w);
2278 _clutter_actor_fully_transform_vertices (ClutterActor *self,
2279 const ClutterVertex *vertices_in,
2280 ClutterVertex *vertices_out,
2283 ClutterActor *stage;
2284 CoglMatrix modelview;
2285 CoglMatrix projection;
2288 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
2290 stage = _clutter_actor_get_stage_internal (self);
2292 /* We really can't do anything meaningful in this case so don't try
2293 * to do any transform */
2297 /* Note: we pass NULL as the ancestor because we don't just want the modelview
2298 * that gets us to stage coordinates, we want to go all the way to eye
2300 _clutter_actor_apply_relative_transformation_matrix (self, NULL, &modelview);
2302 /* Fetch the projection and viewport */
2303 _clutter_stage_get_projection_matrix (CLUTTER_STAGE (stage), &projection);
2304 _clutter_stage_get_viewport (CLUTTER_STAGE (stage),
2310 _clutter_util_fully_transform_vertices (&modelview,
2321 * clutter_actor_apply_transform_to_point:
2322 * @self: A #ClutterActor
2323 * @point: A point as #ClutterVertex
2324 * @vertex: (out caller-allocates): The translated #ClutterVertex
2326 * Transforms @point in coordinates relative to the actor
2327 * into screen-relative coordinates with the current actor
2328 * transformation (i.e. scale, rotation, etc)
2333 clutter_actor_apply_transform_to_point (ClutterActor *self,
2334 const ClutterVertex *point,
2335 ClutterVertex *vertex)
2337 g_return_if_fail (point != NULL);
2338 g_return_if_fail (vertex != NULL);
2339 _clutter_actor_fully_transform_vertices (self, point, vertex, 1);
2343 * _clutter_actor_get_relative_transformation_matrix:
2344 * @self: The actor whose coordinate space you want to transform from.
2345 * @ancestor: The ancestor actor whose coordinate space you want to transform too
2346 * or %NULL if you want to transform all the way to eye coordinates.
2347 * @matrix: A #CoglMatrix to store the transformation
2349 * This gets a transformation @matrix that will transform coordinates from the
2350 * coordinate space of @self into the coordinate space of @ancestor.
2352 * For example if you need a matrix that can transform the local actor
2353 * coordinates of @self into stage coordinates you would pass the actor's stage
2354 * pointer as the @ancestor.
2356 * If you pass %NULL then the transformation will take you all the way through
2357 * to eye coordinates. This can be useful if you want to extract the entire
2358 * modelview transform that Clutter applies before applying the projection
2359 * transformation. If you want to explicitly set a modelview on a CoglFramebuffer
2360 * using cogl_set_modelview_matrix() for example then you would want a matrix
2361 * that transforms into eye coordinates.
2363 * <note><para>This function explicitly initializes the given @matrix. If you just
2364 * want clutter to multiply a relative transformation with an existing matrix
2365 * you can use clutter_actor_apply_relative_transformation_matrix()
2366 * instead.</para></note>
2369 /* XXX: We should consider caching the stage relative modelview along with
2370 * the actor itself */
2372 _clutter_actor_get_relative_transformation_matrix (ClutterActor *self,
2373 ClutterActor *ancestor,
2376 cogl_matrix_init_identity (matrix);
2378 _clutter_actor_apply_relative_transformation_matrix (self, ancestor, matrix);
2381 /* Project the given @box into stage window coordinates, writing the
2382 * transformed vertices to @verts[]. */
2384 _clutter_actor_transform_and_project_box (ClutterActor *self,
2385 const ClutterActorBox *box,
2386 ClutterVertex verts[])
2388 ClutterVertex box_vertices[4];
2390 box_vertices[0].x = box->x1;
2391 box_vertices[0].y = box->y1;
2392 box_vertices[0].z = 0;
2393 box_vertices[1].x = box->x2;
2394 box_vertices[1].y = box->y1;
2395 box_vertices[1].z = 0;
2396 box_vertices[2].x = box->x1;
2397 box_vertices[2].y = box->y2;
2398 box_vertices[2].z = 0;
2399 box_vertices[3].x = box->x2;
2400 box_vertices[3].y = box->y2;
2401 box_vertices[3].z = 0;
2404 _clutter_actor_fully_transform_vertices (self, box_vertices, verts, 4);
2408 * clutter_actor_get_allocation_vertices:
2409 * @self: A #ClutterActor
2410 * @ancestor: (allow-none): A #ClutterActor to calculate the vertices
2411 * against, or %NULL to use the #ClutterStage
2412 * @verts: (out) (array fixed-size=4) (element-type Clutter.Vertex): return
2413 * location for an array of 4 #ClutterVertex in which to store the result
2415 * Calculates the transformed coordinates of the four corners of the
2416 * actor in the plane of @ancestor. The returned vertices relate to
2417 * the #ClutterActorBox coordinates as follows:
2419 * <listitem><para>@verts[0] contains (x1, y1)</para></listitem>
2420 * <listitem><para>@verts[1] contains (x2, y1)</para></listitem>
2421 * <listitem><para>@verts[2] contains (x1, y2)</para></listitem>
2422 * <listitem><para>@verts[3] contains (x2, y2)</para></listitem>
2425 * If @ancestor is %NULL the ancestor will be the #ClutterStage. In
2426 * this case, the coordinates returned will be the coordinates on
2427 * the stage before the projection is applied. This is different from
2428 * the behaviour of clutter_actor_get_abs_allocation_vertices().
2433 clutter_actor_get_allocation_vertices (ClutterActor *self,
2434 ClutterActor *ancestor,
2435 ClutterVertex verts[])
2437 ClutterActorPrivate *priv;
2438 ClutterActorBox box;
2439 ClutterVertex vertices[4];
2440 CoglMatrix modelview;
2442 g_return_if_fail (CLUTTER_IS_ACTOR (self));
2443 g_return_if_fail (ancestor == NULL || CLUTTER_IS_ACTOR (ancestor));
2445 if (ancestor == NULL)
2446 ancestor = _clutter_actor_get_stage_internal (self);
2448 /* Fallback to a NOP transform if the actor isn't parented under a
2450 if (ancestor == NULL)
2455 /* if the actor needs to be allocated we force a relayout, so that
2456 * we will have valid values to use in the transformations */
2457 if (priv->needs_allocation)
2459 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
2461 _clutter_stage_maybe_relayout (stage);
2464 box.x1 = box.y1 = 0;
2465 /* The result isn't really meaningful in this case but at
2466 * least try to do something *vaguely* reasonable... */
2467 clutter_actor_get_size (self, &box.x2, &box.y2);
2471 clutter_actor_get_allocation_box (self, &box);
2473 vertices[0].x = box.x1;
2474 vertices[0].y = box.y1;
2476 vertices[1].x = box.x2;
2477 vertices[1].y = box.y1;
2479 vertices[2].x = box.x1;
2480 vertices[2].y = box.y2;
2482 vertices[3].x = box.x2;
2483 vertices[3].y = box.y2;
2486 _clutter_actor_get_relative_transformation_matrix (self, ancestor,
2489 cogl_matrix_transform_points (&modelview,
2491 sizeof (ClutterVertex),
2493 sizeof (ClutterVertex),
2499 * clutter_actor_get_abs_allocation_vertices:
2500 * @self: A #ClutterActor
2501 * @verts: (out) (array fixed-size=4): Pointer to a location of an array
2502 * of 4 #ClutterVertex where to store the result.
2504 * Calculates the transformed screen coordinates of the four corners of
2505 * the actor; the returned vertices relate to the #ClutterActorBox
2506 * coordinates as follows:
2508 * <listitem><para>v[0] contains (x1, y1)</para></listitem>
2509 * <listitem><para>v[1] contains (x2, y1)</para></listitem>
2510 * <listitem><para>v[2] contains (x1, y2)</para></listitem>
2511 * <listitem><para>v[3] contains (x2, y2)</para></listitem>
2517 clutter_actor_get_abs_allocation_vertices (ClutterActor *self,
2518 ClutterVertex verts[])
2520 ClutterActorPrivate *priv;
2521 ClutterActorBox actor_space_allocation;
2523 g_return_if_fail (CLUTTER_IS_ACTOR (self));
2527 /* if the actor needs to be allocated we force a relayout, so that
2528 * the actor allocation box will be valid for
2529 * _clutter_actor_transform_and_project_box()
2531 if (priv->needs_allocation)
2533 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
2534 /* There's nothing meaningful we can do now */
2538 _clutter_stage_maybe_relayout (stage);
2541 /* NB: _clutter_actor_transform_and_project_box expects a box in the actor's
2542 * own coordinate space... */
2543 actor_space_allocation.x1 = 0;
2544 actor_space_allocation.y1 = 0;
2545 actor_space_allocation.x2 = priv->allocation.x2 - priv->allocation.x1;
2546 actor_space_allocation.y2 = priv->allocation.y2 - priv->allocation.y1;
2547 _clutter_actor_transform_and_project_box (self,
2548 &actor_space_allocation,
2553 clutter_actor_real_apply_transform (ClutterActor *self,
2556 ClutterActorPrivate *priv = self->priv;
2558 if (!priv->transform_valid)
2560 CoglMatrix *transform = &priv->transform;
2561 const ClutterTransformInfo *info;
2563 info = _clutter_actor_get_transform_info_or_defaults (self);
2565 cogl_matrix_init_identity (transform);
2567 cogl_matrix_translate (transform,
2568 priv->allocation.x1,
2569 priv->allocation.y1,
2573 cogl_matrix_translate (transform, 0, 0, priv->z);
2576 * because the rotation involves translations, we must scale
2577 * before applying the rotations (if we apply the scale after
2578 * the rotations, the translations included in the rotation are
2579 * not scaled and so the entire object will move on the screen
2580 * as a result of rotating it).
2582 if (info->scale_x != 1.0 || info->scale_y != 1.0)
2584 TRANSFORM_ABOUT_ANCHOR_COORD (self, transform,
2585 &info->scale_center,
2586 cogl_matrix_scale (transform,
2593 TRANSFORM_ABOUT_ANCHOR_COORD (self, transform,
2595 cogl_matrix_rotate (transform,
2600 TRANSFORM_ABOUT_ANCHOR_COORD (self, transform,
2602 cogl_matrix_rotate (transform,
2607 TRANSFORM_ABOUT_ANCHOR_COORD (self, transform,
2609 cogl_matrix_rotate (transform,
2613 if (!clutter_anchor_coord_is_zero (&info->anchor))
2617 clutter_anchor_coord_get_units (self, &info->anchor, &x, &y, &z);
2618 cogl_matrix_translate (transform, -x, -y, -z);
2621 priv->transform_valid = TRUE;
2624 cogl_matrix_multiply (matrix, matrix, &priv->transform);
2627 /* Applies the transforms associated with this actor to the given
2630 _clutter_actor_apply_modelview_transform (ClutterActor *self,
2633 CLUTTER_ACTOR_GET_CLASS (self)->apply_transform (self, matrix);
2637 * clutter_actor_apply_relative_transformation_matrix:
2638 * @self: The actor whose coordinate space you want to transform from.
2639 * @ancestor: The ancestor actor whose coordinate space you want to transform too
2640 * or %NULL if you want to transform all the way to eye coordinates.
2641 * @matrix: A #CoglMatrix to apply the transformation too.
2643 * This multiplies a transform with @matrix that will transform coordinates
2644 * from the coordinate space of @self into the coordinate space of @ancestor.
2646 * For example if you need a matrix that can transform the local actor
2647 * coordinates of @self into stage coordinates you would pass the actor's stage
2648 * pointer as the @ancestor.
2650 * If you pass %NULL then the transformation will take you all the way through
2651 * to eye coordinates. This can be useful if you want to extract the entire
2652 * modelview transform that Clutter applies before applying the projection
2653 * transformation. If you want to explicitly set a modelview on a CoglFramebuffer
2654 * using cogl_set_modelview_matrix() for example then you would want a matrix
2655 * that transforms into eye coordinates.
2657 * <note>This function doesn't initialize the given @matrix, it simply
2658 * multiplies the requested transformation matrix with the existing contents of
2659 * @matrix. You can use cogl_matrix_init_identity() to initialize the @matrix
2660 * before calling this function, or you can use
2661 * clutter_actor_get_relative_transformation_matrix() instead.</note>
2664 _clutter_actor_apply_relative_transformation_matrix (ClutterActor *self,
2665 ClutterActor *ancestor,
2668 ClutterActor *parent;
2670 /* Note we terminate before ever calling stage->apply_transform()
2671 * since that would conceptually be relative to the underlying
2672 * window OpenGL coordinates so we'd need a special @ancestor
2673 * value to represent the fake parent of the stage. */
2674 if (self == ancestor)
2677 parent = clutter_actor_get_parent (self);
2680 _clutter_actor_apply_relative_transformation_matrix (parent, ancestor,
2683 _clutter_actor_apply_modelview_transform (self, matrix);
2687 _clutter_actor_draw_paint_volume_full (ClutterActor *self,
2688 ClutterPaintVolume *pv,
2690 const CoglColor *color)
2692 static CoglPipeline *outline = NULL;
2693 CoglPrimitive *prim;
2694 ClutterVertex line_ends[12 * 2];
2697 clutter_backend_get_cogl_context (clutter_get_default_backend ());
2698 /* XXX: at some point we'll query this from the stage but we can't
2699 * do that until the osx backend uses Cogl natively. */
2700 CoglFramebuffer *fb = cogl_get_draw_framebuffer ();
2702 if (outline == NULL)
2703 outline = cogl_pipeline_new (ctx);
2705 _clutter_paint_volume_complete (pv);
2707 n_vertices = pv->is_2d ? 4 * 2 : 12 * 2;
2710 line_ends[0] = pv->vertices[0]; line_ends[1] = pv->vertices[1];
2711 line_ends[2] = pv->vertices[1]; line_ends[3] = pv->vertices[2];
2712 line_ends[4] = pv->vertices[2]; line_ends[5] = pv->vertices[3];
2713 line_ends[6] = pv->vertices[3]; line_ends[7] = pv->vertices[0];
2718 line_ends[8] = pv->vertices[4]; line_ends[9] = pv->vertices[5];
2719 line_ends[10] = pv->vertices[5]; line_ends[11] = pv->vertices[6];
2720 line_ends[12] = pv->vertices[6]; line_ends[13] = pv->vertices[7];
2721 line_ends[14] = pv->vertices[7]; line_ends[15] = pv->vertices[4];
2723 /* Lines connecting front face to back face */
2724 line_ends[16] = pv->vertices[0]; line_ends[17] = pv->vertices[4];
2725 line_ends[18] = pv->vertices[1]; line_ends[19] = pv->vertices[5];
2726 line_ends[20] = pv->vertices[2]; line_ends[21] = pv->vertices[6];
2727 line_ends[22] = pv->vertices[3]; line_ends[23] = pv->vertices[7];
2730 prim = cogl_primitive_new_p3 (ctx, COGL_VERTICES_MODE_LINES,
2732 (CoglVertexP3 *)line_ends);
2734 cogl_pipeline_set_color (outline, color);
2735 cogl_framebuffer_draw_primitive (fb, outline, prim);
2736 cogl_object_unref (prim);
2740 PangoLayout *layout;
2741 layout = pango_layout_new (clutter_actor_get_pango_context (self));
2742 pango_layout_set_text (layout, label, -1);
2743 cogl_pango_render_layout (layout,
2748 g_object_unref (layout);
2753 _clutter_actor_draw_paint_volume (ClutterActor *self)
2755 ClutterPaintVolume *pv;
2758 pv = _clutter_actor_get_paint_volume_mutable (self);
2761 gfloat width, height;
2762 ClutterPaintVolume fake_pv;
2764 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
2765 _clutter_paint_volume_init_static (&fake_pv, stage);
2767 clutter_actor_get_size (self, &width, &height);
2768 clutter_paint_volume_set_width (&fake_pv, width);
2769 clutter_paint_volume_set_height (&fake_pv, height);
2771 cogl_color_init_from_4f (&color, 0, 0, 1, 1);
2772 _clutter_actor_draw_paint_volume_full (self, &fake_pv,
2773 _clutter_actor_get_debug_name (self),
2776 clutter_paint_volume_free (&fake_pv);
2780 cogl_color_init_from_4f (&color, 0, 1, 0, 1);
2781 _clutter_actor_draw_paint_volume_full (self, pv,
2782 _clutter_actor_get_debug_name (self),
2788 _clutter_actor_paint_cull_result (ClutterActor *self,
2790 ClutterCullResult result)
2792 ClutterPaintVolume *pv;
2797 if (result == CLUTTER_CULL_RESULT_IN)
2798 cogl_color_init_from_4f (&color, 0, 1, 0, 1);
2799 else if (result == CLUTTER_CULL_RESULT_OUT)
2800 cogl_color_init_from_4f (&color, 0, 0, 1, 1);
2802 cogl_color_init_from_4f (&color, 0, 1, 1, 1);
2805 cogl_color_init_from_4f (&color, 1, 1, 1, 1);
2807 if (success && (pv = _clutter_actor_get_paint_volume_mutable (self)))
2808 _clutter_actor_draw_paint_volume_full (self, pv,
2809 _clutter_actor_get_debug_name (self),
2813 PangoLayout *layout;
2815 g_strdup_printf ("CULL FAILURE: %s", _clutter_actor_get_debug_name (self));
2816 cogl_color_init_from_4f (&color, 1, 1, 1, 1);
2817 cogl_set_source_color (&color);
2819 layout = pango_layout_new (clutter_actor_get_pango_context (self));
2820 pango_layout_set_text (layout, label, -1);
2821 cogl_pango_render_layout (layout,
2827 g_object_unref (layout);
2831 static int clone_paint_level = 0;
2834 _clutter_actor_push_clone_paint (void)
2836 clone_paint_level++;
2840 _clutter_actor_pop_clone_paint (void)
2842 clone_paint_level--;
2846 in_clone_paint (void)
2848 return clone_paint_level > 0;
2851 /* Returns TRUE if the actor can be ignored */
2852 /* FIXME: we should return a ClutterCullResult, and
2853 * clutter_actor_paint should understand that a CLUTTER_CULL_RESULT_IN
2854 * means there's no point in trying to cull descendants of the current
2857 cull_actor (ClutterActor *self, ClutterCullResult *result_out)
2859 ClutterActorPrivate *priv = self->priv;
2860 ClutterActor *stage;
2861 const ClutterPlane *stage_clip;
2863 if (!priv->last_paint_volume_valid)
2865 CLUTTER_NOTE (CLIPPING, "Bail from cull_actor without culling (%s): "
2866 "->last_paint_volume_valid == FALSE",
2867 _clutter_actor_get_debug_name (self));
2871 if (G_UNLIKELY (clutter_paint_debug_flags & CLUTTER_DEBUG_DISABLE_CULLING))
2874 stage = _clutter_actor_get_stage_internal (self);
2875 stage_clip = _clutter_stage_get_clip (CLUTTER_STAGE (stage));
2876 if (G_UNLIKELY (!stage_clip))
2878 CLUTTER_NOTE (CLIPPING, "Bail from cull_actor without culling (%s): "
2879 "No stage clip set",
2880 _clutter_actor_get_debug_name (self));
2884 if (cogl_get_draw_framebuffer () !=
2885 _clutter_stage_get_active_framebuffer (CLUTTER_STAGE (stage)))
2887 CLUTTER_NOTE (CLIPPING, "Bail from cull_actor without culling (%s): "
2888 "Current framebuffer doesn't correspond to stage",
2889 _clutter_actor_get_debug_name (self));
2894 _clutter_paint_volume_cull (&priv->last_paint_volume, stage_clip);
2899 _clutter_actor_update_last_paint_volume (ClutterActor *self)
2901 ClutterActorPrivate *priv = self->priv;
2902 const ClutterPaintVolume *pv;
2904 if (priv->last_paint_volume_valid)
2906 clutter_paint_volume_free (&priv->last_paint_volume);
2907 priv->last_paint_volume_valid = FALSE;
2910 pv = clutter_actor_get_paint_volume (self);
2913 CLUTTER_NOTE (CLIPPING, "Bail from update_last_paint_volume (%s): "
2914 "Actor failed to report a paint volume",
2915 _clutter_actor_get_debug_name (self));
2919 _clutter_paint_volume_copy_static (pv, &priv->last_paint_volume);
2921 _clutter_paint_volume_transform_relative (&priv->last_paint_volume,
2922 NULL); /* eye coordinates */
2924 priv->last_paint_volume_valid = TRUE;
2927 static inline gboolean
2928 actor_has_shader_data (ClutterActor *self)
2930 return g_object_get_qdata (G_OBJECT (self), quark_shader_data) != NULL;
2934 _clutter_actor_get_pick_id (ClutterActor *self)
2936 if (self->priv->pick_id < 0)
2939 return self->priv->pick_id;
2942 /* This is the same as clutter_actor_add_effect except that it doesn't
2943 queue a redraw and it doesn't notify on the effect property */
2945 _clutter_actor_add_effect_internal (ClutterActor *self,
2946 ClutterEffect *effect)
2948 ClutterActorPrivate *priv = self->priv;
2950 if (priv->effects == NULL)
2952 priv->effects = g_object_new (CLUTTER_TYPE_META_GROUP, NULL);
2953 priv->effects->actor = self;
2956 _clutter_meta_group_add_meta (priv->effects, CLUTTER_ACTOR_META (effect));
2959 /* This is the same as clutter_actor_remove_effect except that it doesn't
2960 queue a redraw and it doesn't notify on the effect property */
2962 _clutter_actor_remove_effect_internal (ClutterActor *self,
2963 ClutterEffect *effect)
2965 ClutterActorPrivate *priv = self->priv;
2967 if (priv->effects == NULL)
2970 _clutter_meta_group_remove_meta (priv->effects, CLUTTER_ACTOR_META (effect));
2974 needs_flatten_effect (ClutterActor *self)
2976 ClutterActorPrivate *priv = self->priv;
2978 if (G_UNLIKELY (clutter_paint_debug_flags &
2979 CLUTTER_DEBUG_DISABLE_OFFSCREEN_REDIRECT))
2982 if (priv->offscreen_redirect & CLUTTER_OFFSCREEN_REDIRECT_ALWAYS)
2984 else if (priv->offscreen_redirect & CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY)
2986 if (clutter_actor_get_paint_opacity (self) < 255 &&
2987 clutter_actor_has_overlaps (self))
2995 add_or_remove_flatten_effect (ClutterActor *self)
2997 ClutterActorPrivate *priv = self->priv;
2999 /* Add or remove the flatten effect depending on the
3000 offscreen-redirect property. */
3001 if (needs_flatten_effect (self))
3003 if (priv->flatten_effect == NULL)
3005 ClutterActorMeta *actor_meta;
3008 priv->flatten_effect = _clutter_flatten_effect_new ();
3009 /* Keep a reference to the effect so that we can queue
3011 g_object_ref_sink (priv->flatten_effect);
3013 /* Set the priority of the effect to high so that it will
3014 always be applied to the actor first. It uses an internal
3015 priority so that it won't be visible to applications */
3016 actor_meta = CLUTTER_ACTOR_META (priv->flatten_effect);
3017 priority = CLUTTER_ACTOR_META_PRIORITY_INTERNAL_HIGH;
3018 _clutter_actor_meta_set_priority (actor_meta, priority);
3020 /* This will add the effect without queueing a redraw */
3021 _clutter_actor_add_effect_internal (self, priv->flatten_effect);
3026 if (priv->flatten_effect != NULL)
3028 /* Destroy the effect so that it will lose its fbo cache of
3030 _clutter_actor_remove_effect_internal (self, priv->flatten_effect);
3031 g_object_unref (priv->flatten_effect);
3032 priv->flatten_effect = NULL;
3038 clutter_actor_real_paint (ClutterActor *actor)
3040 ClutterActorPrivate *priv = actor->priv;
3043 /* paint the background color, if set */
3044 if (priv->bg_color_set)
3046 float width, height;
3049 clutter_actor_box_get_size (&priv->allocation, &width, &height);
3051 real_alpha = clutter_actor_get_paint_opacity_internal (actor)
3052 * priv->bg_color.alpha
3055 cogl_set_source_color4ub (priv->bg_color.red,
3056 priv->bg_color.green,
3057 priv->bg_color.blue,
3060 cogl_rectangle (0, 0, width, height);
3063 for (iter = priv->first_child;
3065 iter = iter->priv->next_sibling)
3067 CLUTTER_NOTE (PAINT, "Painting %s, child of %s, at { %.2f, %.2f - %.2f x %.2f }",
3068 _clutter_actor_get_debug_name (iter),
3069 _clutter_actor_get_debug_name (actor),
3070 iter->priv->allocation.x1,
3071 iter->priv->allocation.y1,
3072 iter->priv->allocation.x2 - iter->priv->allocation.x1,
3073 iter->priv->allocation.y2 - iter->priv->allocation.y1);
3075 clutter_actor_paint (iter);
3080 * clutter_actor_paint:
3081 * @self: A #ClutterActor
3083 * Renders the actor to display.
3085 * This function should not be called directly by applications.
3086 * Call clutter_actor_queue_redraw() to queue paints, instead.
3088 * This function is context-aware, and will either cause a
3089 * regular paint or a pick paint.
3091 * This function will emit the #ClutterActor::paint signal or
3092 * the #ClutterActor::pick signal, depending on the context.
3094 * This function does not paint the actor if the actor is set to 0,
3095 * unless it is performing a pick paint.
3098 clutter_actor_paint (ClutterActor *self)
3100 ClutterActorPrivate *priv;
3101 ClutterPickMode pick_mode;
3102 gboolean clip_set = FALSE;
3103 gboolean shader_applied = FALSE;
3105 CLUTTER_STATIC_COUNTER (actor_paint_counter,
3106 "Actor real-paint counter",
3107 "Increments each time any actor is painted",
3108 0 /* no application private data */);
3109 CLUTTER_STATIC_COUNTER (actor_pick_counter,
3110 "Actor pick-paint counter",
3111 "Increments each time any actor is painted "
3113 0 /* no application private data */);
3115 g_return_if_fail (CLUTTER_IS_ACTOR (self));
3117 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
3122 pick_mode = _clutter_context_get_pick_mode ();
3124 if (pick_mode == CLUTTER_PICK_NONE)
3125 priv->propagated_one_redraw = FALSE;
3127 /* It's an important optimization that we consider painting of
3128 * actors with 0 opacity to be a NOP... */
3129 if (pick_mode == CLUTTER_PICK_NONE &&
3130 /* ignore top-levels, since they might be transparent */
3131 !CLUTTER_ACTOR_IS_TOPLEVEL (self) &&
3132 /* Use the override opacity if its been set */
3133 ((priv->opacity_override >= 0) ?
3134 priv->opacity_override : priv->opacity) == 0)
3137 /* if we aren't paintable (not in a toplevel with all
3138 * parents paintable) then do nothing.
3140 if (!CLUTTER_ACTOR_IS_MAPPED (self))
3143 /* mark that we are in the paint process */
3144 CLUTTER_SET_PRIVATE_FLAGS (self, CLUTTER_IN_PAINT);
3148 if (priv->enable_model_view_transform)
3152 /* XXX: It could be better to cache the modelview with the actor
3153 * instead of progressively building up the transformations on
3154 * the matrix stack every time we paint. */
3155 cogl_get_modelview_matrix (&matrix);
3156 _clutter_actor_apply_modelview_transform (self, &matrix);
3158 #ifdef CLUTTER_ENABLE_DEBUG
3159 /* Catch when out-of-band transforms have been made by actors not as part
3160 * of an apply_transform vfunc... */
3161 if (G_UNLIKELY (clutter_debug_flags & CLUTTER_DEBUG_OOB_TRANSFORMS))
3163 CoglMatrix expected_matrix;
3165 _clutter_actor_get_relative_transformation_matrix (self, NULL,
3168 if (!cogl_matrix_equal (&matrix, &expected_matrix))
3170 GString *buf = g_string_sized_new (1024);
3171 ClutterActor *parent;
3174 while (parent != NULL)
3176 g_string_append (buf, _clutter_actor_get_debug_name (parent));
3178 if (parent->priv->parent != NULL)
3179 g_string_append (buf, "->");
3181 parent = parent->priv->parent;
3184 g_warning ("Unexpected transform found when painting actor "
3185 "\"%s\". This will be caused by one of the actor's "
3186 "ancestors (%s) using the Cogl API directly to transform "
3187 "children instead of using ::apply_transform().",
3188 _clutter_actor_get_debug_name (self),
3191 g_string_free (buf, TRUE);
3194 #endif /* CLUTTER_ENABLE_DEBUG */
3196 cogl_set_modelview_matrix (&matrix);
3201 cogl_clip_push_rectangle (priv->clip.x,
3203 priv->clip.x + priv->clip.width,
3204 priv->clip.y + priv->clip.height);
3207 else if (priv->clip_to_allocation)
3209 gfloat width, height;
3211 width = priv->allocation.x2 - priv->allocation.x1;
3212 height = priv->allocation.y2 - priv->allocation.y1;
3214 cogl_clip_push_rectangle (0, 0, width, height);
3218 if (pick_mode == CLUTTER_PICK_NONE)
3220 CLUTTER_COUNTER_INC (_clutter_uprof_context, actor_paint_counter);
3222 /* We check whether we need to add the flatten effect before
3223 each paint so that we can avoid having a mechanism for
3224 applications to notify when the value of the
3225 has_overlaps virtual changes. */
3226 add_or_remove_flatten_effect (self);
3229 CLUTTER_COUNTER_INC (_clutter_uprof_context, actor_pick_counter);
3231 /* We save the current paint volume so that the next time the
3232 * actor queues a redraw we can constrain the redraw to just
3233 * cover the union of the new bounding box and the old.
3235 * We also fetch the current paint volume to perform culling so
3236 * we can avoid painting actors outside the current clip region.
3238 * If we are painting inside a clone, we should neither update
3239 * the paint volume or use it to cull painting, since the paint
3240 * box represents the location of the source actor on the
3243 * XXX: We are starting to do a lot of vertex transforms on
3244 * the CPU in a typical paint, so at some point we should
3245 * audit these and consider caching some things.
3247 * NB: We don't perform culling while picking at this point because
3248 * clutter-stage.c doesn't setup the clipping planes appropriately.
3250 * NB: We don't want to update the last-paint-volume during picking
3251 * because the last-paint-volume is used to determine the old screen
3252 * space location of an actor that has moved so we can know the
3253 * minimal region to redraw to clear an old view of the actor. If we
3254 * update this during picking then by the time we come around to
3255 * paint then the last-paint-volume would likely represent the new
3256 * actor position not the old.
3258 if (!in_clone_paint () && pick_mode == CLUTTER_PICK_NONE)
3261 /* annoyingly gcc warns if uninitialized even though
3262 * the initialization is redundant :-( */
3263 ClutterCullResult result = CLUTTER_CULL_RESULT_IN;
3265 if (G_LIKELY ((clutter_paint_debug_flags &
3266 (CLUTTER_DEBUG_DISABLE_CULLING |
3267 CLUTTER_DEBUG_DISABLE_CLIPPED_REDRAWS)) !=
3268 (CLUTTER_DEBUG_DISABLE_CULLING |
3269 CLUTTER_DEBUG_DISABLE_CLIPPED_REDRAWS)))
3270 _clutter_actor_update_last_paint_volume (self);
3272 success = cull_actor (self, &result);
3274 if (G_UNLIKELY (clutter_paint_debug_flags & CLUTTER_DEBUG_REDRAWS))
3275 _clutter_actor_paint_cull_result (self, success, result);
3276 else if (result == CLUTTER_CULL_RESULT_OUT && success)
3280 if (priv->effects == NULL)
3282 if (pick_mode == CLUTTER_PICK_NONE &&
3283 actor_has_shader_data (self))
3285 _clutter_actor_shader_pre_paint (self, FALSE);
3286 shader_applied = TRUE;
3289 priv->next_effect_to_paint = NULL;
3292 priv->next_effect_to_paint =
3293 _clutter_meta_group_peek_metas (priv->effects);
3295 clutter_actor_continue_paint (self);
3298 _clutter_actor_shader_post_paint (self);
3300 if (G_UNLIKELY (clutter_paint_debug_flags & CLUTTER_DEBUG_PAINT_VOLUMES &&
3301 pick_mode == CLUTTER_PICK_NONE))
3302 _clutter_actor_draw_paint_volume (self);
3305 /* If we make it here then the actor has run through a complete
3306 paint run including all the effects so it's no longer dirty */
3307 if (pick_mode == CLUTTER_PICK_NONE)
3308 priv->is_dirty = FALSE;
3315 /* paint sequence complete */
3316 CLUTTER_UNSET_PRIVATE_FLAGS (self, CLUTTER_IN_PAINT);
3320 * clutter_actor_continue_paint:
3321 * @self: A #ClutterActor
3323 * Run the next stage of the paint sequence. This function should only
3324 * be called within the implementation of the ‘run’ virtual of a
3325 * #ClutterEffect. It will cause the run method of the next effect to
3326 * be applied, or it will paint the actual actor if the current effect
3327 * is the last effect in the chain.
3332 clutter_actor_continue_paint (ClutterActor *self)
3334 ClutterActorPrivate *priv;
3336 g_return_if_fail (CLUTTER_IS_ACTOR (self));
3337 /* This should only be called from with in the ‘run’ implementation
3338 of a ClutterEffect */
3339 g_return_if_fail (CLUTTER_ACTOR_IN_PAINT (self));
3343 /* Skip any effects that are disabled */
3344 while (priv->next_effect_to_paint &&
3345 !clutter_actor_meta_get_enabled (priv->next_effect_to_paint->data))
3346 priv->next_effect_to_paint = priv->next_effect_to_paint->next;
3348 /* If this has come from the last effect then we'll just paint the
3350 if (priv->next_effect_to_paint == NULL)
3352 if (_clutter_context_get_pick_mode () == CLUTTER_PICK_NONE)
3354 g_signal_emit (self, actor_signals[PAINT], 0);
3358 ClutterColor col = { 0, };
3360 _clutter_id_to_color (_clutter_actor_get_pick_id (self), &col);
3362 /* Actor will then paint silhouette of itself in supplied
3363 * color. See clutter_stage_get_actor_at_pos() for where
3364 * picking is enabled.
3366 g_signal_emit (self, actor_signals[PICK], 0, &col);
3371 ClutterEffect *old_current_effect;
3372 ClutterEffectPaintFlags run_flags = 0;
3374 /* Cache the current effect so that we can put it back before
3376 old_current_effect = priv->current_effect;
3378 priv->current_effect = priv->next_effect_to_paint->data;
3379 priv->next_effect_to_paint = priv->next_effect_to_paint->next;
3381 if (_clutter_context_get_pick_mode () == CLUTTER_PICK_NONE)
3385 /* If there's an effect queued with this redraw then all
3386 effects up to that one will be considered dirty. It
3387 is expected the queued effect will paint the cached
3388 image and not call clutter_actor_continue_paint again
3389 (although it should work ok if it does) */
3390 if (priv->effect_to_redraw == NULL ||
3391 priv->current_effect != priv->effect_to_redraw)
3392 run_flags |= CLUTTER_EFFECT_PAINT_ACTOR_DIRTY;
3395 _clutter_effect_paint (priv->current_effect, run_flags);
3399 /* We can't determine when an actor has been modified since
3400 its last pick so lets just assume it has always been
3402 run_flags |= CLUTTER_EFFECT_PAINT_ACTOR_DIRTY;
3404 _clutter_effect_pick (priv->current_effect, run_flags);
3407 priv->current_effect = old_current_effect;
3411 static ClutterActorTraverseVisitFlags
3412 invalidate_queue_redraw_entry (ClutterActor *self,
3416 ClutterActorPrivate *priv = self->priv;
3418 if (priv->queue_redraw_entry != NULL)
3420 _clutter_stage_queue_redraw_entry_invalidate (priv->queue_redraw_entry);
3421 priv->queue_redraw_entry = NULL;
3424 return CLUTTER_ACTOR_TRAVERSE_VISIT_CONTINUE;
3428 remove_child (ClutterActor *self,
3429 ClutterActor *child)
3431 ClutterActor *prev_sibling, *next_sibling;
3433 prev_sibling = child->priv->prev_sibling;
3434 next_sibling = child->priv->next_sibling;
3436 if (prev_sibling != NULL)
3437 prev_sibling->priv->next_sibling = next_sibling;
3439 if (next_sibling != NULL)
3440 next_sibling->priv->prev_sibling = prev_sibling;
3442 if (self->priv->first_child == child)
3443 self->priv->first_child = next_sibling;
3445 if (self->priv->last_child == child)
3446 self->priv->last_child = prev_sibling;
3448 child->priv->parent = NULL;
3449 child->priv->prev_sibling = NULL;
3450 child->priv->next_sibling = NULL;
3454 REMOVE_CHILD_DESTROY_META = 1 << 0,
3455 REMOVE_CHILD_EMIT_PARENT_SET = 1 << 1,
3456 REMOVE_CHILD_EMIT_ACTOR_REMOVED = 1 << 2,
3457 REMOVE_CHILD_CHECK_STATE = 1 << 3,
3458 REMOVE_CHILD_FLUSH_QUEUE = 1 << 4,
3459 REMOVE_CHILD_NOTIFY_FIRST_LAST = 1 << 5,
3461 /* default flags for public API */
3462 REMOVE_CHILD_DEFAULT_FLAGS = REMOVE_CHILD_DESTROY_META |
3463 REMOVE_CHILD_EMIT_PARENT_SET |
3464 REMOVE_CHILD_EMIT_ACTOR_REMOVED |
3465 REMOVE_CHILD_CHECK_STATE |
3466 REMOVE_CHILD_FLUSH_QUEUE |
3467 REMOVE_CHILD_NOTIFY_FIRST_LAST,
3469 /* flags for legacy/deprecated API */
3470 REMOVE_CHILD_LEGACY_FLAGS = REMOVE_CHILD_CHECK_STATE |
3471 REMOVE_CHILD_FLUSH_QUEUE |
3472 REMOVE_CHILD_EMIT_PARENT_SET |
3473 REMOVE_CHILD_NOTIFY_FIRST_LAST
3474 } ClutterActorRemoveChildFlags;
3477 * clutter_actor_remove_child_internal:
3478 * @self: a #ClutterActor
3479 * @child: the child of @self that has to be removed
3480 * @flags: control the removal operations
3482 * Removes @child from the list of children of @self.
3485 clutter_actor_remove_child_internal (ClutterActor *self,
3486 ClutterActor *child,
3487 ClutterActorRemoveChildFlags flags)
3489 ClutterActor *old_first, *old_last;
3490 gboolean destroy_meta, emit_parent_set, emit_actor_removed, check_state;
3491 gboolean flush_queue;
3492 gboolean notify_first_last;
3493 gboolean was_mapped;
3495 destroy_meta = (flags & REMOVE_CHILD_DESTROY_META) != 0;
3496 emit_parent_set = (flags & REMOVE_CHILD_EMIT_PARENT_SET) != 0;
3497 emit_actor_removed = (flags & REMOVE_CHILD_EMIT_ACTOR_REMOVED) != 0;
3498 check_state = (flags & REMOVE_CHILD_CHECK_STATE) != 0;
3499 flush_queue = (flags & REMOVE_CHILD_FLUSH_QUEUE) != 0;
3500 notify_first_last = (flags & REMOVE_CHILD_NOTIFY_FIRST_LAST) != 0;
3502 g_object_freeze_notify (G_OBJECT (self));
3505 clutter_container_destroy_child_meta (CLUTTER_CONTAINER (self), child);
3509 was_mapped = CLUTTER_ACTOR_IS_MAPPED (child);
3511 /* we need to unrealize *before* we set parent_actor to NULL,
3512 * because in an unrealize method actors are dissociating from the
3513 * stage, which means they need to be able to
3514 * clutter_actor_get_stage().
3516 * yhis should unmap and unrealize, unless we're reparenting.
3518 clutter_actor_update_map_state (child, MAP_STATE_MAKE_UNREALIZED);
3525 /* We take this opportunity to invalidate any queue redraw entry
3526 * associated with the actor and descendants since we won't be able to
3527 * determine the appropriate stage after this.
3529 * we do this after we updated the mapped state because actors might
3530 * end up queueing redraws inside their mapped/unmapped virtual
3531 * functions, and if we invalidate the redraw entry we could end up
3532 * with an inconsistent state and weird memory corruption. see
3535 * http://bugzilla.clutter-project.org/show_bug.cgi?id=2621
3536 * https://bugzilla.gnome.org/show_bug.cgi?id=652036
3538 _clutter_actor_traverse (child,
3540 invalidate_queue_redraw_entry,
3545 old_first = self->priv->first_child;
3546 old_last = self->priv->last_child;
3548 remove_child (self, child);
3550 self->priv->n_children -= 1;
3552 self->priv->age += 1;
3554 /* clutter_actor_reparent() will emit ::parent-set for us */
3555 if (emit_parent_set && !CLUTTER_ACTOR_IN_REPARENT (child))
3556 g_signal_emit (child, actor_signals[PARENT_SET], 0, self);
3558 /* if the child was mapped then we need to relayout ourselves to account
3559 * for the removed child
3562 clutter_actor_queue_relayout (self);
3564 /* we need to emit the signal before dropping the reference */
3565 if (emit_actor_removed)
3566 g_signal_emit_by_name (self, "actor-removed", child);
3568 if (notify_first_last)
3570 if (old_first != self->priv->first_child)
3571 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_FIRST_CHILD]);
3573 if (old_last != self->priv->last_child)
3574 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_LAST_CHILD]);
3577 g_object_thaw_notify (G_OBJECT (self));
3579 /* remove the reference we acquired in clutter_actor_add_child() */
3580 g_object_unref (child);
3583 static const ClutterTransformInfo default_transform_info = {
3584 0.0, { 0, }, /* rotation-x */
3585 0.0, { 0, }, /* rotation-y */
3586 0.0, { 0, }, /* rotation-z */
3588 1.0, 1.0, { 0, }, /* scale */
3590 { 0, }, /* anchor */
3594 * _clutter_actor_get_transform_info_or_defaults:
3595 * @self: a #ClutterActor
3597 * Retrieves the ClutterTransformInfo structure associated to an actor.
3599 * If the actor does not have a ClutterTransformInfo structure associated
3600 * to it, then the default structure will be returned.
3602 * This function should only be used for getters.
3604 * Return value: a const pointer to the ClutterTransformInfo structure
3606 const ClutterTransformInfo *
3607 _clutter_actor_get_transform_info_or_defaults (ClutterActor *self)
3609 ClutterTransformInfo *info;
3611 info = g_object_get_qdata (G_OBJECT (self), quark_actor_transform_info);
3615 return &default_transform_info;
3619 clutter_transform_info_free (gpointer data)
3622 g_slice_free (ClutterTransformInfo, data);
3626 * _clutter_actor_get_transform_info:
3627 * @self: a #ClutterActor
3629 * Retrieves a pointer to the ClutterTransformInfo structure.
3631 * If the actor does not have a ClutterTransformInfo associated to it, one
3632 * will be created and initialized to the default values.
3634 * This function should be used for setters.
3636 * For getters, you should use _clutter_actor_get_transform_info_or_defaults()
3639 * Return value: (transfer none): a pointer to the ClutterTransformInfo
3642 ClutterTransformInfo *
3643 _clutter_actor_get_transform_info (ClutterActor *self)
3645 ClutterTransformInfo *info;
3647 info = g_object_get_qdata (G_OBJECT (self), quark_actor_transform_info);
3650 info = g_slice_new (ClutterTransformInfo);
3652 *info = default_transform_info;
3654 g_object_set_qdata_full (G_OBJECT (self), quark_actor_transform_info,
3656 clutter_transform_info_free);
3663 * clutter_actor_set_rotation_angle_internal:
3664 * @self: a #ClutterActor
3665 * @axis: the axis of the angle to change
3666 * @angle: the angle of rotation
3668 * Sets the rotation angle on the given axis without affecting the
3669 * rotation center point.
3672 clutter_actor_set_rotation_angle_internal (ClutterActor *self,
3673 ClutterRotateAxis axis,
3676 GObject *obj = G_OBJECT (self);
3677 ClutterTransformInfo *info;
3679 info = _clutter_actor_get_transform_info (self);
3681 g_object_freeze_notify (obj);
3685 case CLUTTER_X_AXIS:
3686 info->rx_angle = angle;
3687 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_ANGLE_X]);
3690 case CLUTTER_Y_AXIS:
3691 info->ry_angle = angle;
3692 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_ANGLE_Y]);
3695 case CLUTTER_Z_AXIS:
3696 info->rz_angle = angle;
3697 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_ANGLE_Z]);
3701 self->priv->transform_valid = FALSE;
3703 g_object_thaw_notify (obj);
3705 clutter_actor_queue_redraw (self);
3709 * clutter_actor_set_rotation_center_internal:
3710 * @self: a #ClutterActor
3711 * @axis: the axis of the center to change
3712 * @center: the coordinates of the rotation center
3714 * Sets the rotation center on the given axis without affecting the
3718 clutter_actor_set_rotation_center_internal (ClutterActor *self,
3719 ClutterRotateAxis axis,
3720 const ClutterVertex *center)
3722 GObject *obj = G_OBJECT (self);
3723 ClutterTransformInfo *info;
3724 ClutterVertex v = { 0, 0, 0 };
3726 info = _clutter_actor_get_transform_info (self);
3731 g_object_freeze_notify (obj);
3735 case CLUTTER_X_AXIS:
3736 clutter_anchor_coord_set_units (&info->rx_center, v.x, v.y, v.z);
3737 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_X]);
3740 case CLUTTER_Y_AXIS:
3741 clutter_anchor_coord_set_units (&info->ry_center, v.x, v.y, v.z);
3742 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_Y]);
3745 case CLUTTER_Z_AXIS:
3746 /* if the previously set rotation center was fractional, then
3747 * setting explicit coordinates will have to notify the
3748 * :rotation-center-z-gravity property as well
3750 if (info->rz_center.is_fractional)
3751 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_Z_GRAVITY]);
3753 clutter_anchor_coord_set_units (&info->rz_center, v.x, v.y, v.z);
3754 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_Z]);
3758 self->priv->transform_valid = FALSE;
3760 g_object_thaw_notify (obj);
3762 clutter_actor_queue_redraw (self);
3766 clutter_actor_set_scale_factor (ClutterActor *self,
3767 ClutterRotateAxis axis,
3770 GObject *obj = G_OBJECT (self);
3771 ClutterTransformInfo *info;
3773 info = _clutter_actor_get_transform_info (self);
3775 g_object_freeze_notify (obj);
3779 case CLUTTER_X_AXIS:
3780 info->scale_x = factor;
3781 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_X]);
3784 case CLUTTER_Y_AXIS:
3785 info->scale_y = factor;
3786 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_Y]);
3790 g_assert_not_reached ();
3793 self->priv->transform_valid = FALSE;
3795 clutter_actor_queue_redraw (self);
3797 g_object_thaw_notify (obj);
3801 clutter_actor_set_scale_center (ClutterActor *self,
3802 ClutterRotateAxis axis,
3805 GObject *obj = G_OBJECT (self);
3806 ClutterTransformInfo *info;
3807 gfloat center_x, center_y;
3809 info = _clutter_actor_get_transform_info (self);
3811 g_object_freeze_notify (obj);
3813 /* get the current scale center coordinates */
3814 clutter_anchor_coord_get_units (self, &info->scale_center,
3819 /* we need to notify this too, because setting explicit coordinates will
3820 * change the gravity as a side effect
3822 if (info->scale_center.is_fractional)
3823 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_GRAVITY]);
3827 case CLUTTER_X_AXIS:
3828 clutter_anchor_coord_set_units (&info->scale_center, coord, center_y, 0);
3829 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_CENTER_X]);
3832 case CLUTTER_Y_AXIS:
3833 clutter_anchor_coord_set_units (&info->scale_center, center_x, coord, 0);
3834 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_CENTER_Y]);
3838 g_assert_not_reached ();
3841 self->priv->transform_valid = FALSE;
3843 clutter_actor_queue_redraw (self);
3845 g_object_thaw_notify (obj);
3849 clutter_actor_set_anchor_coord (ClutterActor *self,
3850 ClutterRotateAxis axis,
3853 GObject *obj = G_OBJECT (self);
3854 ClutterTransformInfo *info;
3855 gfloat anchor_x, anchor_y;
3857 info = _clutter_actor_get_transform_info (self);
3859 g_object_freeze_notify (obj);
3861 clutter_anchor_coord_get_units (self, &info->anchor,
3866 if (info->anchor.is_fractional)
3867 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_GRAVITY]);
3871 case CLUTTER_X_AXIS:
3872 clutter_anchor_coord_set_units (&info->anchor,
3876 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_X]);
3879 case CLUTTER_Y_AXIS:
3880 clutter_anchor_coord_set_units (&info->anchor,
3884 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_Y]);
3888 g_assert_not_reached ();
3891 self->priv->transform_valid = FALSE;
3893 clutter_actor_queue_redraw (self);
3895 g_object_thaw_notify (obj);
3899 clutter_actor_set_property (GObject *object,
3901 const GValue *value,
3904 ClutterActor *actor = CLUTTER_ACTOR (object);
3905 ClutterActorPrivate *priv = actor->priv;
3910 clutter_actor_set_x (actor, g_value_get_float (value));
3914 clutter_actor_set_y (actor, g_value_get_float (value));
3918 clutter_actor_set_width (actor, g_value_get_float (value));
3922 clutter_actor_set_height (actor, g_value_get_float (value));
3926 clutter_actor_set_x (actor, g_value_get_float (value));
3930 clutter_actor_set_y (actor, g_value_get_float (value));
3933 case PROP_FIXED_POSITION_SET:
3934 clutter_actor_set_fixed_position_set (actor, g_value_get_boolean (value));
3937 case PROP_MIN_WIDTH:
3938 clutter_actor_set_min_width (actor, g_value_get_float (value));
3941 case PROP_MIN_HEIGHT:
3942 clutter_actor_set_min_height (actor, g_value_get_float (value));
3945 case PROP_NATURAL_WIDTH:
3946 clutter_actor_set_natural_width (actor, g_value_get_float (value));
3949 case PROP_NATURAL_HEIGHT:
3950 clutter_actor_set_natural_height (actor, g_value_get_float (value));
3953 case PROP_MIN_WIDTH_SET:
3954 clutter_actor_set_min_width_set (actor, g_value_get_boolean (value));
3957 case PROP_MIN_HEIGHT_SET:
3958 clutter_actor_set_min_height_set (actor, g_value_get_boolean (value));
3961 case PROP_NATURAL_WIDTH_SET:
3962 clutter_actor_set_natural_width_set (actor, g_value_get_boolean (value));
3965 case PROP_NATURAL_HEIGHT_SET:
3966 clutter_actor_set_natural_height_set (actor, g_value_get_boolean (value));
3969 case PROP_REQUEST_MODE:
3970 clutter_actor_set_request_mode (actor, g_value_get_enum (value));
3974 clutter_actor_set_depth (actor, g_value_get_float (value));
3978 clutter_actor_set_opacity (actor, g_value_get_uint (value));
3981 case PROP_OFFSCREEN_REDIRECT:
3982 clutter_actor_set_offscreen_redirect (actor, g_value_get_enum (value));
3986 clutter_actor_set_name (actor, g_value_get_string (value));
3990 if (g_value_get_boolean (value) == TRUE)
3991 clutter_actor_show (actor);
3993 clutter_actor_hide (actor);
3997 clutter_actor_set_scale_factor (actor, CLUTTER_X_AXIS,
3998 g_value_get_double (value));
4002 clutter_actor_set_scale_factor (actor, CLUTTER_Y_AXIS,
4003 g_value_get_double (value));
4006 case PROP_SCALE_CENTER_X:
4007 clutter_actor_set_scale_center (actor, CLUTTER_X_AXIS,
4008 g_value_get_float (value));
4011 case PROP_SCALE_CENTER_Y:
4012 clutter_actor_set_scale_center (actor, CLUTTER_Y_AXIS,
4013 g_value_get_float (value));
4016 case PROP_SCALE_GRAVITY:
4018 const ClutterTransformInfo *info;
4019 ClutterGravity gravity;
4021 info = _clutter_actor_get_transform_info_or_defaults (actor);
4022 gravity = g_value_get_enum (value);
4024 clutter_actor_set_scale_with_gravity (actor,
4033 const ClutterGeometry *geom = g_value_get_boxed (value);
4035 clutter_actor_set_clip (actor,
4037 geom->width, geom->height);
4041 case PROP_CLIP_TO_ALLOCATION:
4042 clutter_actor_set_clip_to_allocation (actor, g_value_get_boolean (value));
4046 clutter_actor_set_reactive (actor, g_value_get_boolean (value));
4049 case PROP_ROTATION_ANGLE_X:
4050 clutter_actor_set_rotation_angle_internal (actor,
4052 g_value_get_double (value));
4055 case PROP_ROTATION_ANGLE_Y:
4056 clutter_actor_set_rotation_angle_internal (actor,
4058 g_value_get_double (value));
4061 case PROP_ROTATION_ANGLE_Z:
4062 clutter_actor_set_rotation_angle_internal (actor,
4064 g_value_get_double (value));
4067 case PROP_ROTATION_CENTER_X:
4068 clutter_actor_set_rotation_center_internal (actor,
4070 g_value_get_boxed (value));
4073 case PROP_ROTATION_CENTER_Y:
4074 clutter_actor_set_rotation_center_internal (actor,
4076 g_value_get_boxed (value));
4079 case PROP_ROTATION_CENTER_Z:
4080 clutter_actor_set_rotation_center_internal (actor,
4082 g_value_get_boxed (value));
4085 case PROP_ROTATION_CENTER_Z_GRAVITY:
4087 const ClutterTransformInfo *info;
4089 info = _clutter_actor_get_transform_info_or_defaults (actor);
4090 clutter_actor_set_z_rotation_from_gravity (actor, info->rz_angle,
4091 g_value_get_enum (value));
4096 clutter_actor_set_anchor_coord (actor, CLUTTER_X_AXIS,
4097 g_value_get_float (value));
4101 clutter_actor_set_anchor_coord (actor, CLUTTER_Y_AXIS,
4102 g_value_get_float (value));
4105 case PROP_ANCHOR_GRAVITY:
4106 clutter_actor_set_anchor_point_from_gravity (actor,
4107 g_value_get_enum (value));
4110 case PROP_SHOW_ON_SET_PARENT:
4111 priv->show_on_set_parent = g_value_get_boolean (value);
4114 case PROP_TEXT_DIRECTION:
4115 clutter_actor_set_text_direction (actor, g_value_get_enum (value));
4119 clutter_actor_add_action (actor, g_value_get_object (value));
4122 case PROP_CONSTRAINTS:
4123 clutter_actor_add_constraint (actor, g_value_get_object (value));
4127 clutter_actor_add_effect (actor, g_value_get_object (value));
4130 case PROP_LAYOUT_MANAGER:
4131 clutter_actor_set_layout_manager (actor, g_value_get_object (value));
4135 clutter_actor_set_x_align (actor, g_value_get_enum (value));
4139 clutter_actor_set_y_align (actor, g_value_get_enum (value));
4142 case PROP_MARGIN_TOP:
4143 clutter_actor_set_margin_top (actor, g_value_get_float (value));
4146 case PROP_MARGIN_BOTTOM:
4147 clutter_actor_set_margin_bottom (actor, g_value_get_float (value));
4150 case PROP_MARGIN_LEFT:
4151 clutter_actor_set_margin_left (actor, g_value_get_float (value));
4154 case PROP_MARGIN_RIGHT:
4155 clutter_actor_set_margin_right (actor, g_value_get_float (value));
4158 case PROP_BACKGROUND_COLOR:
4159 clutter_actor_set_background_color (actor, g_value_get_boxed (value));
4163 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
4169 clutter_actor_get_property (GObject *object,
4174 ClutterActor *actor = CLUTTER_ACTOR (object);
4175 ClutterActorPrivate *priv = actor->priv;
4180 g_value_set_float (value, clutter_actor_get_x (actor));
4184 g_value_set_float (value, clutter_actor_get_y (actor));
4188 g_value_set_float (value, clutter_actor_get_width (actor));
4192 g_value_set_float (value, clutter_actor_get_height (actor));
4197 const ClutterLayoutInfo *info;
4199 info = _clutter_actor_get_layout_info_or_defaults (actor);
4200 g_value_set_float (value, info->fixed_x);
4206 const ClutterLayoutInfo *info;
4208 info = _clutter_actor_get_layout_info_or_defaults (actor);
4209 g_value_set_float (value, info->fixed_y);
4213 case PROP_FIXED_POSITION_SET:
4214 g_value_set_boolean (value, priv->position_set);
4217 case PROP_MIN_WIDTH:
4219 const ClutterLayoutInfo *info;
4221 info = _clutter_actor_get_layout_info_or_defaults (actor);
4222 g_value_set_float (value, info->min_width);
4226 case PROP_MIN_HEIGHT:
4228 const ClutterLayoutInfo *info;
4230 info = _clutter_actor_get_layout_info_or_defaults (actor);
4231 g_value_set_float (value, info->min_height);
4235 case PROP_NATURAL_WIDTH:
4237 const ClutterLayoutInfo *info;
4239 info = _clutter_actor_get_layout_info_or_defaults (actor);
4240 g_value_set_float (value, info->natural_width);
4244 case PROP_NATURAL_HEIGHT:
4246 const ClutterLayoutInfo *info;
4248 info = _clutter_actor_get_layout_info_or_defaults (actor);
4249 g_value_set_float (value, info->natural_height);
4253 case PROP_MIN_WIDTH_SET:
4254 g_value_set_boolean (value, priv->min_width_set);
4257 case PROP_MIN_HEIGHT_SET:
4258 g_value_set_boolean (value, priv->min_height_set);
4261 case PROP_NATURAL_WIDTH_SET:
4262 g_value_set_boolean (value, priv->natural_width_set);
4265 case PROP_NATURAL_HEIGHT_SET:
4266 g_value_set_boolean (value, priv->natural_height_set);
4269 case PROP_REQUEST_MODE:
4270 g_value_set_enum (value, priv->request_mode);
4273 case PROP_ALLOCATION:
4274 g_value_set_boxed (value, &priv->allocation);
4278 g_value_set_float (value, clutter_actor_get_depth (actor));
4282 g_value_set_uint (value, priv->opacity);
4285 case PROP_OFFSCREEN_REDIRECT:
4286 g_value_set_enum (value, priv->offscreen_redirect);
4290 g_value_set_string (value, priv->name);
4294 g_value_set_boolean (value, CLUTTER_ACTOR_IS_VISIBLE (actor));
4298 g_value_set_boolean (value, CLUTTER_ACTOR_IS_MAPPED (actor));
4302 g_value_set_boolean (value, CLUTTER_ACTOR_IS_REALIZED (actor));
4306 g_value_set_boolean (value, priv->has_clip);
4311 ClutterGeometry clip;
4313 clip.x = CLUTTER_NEARBYINT (priv->clip.x);
4314 clip.y = CLUTTER_NEARBYINT (priv->clip.y);
4315 clip.width = CLUTTER_NEARBYINT (priv->clip.width);
4316 clip.height = CLUTTER_NEARBYINT (priv->clip.height);
4318 g_value_set_boxed (value, &clip);
4322 case PROP_CLIP_TO_ALLOCATION:
4323 g_value_set_boolean (value, priv->clip_to_allocation);
4328 const ClutterTransformInfo *info;
4330 info = _clutter_actor_get_transform_info_or_defaults (actor);
4331 g_value_set_double (value, info->scale_x);
4337 const ClutterTransformInfo *info;
4339 info = _clutter_actor_get_transform_info_or_defaults (actor);
4340 g_value_set_double (value, info->scale_y);
4344 case PROP_SCALE_CENTER_X:
4348 clutter_actor_get_scale_center (actor, ¢er, NULL);
4350 g_value_set_float (value, center);
4354 case PROP_SCALE_CENTER_Y:
4358 clutter_actor_get_scale_center (actor, NULL, ¢er);
4360 g_value_set_float (value, center);
4364 case PROP_SCALE_GRAVITY:
4365 g_value_set_enum (value, clutter_actor_get_scale_gravity (actor));
4369 g_value_set_boolean (value, clutter_actor_get_reactive (actor));
4372 case PROP_ROTATION_ANGLE_X:
4374 const ClutterTransformInfo *info;
4376 info = _clutter_actor_get_transform_info_or_defaults (actor);
4377 g_value_set_double (value, info->rx_angle);
4381 case PROP_ROTATION_ANGLE_Y:
4383 const ClutterTransformInfo *info;
4385 info = _clutter_actor_get_transform_info_or_defaults (actor);
4386 g_value_set_double (value, info->ry_angle);
4390 case PROP_ROTATION_ANGLE_Z:
4392 const ClutterTransformInfo *info;
4394 info = _clutter_actor_get_transform_info_or_defaults (actor);
4395 g_value_set_double (value, info->rz_angle);
4399 case PROP_ROTATION_CENTER_X:
4401 ClutterVertex center;
4403 clutter_actor_get_rotation (actor, CLUTTER_X_AXIS,
4408 g_value_set_boxed (value, ¢er);
4412 case PROP_ROTATION_CENTER_Y:
4414 ClutterVertex center;
4416 clutter_actor_get_rotation (actor, CLUTTER_Y_AXIS,
4421 g_value_set_boxed (value, ¢er);
4425 case PROP_ROTATION_CENTER_Z:
4427 ClutterVertex center;
4429 clutter_actor_get_rotation (actor, CLUTTER_Z_AXIS,
4434 g_value_set_boxed (value, ¢er);
4438 case PROP_ROTATION_CENTER_Z_GRAVITY:
4439 g_value_set_enum (value, clutter_actor_get_z_rotation_gravity (actor));
4444 const ClutterTransformInfo *info;
4447 info = _clutter_actor_get_transform_info_or_defaults (actor);
4448 clutter_anchor_coord_get_units (actor, &info->anchor,
4452 g_value_set_float (value, anchor_x);
4458 const ClutterTransformInfo *info;
4461 info = _clutter_actor_get_transform_info_or_defaults (actor);
4462 clutter_anchor_coord_get_units (actor, &info->anchor,
4466 g_value_set_float (value, anchor_y);
4470 case PROP_ANCHOR_GRAVITY:
4471 g_value_set_enum (value, clutter_actor_get_anchor_point_gravity (actor));
4474 case PROP_SHOW_ON_SET_PARENT:
4475 g_value_set_boolean (value, priv->show_on_set_parent);
4478 case PROP_TEXT_DIRECTION:
4479 g_value_set_enum (value, priv->text_direction);
4482 case PROP_HAS_POINTER:
4483 g_value_set_boolean (value, priv->has_pointer);
4486 case PROP_LAYOUT_MANAGER:
4487 g_value_set_object (value, priv->layout_manager);
4492 const ClutterLayoutInfo *info;
4494 info = _clutter_actor_get_layout_info_or_defaults (actor);
4495 g_value_set_enum (value, info->x_align);
4501 const ClutterLayoutInfo *info;
4503 info = _clutter_actor_get_layout_info_or_defaults (actor);
4504 g_value_set_enum (value, info->y_align);
4508 case PROP_MARGIN_TOP:
4510 const ClutterLayoutInfo *info;
4512 info = _clutter_actor_get_layout_info_or_defaults (actor);
4513 g_value_set_float (value, info->margin.top);
4517 case PROP_MARGIN_BOTTOM:
4519 const ClutterLayoutInfo *info;
4521 info = _clutter_actor_get_layout_info_or_defaults (actor);
4522 g_value_set_float (value, info->margin.bottom);
4526 case PROP_MARGIN_LEFT:
4528 const ClutterLayoutInfo *info;
4530 info = _clutter_actor_get_layout_info_or_defaults (actor);
4531 g_value_set_float (value, info->margin.left);
4535 case PROP_MARGIN_RIGHT:
4537 const ClutterLayoutInfo *info;
4539 info = _clutter_actor_get_layout_info_or_defaults (actor);
4540 g_value_set_float (value, info->margin.right);
4544 case PROP_BACKGROUND_COLOR_SET:
4545 g_value_set_boolean (value, priv->bg_color_set);
4548 case PROP_BACKGROUND_COLOR:
4549 g_value_set_boxed (value, &priv->bg_color);
4552 case PROP_FIRST_CHILD:
4553 g_value_set_object (value, priv->first_child);
4556 case PROP_LAST_CHILD:
4557 g_value_set_object (value, priv->last_child);
4561 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
4567 clutter_actor_dispose (GObject *object)
4569 ClutterActor *self = CLUTTER_ACTOR (object);
4570 ClutterActorPrivate *priv = self->priv;
4572 CLUTTER_NOTE (MISC, "Disposing of object (id=%d) of type '%s' (ref_count:%d)",
4574 g_type_name (G_OBJECT_TYPE (self)),
4577 g_signal_emit (self, actor_signals[DESTROY], 0);
4579 /* avoid recursing when called from clutter_actor_destroy() */
4580 if (priv->parent != NULL)
4582 ClutterActor *parent = priv->parent;
4584 /* go through the Container implementation unless this
4585 * is an internal child and has been marked as such.
4587 * removing the actor from its parent will reset the
4588 * realized and mapped states.
4590 if (!CLUTTER_ACTOR_IS_INTERNAL_CHILD (self))
4591 clutter_container_remove_actor (CLUTTER_CONTAINER (parent), self);
4593 clutter_actor_remove_child_internal (parent, self,
4594 REMOVE_CHILD_LEGACY_FLAGS);
4597 /* parent must be gone at this point */
4598 g_assert (priv->parent == NULL);
4600 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
4602 /* can't be mapped or realized with no parent */
4603 g_assert (!CLUTTER_ACTOR_IS_MAPPED (self));
4604 g_assert (!CLUTTER_ACTOR_IS_REALIZED (self));
4607 g_clear_object (&priv->pango_context);
4608 g_clear_object (&priv->actions);
4609 g_clear_object (&priv->constraints);
4610 g_clear_object (&priv->effects);
4611 g_clear_object (&priv->flatten_effect);
4613 if (priv->layout_manager != NULL)
4615 clutter_layout_manager_set_container (priv->layout_manager, NULL);
4616 g_object_unref (priv->layout_manager);
4617 priv->layout_manager = NULL;
4620 G_OBJECT_CLASS (clutter_actor_parent_class)->dispose (object);
4624 clutter_actor_finalize (GObject *object)
4626 ClutterActorPrivate *priv = CLUTTER_ACTOR (object)->priv;
4628 CLUTTER_NOTE (MISC, "Finalize actor (name='%s', id=%d) of type '%s'",
4629 priv->name != NULL ? priv->name : "<none>",
4631 g_type_name (G_OBJECT_TYPE (object)));
4633 _clutter_context_release_id (priv->id);
4635 g_free (priv->name);
4637 G_OBJECT_CLASS (clutter_actor_parent_class)->finalize (object);
4642 * clutter_actor_get_accessible:
4643 * @self: a #ClutterActor
4645 * Returns the accessible object that describes the actor to an
4646 * assistive technology.
4648 * If no class-specific #AtkObject implementation is available for the
4649 * actor instance in question, it will inherit an #AtkObject
4650 * implementation from the first ancestor class for which such an
4651 * implementation is defined.
4653 * The documentation of the <ulink
4654 * url="http://developer.gnome.org/doc/API/2.0/atk/index.html">ATK</ulink>
4655 * library contains more information about accessible objects and
4658 * Returns: (transfer none): the #AtkObject associated with @actor
4661 clutter_actor_get_accessible (ClutterActor *self)
4663 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
4665 return CLUTTER_ACTOR_GET_CLASS (self)->get_accessible (self);
4669 clutter_actor_real_get_accessible (ClutterActor *actor)
4671 return atk_gobject_accessible_for_object (G_OBJECT (actor));
4675 _clutter_actor_ref_accessible (AtkImplementor *implementor)
4677 AtkObject *accessible;
4679 accessible = clutter_actor_get_accessible (CLUTTER_ACTOR (implementor));
4680 if (accessible != NULL)
4681 g_object_ref (accessible);
4687 atk_implementor_iface_init (AtkImplementorIface *iface)
4689 iface->ref_accessible = _clutter_actor_ref_accessible;
4693 clutter_actor_update_default_paint_volume (ClutterActor *self,
4694 ClutterPaintVolume *volume)
4696 ClutterActorPrivate *priv = self->priv;
4697 gboolean res = FALSE;
4699 /* we start from the allocation */
4700 clutter_paint_volume_set_width (volume,
4701 priv->allocation.x2 - priv->allocation.x1);
4702 clutter_paint_volume_set_height (volume,
4703 priv->allocation.y2 - priv->allocation.y1);
4705 /* if the actor has a clip set then we have a pretty definite
4706 * size for the paint volume: the actor cannot possibly paint
4707 * outside the clip region.
4709 if (priv->clip_to_allocation)
4711 /* the allocation has already been set, so we just flip the
4718 ClutterActor *child;
4720 if (priv->has_clip &&
4721 priv->clip.width >= 0 &&
4722 priv->clip.height >= 0)
4724 ClutterVertex origin;
4726 origin.x = priv->clip.x;
4727 origin.y = priv->clip.y;
4730 clutter_paint_volume_set_origin (volume, &origin);
4731 clutter_paint_volume_set_width (volume, priv->clip.width);
4732 clutter_paint_volume_set_height (volume, priv->clip.height);
4737 /* if we don't have children we just bail out here... */
4738 if (priv->n_children == 0)
4741 /* ...but if we have children then we ask for their paint volume in
4742 * our coordinates. if any of our children replies that it doesn't
4743 * have a paint volume, we bail out
4745 for (child = priv->first_child;
4747 child = child->priv->next_sibling)
4749 const ClutterPaintVolume *child_volume;
4751 child_volume = clutter_actor_get_transformed_paint_volume (child, self);
4752 if (child_volume == NULL)
4758 clutter_paint_volume_union (volume, child_volume);
4768 clutter_actor_real_get_paint_volume (ClutterActor *self,
4769 ClutterPaintVolume *volume)
4771 ClutterActorClass *klass;
4774 klass = CLUTTER_ACTOR_GET_CLASS (self);
4776 /* XXX - this thoroughly sucks, but we don't want to penalize users
4777 * who use ClutterActor as a "new ClutterGroup" by forcing a full-stage
4778 * redraw. This should go away in 2.0.
4780 if (klass->paint == clutter_actor_real_paint &&
4781 klass->get_paint_volume == clutter_actor_real_get_paint_volume)
4787 /* this is the default return value: we cannot know if a class
4788 * is going to paint outside its allocation, so we take the
4789 * conservative approach.
4794 if (clutter_actor_update_default_paint_volume (self, volume))
4801 * clutter_actor_get_default_paint_volume:
4802 * @self: a #ClutterActor
4804 * Retrieves the default paint volume for @self.
4806 * This function provides the same #ClutterPaintVolume that would be
4807 * computed by the default implementation inside #ClutterActor of the
4808 * #ClutterActorClass.get_paint_volume() virtual function.
4810 * This function should only be used by #ClutterActor subclasses that
4811 * cannot chain up to the parent implementation when computing their
4814 * Return value: (transfer none): a pointer to the default
4815 * #ClutterPaintVolume, relative to the #ClutterActor, or %NULL if
4816 * the actor could not compute a valid paint volume. The returned value
4817 * is not guaranteed to be stable across multiple frames, so if you
4818 * want to retain it, you will need to copy it using
4819 * clutter_paint_volume_copy().
4823 const ClutterPaintVolume *
4824 clutter_actor_get_default_paint_volume (ClutterActor *self)
4826 ClutterPaintVolume volume;
4827 ClutterPaintVolume *res;
4829 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
4832 _clutter_paint_volume_init_static (&volume, self);
4833 if (clutter_actor_update_default_paint_volume (self, &volume))
4835 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
4839 res = _clutter_stage_paint_volume_stack_allocate (CLUTTER_STAGE (stage));
4840 _clutter_paint_volume_copy_static (&volume, res);
4844 clutter_paint_volume_free (&volume);
4850 clutter_actor_real_has_overlaps (ClutterActor *self)
4852 /* By default we'll assume that all actors need an offscreen redirect to get
4853 * the correct opacity. Actors such as ClutterTexture that would never need
4854 * an offscreen redirect can override this to return FALSE. */
4859 clutter_actor_real_destroy (ClutterActor *actor)
4861 ClutterActorIter iter;
4863 clutter_actor_iter_init (&iter, actor);
4864 while (clutter_actor_iter_next (&iter, NULL))
4865 clutter_actor_iter_destroy (&iter);
4869 clutter_actor_constructor (GType gtype,
4871 GObjectConstructParam *props)
4873 GObjectClass *gobject_class;
4877 gobject_class = G_OBJECT_CLASS (clutter_actor_parent_class);
4878 retval = gobject_class->constructor (gtype, n_props, props);
4879 self = CLUTTER_ACTOR (retval);
4881 if (self->priv->layout_manager == NULL)
4883 ClutterLayoutManager *default_layout;
4885 CLUTTER_NOTE (LAYOUT, "Creating default layout manager");
4887 default_layout = clutter_fixed_layout_new ();
4888 clutter_actor_set_layout_manager (self, default_layout);
4895 clutter_actor_class_init (ClutterActorClass *klass)
4897 GObjectClass *object_class = G_OBJECT_CLASS (klass);
4899 quark_shader_data = g_quark_from_static_string ("-clutter-actor-shader-data");
4900 quark_actor_layout_info = g_quark_from_static_string ("-clutter-actor-layout-info");
4901 quark_actor_transform_info = g_quark_from_static_string ("-clutter-actor-transform-info");
4903 object_class->constructor = clutter_actor_constructor;
4904 object_class->set_property = clutter_actor_set_property;
4905 object_class->get_property = clutter_actor_get_property;
4906 object_class->dispose = clutter_actor_dispose;
4907 object_class->finalize = clutter_actor_finalize;
4909 klass->show = clutter_actor_real_show;
4910 klass->show_all = clutter_actor_show;
4911 klass->hide = clutter_actor_real_hide;
4912 klass->hide_all = clutter_actor_hide;
4913 klass->map = clutter_actor_real_map;
4914 klass->unmap = clutter_actor_real_unmap;
4915 klass->unrealize = clutter_actor_real_unrealize;
4916 klass->pick = clutter_actor_real_pick;
4917 klass->get_preferred_width = clutter_actor_real_get_preferred_width;
4918 klass->get_preferred_height = clutter_actor_real_get_preferred_height;
4919 klass->allocate = clutter_actor_real_allocate;
4920 klass->queue_redraw = clutter_actor_real_queue_redraw;
4921 klass->queue_relayout = clutter_actor_real_queue_relayout;
4922 klass->apply_transform = clutter_actor_real_apply_transform;
4923 klass->get_accessible = clutter_actor_real_get_accessible;
4924 klass->get_paint_volume = clutter_actor_real_get_paint_volume;
4925 klass->has_overlaps = clutter_actor_real_has_overlaps;
4926 klass->paint = clutter_actor_real_paint;
4927 klass->destroy = clutter_actor_real_destroy;
4929 g_type_class_add_private (klass, sizeof (ClutterActorPrivate));
4934 * X coordinate of the actor in pixels. If written, forces a fixed
4935 * position for the actor. If read, returns the fixed position if any,
4936 * otherwise the allocation if available, otherwise 0.
4939 g_param_spec_float ("x",
4941 P_("X coordinate of the actor"),
4942 -G_MAXFLOAT, G_MAXFLOAT,
4944 CLUTTER_PARAM_READWRITE);
4949 * Y coordinate of the actor in pixels. If written, forces a fixed
4950 * position for the actor. If read, returns the fixed position if
4951 * any, otherwise the allocation if available, otherwise 0.
4954 g_param_spec_float ("y",
4956 P_("Y coordinate of the actor"),
4957 -G_MAXFLOAT, G_MAXFLOAT,
4959 CLUTTER_PARAM_READWRITE);
4962 * ClutterActor:width:
4964 * Width of the actor (in pixels). If written, forces the minimum and
4965 * natural size request of the actor to the given width. If read, returns
4966 * the allocated width if available, otherwise the width request.
4968 obj_props[PROP_WIDTH] =
4969 g_param_spec_float ("width",
4971 P_("Width of the actor"),
4974 CLUTTER_PARAM_READWRITE);
4977 * ClutterActor:height:
4979 * Height of the actor (in pixels). If written, forces the minimum and
4980 * natural size request of the actor to the given height. If read, returns
4981 * the allocated height if available, otherwise the height request.
4983 obj_props[PROP_HEIGHT] =
4984 g_param_spec_float ("height",
4986 P_("Height of the actor"),
4989 CLUTTER_PARAM_READWRITE);
4992 * ClutterActor:fixed-x:
4994 * The fixed X position of the actor in pixels.
4996 * Writing this property sets #ClutterActor:fixed-position-set
4997 * property as well, as a side effect
5001 obj_props[PROP_FIXED_X] =
5002 g_param_spec_float ("fixed-x",
5004 P_("Forced X position of the actor"),
5005 -G_MAXFLOAT, G_MAXFLOAT,
5007 CLUTTER_PARAM_READWRITE);
5010 * ClutterActor:fixed-y:
5012 * The fixed Y position of the actor in pixels.
5014 * Writing this property sets the #ClutterActor:fixed-position-set
5015 * property as well, as a side effect
5019 obj_props[PROP_FIXED_Y] =
5020 g_param_spec_float ("fixed-y",
5022 P_("Forced Y position of the actor"),
5023 -G_MAXFLOAT, G_MAXFLOAT,
5025 CLUTTER_PARAM_READWRITE);
5028 * ClutterActor:fixed-position-set:
5030 * This flag controls whether the #ClutterActor:fixed-x and
5031 * #ClutterActor:fixed-y properties are used
5035 obj_props[PROP_FIXED_POSITION_SET] =
5036 g_param_spec_boolean ("fixed-position-set",
5037 P_("Fixed position set"),
5038 P_("Whether to use fixed positioning for the actor"),
5040 CLUTTER_PARAM_READWRITE);
5043 * ClutterActor:min-width:
5045 * A forced minimum width request for the actor, in pixels
5047 * Writing this property sets the #ClutterActor:min-width-set property
5048 * as well, as a side effect.
5050 *This property overrides the usual width request of the actor.
5054 obj_props[PROP_MIN_WIDTH] =
5055 g_param_spec_float ("min-width",
5057 P_("Forced minimum width request for the actor"),
5060 CLUTTER_PARAM_READWRITE);
5063 * ClutterActor:min-height:
5065 * A forced minimum height request for the actor, in pixels
5067 * Writing this property sets the #ClutterActor:min-height-set property
5068 * as well, as a side effect. This property overrides the usual height
5069 * request of the actor.
5073 obj_props[PROP_MIN_HEIGHT] =
5074 g_param_spec_float ("min-height",
5076 P_("Forced minimum height request for the actor"),
5079 CLUTTER_PARAM_READWRITE);
5082 * ClutterActor:natural-width:
5084 * A forced natural width request for the actor, in pixels
5086 * Writing this property sets the #ClutterActor:natural-width-set
5087 * property as well, as a side effect. This property overrides the
5088 * usual width request of the actor
5092 obj_props[PROP_NATURAL_WIDTH] =
5093 g_param_spec_float ("natural-width",
5094 P_("Natural Width"),
5095 P_("Forced natural width request for the actor"),
5098 CLUTTER_PARAM_READWRITE);
5101 * ClutterActor:natural-height:
5103 * A forced natural height request for the actor, in pixels
5105 * Writing this property sets the #ClutterActor:natural-height-set
5106 * property as well, as a side effect. This property overrides the
5107 * usual height request of the actor
5111 obj_props[PROP_NATURAL_HEIGHT] =
5112 g_param_spec_float ("natural-height",
5113 P_("Natural Height"),
5114 P_("Forced natural height request for the actor"),
5117 CLUTTER_PARAM_READWRITE);
5120 * ClutterActor:min-width-set:
5122 * This flag controls whether the #ClutterActor:min-width property
5127 obj_props[PROP_MIN_WIDTH_SET] =
5128 g_param_spec_boolean ("min-width-set",
5129 P_("Minimum width set"),
5130 P_("Whether to use the min-width property"),
5132 CLUTTER_PARAM_READWRITE);
5135 * ClutterActor:min-height-set:
5137 * This flag controls whether the #ClutterActor:min-height property
5142 obj_props[PROP_MIN_HEIGHT_SET] =
5143 g_param_spec_boolean ("min-height-set",
5144 P_("Minimum height set"),
5145 P_("Whether to use the min-height property"),
5147 CLUTTER_PARAM_READWRITE);
5150 * ClutterActor:natural-width-set:
5152 * This flag controls whether the #ClutterActor:natural-width property
5157 obj_props[PROP_NATURAL_WIDTH_SET] =
5158 g_param_spec_boolean ("natural-width-set",
5159 P_("Natural width set"),
5160 P_("Whether to use the natural-width property"),
5162 CLUTTER_PARAM_READWRITE);
5165 * ClutterActor:natural-height-set:
5167 * This flag controls whether the #ClutterActor:natural-height property
5172 obj_props[PROP_NATURAL_HEIGHT_SET] =
5173 g_param_spec_boolean ("natural-height-set",
5174 P_("Natural height set"),
5175 P_("Whether to use the natural-height property"),
5177 CLUTTER_PARAM_READWRITE);
5180 * ClutterActor:allocation:
5182 * The allocation for the actor, in pixels
5184 * This is property is read-only, but you might monitor it to know when an
5185 * actor moves or resizes
5189 obj_props[PROP_ALLOCATION] =
5190 g_param_spec_boxed ("allocation",
5192 P_("The actor's allocation"),
5193 CLUTTER_TYPE_ACTOR_BOX,
5194 CLUTTER_PARAM_READABLE);
5197 * ClutterActor:request-mode:
5199 * Request mode for the #ClutterActor. The request mode determines the
5200 * type of geometry management used by the actor, either height for width
5201 * (the default) or width for height.
5203 * For actors implementing height for width, the parent container should get
5204 * the preferred width first, and then the preferred height for that width.
5206 * For actors implementing width for height, the parent container should get
5207 * the preferred height first, and then the preferred width for that height.
5212 * ClutterRequestMode mode;
5213 * gfloat natural_width, min_width;
5214 * gfloat natural_height, min_height;
5216 * mode = clutter_actor_get_request_mode (child);
5217 * if (mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
5219 * clutter_actor_get_preferred_width (child, -1,
5221 * &natural_width);
5222 * clutter_actor_get_preferred_height (child, natural_width,
5224 * &natural_height);
5228 * clutter_actor_get_preferred_height (child, -1,
5230 * &natural_height);
5231 * clutter_actor_get_preferred_width (child, natural_height,
5233 * &natural_width);
5237 * will retrieve the minimum and natural width and height depending on the
5238 * preferred request mode of the #ClutterActor "child".
5240 * The clutter_actor_get_preferred_size() function will implement this
5245 obj_props[PROP_REQUEST_MODE] =
5246 g_param_spec_enum ("request-mode",
5248 P_("The actor's request mode"),
5249 CLUTTER_TYPE_REQUEST_MODE,
5250 CLUTTER_REQUEST_HEIGHT_FOR_WIDTH,
5251 CLUTTER_PARAM_READWRITE);
5254 * ClutterActor:depth:
5256 * The position of the actor on the Z axis
5260 obj_props[PROP_DEPTH] =
5261 g_param_spec_float ("depth",
5263 P_("Position on the Z axis"),
5264 -G_MAXFLOAT, G_MAXFLOAT,
5266 CLUTTER_PARAM_READWRITE);
5269 * ClutterActor:opacity:
5271 * Opacity of an actor, between 0 (fully transparent) and
5272 * 255 (fully opaque)
5274 obj_props[PROP_OPACITY] =
5275 g_param_spec_uint ("opacity",
5277 P_("Opacity of an actor"),
5280 CLUTTER_PARAM_READWRITE);
5283 * ClutterActor:offscreen-redirect:
5285 * Determines the conditions in which the actor will be redirected
5286 * to an offscreen framebuffer while being painted. For example this
5287 * can be used to cache an actor in a framebuffer or for improved
5288 * handling of transparent actors. See
5289 * clutter_actor_set_offscreen_redirect() for details.
5293 obj_props[PROP_OFFSCREEN_REDIRECT] =
5294 g_param_spec_flags ("offscreen-redirect",
5295 P_("Offscreen redirect"),
5296 P_("Flags controlling when to flatten the actor into a single image"),
5297 CLUTTER_TYPE_OFFSCREEN_REDIRECT,
5299 CLUTTER_PARAM_READWRITE);
5302 * ClutterActor:visible:
5304 * Whether the actor is set to be visible or not
5306 * See also #ClutterActor:mapped
5308 obj_props[PROP_VISIBLE] =
5309 g_param_spec_boolean ("visible",
5311 P_("Whether the actor is visible or not"),
5313 CLUTTER_PARAM_READWRITE);
5316 * ClutterActor:mapped:
5318 * Whether the actor is mapped (will be painted when the stage
5319 * to which it belongs is mapped)
5323 obj_props[PROP_MAPPED] =
5324 g_param_spec_boolean ("mapped",
5326 P_("Whether the actor will be painted"),
5328 CLUTTER_PARAM_READABLE);
5331 * ClutterActor:realized:
5333 * Whether the actor has been realized
5337 obj_props[PROP_REALIZED] =
5338 g_param_spec_boolean ("realized",
5340 P_("Whether the actor has been realized"),
5342 CLUTTER_PARAM_READABLE);
5345 * ClutterActor:reactive:
5347 * Whether the actor is reactive to events or not
5349 * Only reactive actors will emit event-related signals
5353 obj_props[PROP_REACTIVE] =
5354 g_param_spec_boolean ("reactive",
5356 P_("Whether the actor is reactive to events"),
5358 CLUTTER_PARAM_READWRITE);
5361 * ClutterActor:has-clip:
5363 * Whether the actor has the #ClutterActor:clip property set or not
5365 obj_props[PROP_HAS_CLIP] =
5366 g_param_spec_boolean ("has-clip",
5368 P_("Whether the actor has a clip set"),
5370 CLUTTER_PARAM_READABLE);
5373 * ClutterActor:clip:
5375 * The clip region for the actor, in actor-relative coordinates
5377 * Every part of the actor outside the clip region will not be
5380 obj_props[PROP_CLIP] =
5381 g_param_spec_boxed ("clip",
5383 P_("The clip region for the actor"),
5384 CLUTTER_TYPE_GEOMETRY,
5385 CLUTTER_PARAM_READWRITE);
5388 * ClutterActor:name:
5390 * The name of the actor
5394 obj_props[PROP_NAME] =
5395 g_param_spec_string ("name",
5397 P_("Name of the actor"),
5399 CLUTTER_PARAM_READWRITE);
5402 * ClutterActor:scale-x:
5404 * The horizontal scale of the actor
5408 obj_props[PROP_SCALE_X] =
5409 g_param_spec_double ("scale-x",
5411 P_("Scale factor on the X axis"),
5414 CLUTTER_PARAM_READWRITE);
5417 * ClutterActor:scale-y:
5419 * The vertical scale of the actor
5423 obj_props[PROP_SCALE_Y] =
5424 g_param_spec_double ("scale-y",
5426 P_("Scale factor on the Y axis"),
5429 CLUTTER_PARAM_READWRITE);
5432 * ClutterActor:scale-center-x:
5434 * The horizontal center point for scaling
5438 obj_props[PROP_SCALE_CENTER_X] =
5439 g_param_spec_float ("scale-center-x",
5440 P_("Scale Center X"),
5441 P_("Horizontal scale center"),
5442 -G_MAXFLOAT, G_MAXFLOAT,
5444 CLUTTER_PARAM_READWRITE);
5447 * ClutterActor:scale-center-y:
5449 * The vertical center point for scaling
5453 obj_props[PROP_SCALE_CENTER_Y] =
5454 g_param_spec_float ("scale-center-y",
5455 P_("Scale Center Y"),
5456 P_("Vertical scale center"),
5457 -G_MAXFLOAT, G_MAXFLOAT,
5459 CLUTTER_PARAM_READWRITE);
5462 * ClutterActor:scale-gravity:
5464 * The center point for scaling expressed as a #ClutterGravity
5468 obj_props[PROP_SCALE_GRAVITY] =
5469 g_param_spec_enum ("scale-gravity",
5470 P_("Scale Gravity"),
5471 P_("The center of scaling"),
5472 CLUTTER_TYPE_GRAVITY,
5473 CLUTTER_GRAVITY_NONE,
5474 CLUTTER_PARAM_READWRITE);
5477 * ClutterActor:rotation-angle-x:
5479 * The rotation angle on the X axis
5483 obj_props[PROP_ROTATION_ANGLE_X] =
5484 g_param_spec_double ("rotation-angle-x",
5485 P_("Rotation Angle X"),
5486 P_("The rotation angle on the X axis"),
5487 -G_MAXDOUBLE, G_MAXDOUBLE,
5489 CLUTTER_PARAM_READWRITE);
5492 * ClutterActor:rotation-angle-y:
5494 * The rotation angle on the Y axis
5498 obj_props[PROP_ROTATION_ANGLE_Y] =
5499 g_param_spec_double ("rotation-angle-y",
5500 P_("Rotation Angle Y"),
5501 P_("The rotation angle on the Y axis"),
5502 -G_MAXDOUBLE, G_MAXDOUBLE,
5504 CLUTTER_PARAM_READWRITE);
5507 * ClutterActor:rotation-angle-z:
5509 * The rotation angle on the Z axis
5513 obj_props[PROP_ROTATION_ANGLE_Z] =
5514 g_param_spec_double ("rotation-angle-z",
5515 P_("Rotation Angle Z"),
5516 P_("The rotation angle on the Z axis"),
5517 -G_MAXDOUBLE, G_MAXDOUBLE,
5519 CLUTTER_PARAM_READWRITE);
5522 * ClutterActor:rotation-center-x:
5524 * The rotation center on the X axis.
5528 obj_props[PROP_ROTATION_CENTER_X] =
5529 g_param_spec_boxed ("rotation-center-x",
5530 P_("Rotation Center X"),
5531 P_("The rotation center on the X axis"),
5532 CLUTTER_TYPE_VERTEX,
5533 CLUTTER_PARAM_READWRITE);
5536 * ClutterActor:rotation-center-y:
5538 * The rotation center on the Y axis.
5542 obj_props[PROP_ROTATION_CENTER_Y] =
5543 g_param_spec_boxed ("rotation-center-y",
5544 P_("Rotation Center Y"),
5545 P_("The rotation center on the Y axis"),
5546 CLUTTER_TYPE_VERTEX,
5547 CLUTTER_PARAM_READWRITE);
5550 * ClutterActor:rotation-center-z:
5552 * The rotation center on the Z axis.
5556 obj_props[PROP_ROTATION_CENTER_Z] =
5557 g_param_spec_boxed ("rotation-center-z",
5558 P_("Rotation Center Z"),
5559 P_("The rotation center on the Z axis"),
5560 CLUTTER_TYPE_VERTEX,
5561 CLUTTER_PARAM_READWRITE);
5564 * ClutterActor:rotation-center-z-gravity:
5566 * The rotation center on the Z axis expressed as a #ClutterGravity.
5570 obj_props[PROP_ROTATION_CENTER_Z_GRAVITY] =
5571 g_param_spec_enum ("rotation-center-z-gravity",
5572 P_("Rotation Center Z Gravity"),
5573 P_("Center point for rotation around the Z axis"),
5574 CLUTTER_TYPE_GRAVITY,
5575 CLUTTER_GRAVITY_NONE,
5576 CLUTTER_PARAM_READWRITE);
5579 * ClutterActor:anchor-x:
5581 * The X coordinate of an actor's anchor point, relative to
5582 * the actor coordinate space, in pixels
5586 obj_props[PROP_ANCHOR_X] =
5587 g_param_spec_float ("anchor-x",
5589 P_("X coordinate of the anchor point"),
5590 -G_MAXFLOAT, G_MAXFLOAT,
5592 CLUTTER_PARAM_READWRITE);
5595 * ClutterActor:anchor-y:
5597 * The Y coordinate of an actor's anchor point, relative to
5598 * the actor coordinate space, in pixels
5602 obj_props[PROP_ANCHOR_Y] =
5603 g_param_spec_float ("anchor-y",
5605 P_("Y coordinate of the anchor point"),
5606 -G_MAXFLOAT, G_MAXFLOAT,
5608 CLUTTER_PARAM_READWRITE);
5611 * ClutterActor:anchor-gravity:
5613 * The anchor point expressed as a #ClutterGravity
5617 obj_props[PROP_ANCHOR_GRAVITY] =
5618 g_param_spec_enum ("anchor-gravity",
5619 P_("Anchor Gravity"),
5620 P_("The anchor point as a ClutterGravity"),
5621 CLUTTER_TYPE_GRAVITY,
5622 CLUTTER_GRAVITY_NONE,
5623 CLUTTER_PARAM_READWRITE);
5626 * ClutterActor:show-on-set-parent:
5628 * If %TRUE, the actor is automatically shown when parented.
5630 * Calling clutter_actor_hide() on an actor which has not been
5631 * parented will set this property to %FALSE as a side effect.
5635 obj_props[PROP_SHOW_ON_SET_PARENT] =
5636 g_param_spec_boolean ("show-on-set-parent",
5637 P_("Show on set parent"),
5638 P_("Whether the actor is shown when parented"),
5640 CLUTTER_PARAM_READWRITE);
5643 * ClutterActor:clip-to-allocation:
5645 * Whether the clip region should track the allocated area
5648 * This property is ignored if a clip area has been explicitly
5649 * set using clutter_actor_set_clip().
5653 obj_props[PROP_CLIP_TO_ALLOCATION] =
5654 g_param_spec_boolean ("clip-to-allocation",
5655 P_("Clip to Allocation"),
5656 P_("Sets the clip region to track the actor's allocation"),
5658 CLUTTER_PARAM_READWRITE);
5661 * ClutterActor:text-direction:
5663 * The direction of the text inside a #ClutterActor.
5667 obj_props[PROP_TEXT_DIRECTION] =
5668 g_param_spec_enum ("text-direction",
5669 P_("Text Direction"),
5670 P_("Direction of the text"),
5671 CLUTTER_TYPE_TEXT_DIRECTION,
5672 CLUTTER_TEXT_DIRECTION_LTR,
5673 CLUTTER_PARAM_READWRITE);
5676 * ClutterActor:has-pointer:
5678 * Whether the actor contains the pointer of a #ClutterInputDevice
5683 obj_props[PROP_HAS_POINTER] =
5684 g_param_spec_boolean ("has-pointer",
5686 P_("Whether the actor contains the pointer of an input device"),
5688 CLUTTER_PARAM_READABLE);
5691 * ClutterActor:actions:
5693 * Adds a #ClutterAction to the actor
5697 obj_props[PROP_ACTIONS] =
5698 g_param_spec_object ("actions",
5700 P_("Adds an action to the actor"),
5701 CLUTTER_TYPE_ACTION,
5702 CLUTTER_PARAM_WRITABLE);
5705 * ClutterActor:constraints:
5707 * Adds a #ClutterConstraint to the actor
5711 obj_props[PROP_CONSTRAINTS] =
5712 g_param_spec_object ("constraints",
5714 P_("Adds a constraint to the actor"),
5715 CLUTTER_TYPE_CONSTRAINT,
5716 CLUTTER_PARAM_WRITABLE);
5719 * ClutterActor:effect:
5721 * Adds #ClutterEffect to the list of effects be applied on a #ClutterActor
5725 obj_props[PROP_EFFECT] =
5726 g_param_spec_object ("effect",
5728 P_("Add an effect to be applied on the actor"),
5729 CLUTTER_TYPE_EFFECT,
5730 CLUTTER_PARAM_WRITABLE);
5733 * ClutterActor:layout-manager:
5735 * A delegate object for controlling the layout of the children of
5740 obj_props[PROP_LAYOUT_MANAGER] =
5741 g_param_spec_object ("layout-manager",
5742 P_("Layout Manager"),
5743 P_("The object controlling the layout of an actor's children"),
5744 CLUTTER_TYPE_LAYOUT_MANAGER,
5745 CLUTTER_PARAM_READWRITE);
5749 * ClutterActor:x-align:
5751 * The alignment of an actor on the X axis, if the actor has been given
5752 * extra space for its allocation.
5756 obj_props[PROP_X_ALIGN] =
5757 g_param_spec_enum ("x-align",
5759 P_("The alignment of the actor on the X axis within its allocation"),
5760 CLUTTER_TYPE_ACTOR_ALIGN,
5761 CLUTTER_ACTOR_ALIGN_FILL,
5762 CLUTTER_PARAM_READWRITE);
5765 * ClutterActor:y-align:
5767 * The alignment of an actor on the Y axis, if the actor has been given
5768 * extra space for its allocation.
5772 obj_props[PROP_Y_ALIGN] =
5773 g_param_spec_enum ("y-align",
5775 P_("The alignment of the actor on the Y axis within its allocation"),
5776 CLUTTER_TYPE_ACTOR_ALIGN,
5777 CLUTTER_ACTOR_ALIGN_FILL,
5778 CLUTTER_PARAM_READWRITE);
5781 * ClutterActor:margin-top:
5783 * The margin (in pixels) from the top of the actor.
5785 * This property adds a margin to the actor's preferred size; the margin
5786 * will be automatically taken into account when allocating the actor.
5790 obj_props[PROP_MARGIN_TOP] =
5791 g_param_spec_float ("margin-top",
5793 P_("Extra space at the top"),
5796 CLUTTER_PARAM_READWRITE);
5799 * ClutterActor:margin-bottom:
5801 * The margin (in pixels) from the bottom of the actor.
5803 * This property adds a margin to the actor's preferred size; the margin
5804 * will be automatically taken into account when allocating the actor.
5808 obj_props[PROP_MARGIN_BOTTOM] =
5809 g_param_spec_float ("margin-bottom",
5810 P_("Margin Bottom"),
5811 P_("Extra space at the bottom"),
5814 CLUTTER_PARAM_READWRITE);
5817 * ClutterActor:margin-left:
5819 * The margin (in pixels) from the left of the actor.
5821 * This property adds a margin to the actor's preferred size; the margin
5822 * will be automatically taken into account when allocating the actor.
5826 obj_props[PROP_MARGIN_LEFT] =
5827 g_param_spec_float ("margin-left",
5829 P_("Extra space at the left"),
5832 CLUTTER_PARAM_READWRITE);
5835 * ClutterActor:margin-right:
5837 * The margin (in pixels) from the right of the actor.
5839 * This property adds a margin to the actor's preferred size; the margin
5840 * will be automatically taken into account when allocating the actor.
5844 obj_props[PROP_MARGIN_RIGHT] =
5845 g_param_spec_float ("margin-right",
5847 P_("Extra space at the right"),
5850 CLUTTER_PARAM_READWRITE);
5853 * ClutterActor:background-color-set:
5855 * Whether the #ClutterActor:background-color property has been set.
5859 obj_props[PROP_BACKGROUND_COLOR_SET] =
5860 g_param_spec_boolean ("background-color-set",
5861 P_("Background Color Set"),
5862 P_("Whether the background color is set"),
5864 CLUTTER_PARAM_READABLE);
5867 * ClutterActor:background-color:
5869 * Paints a solid fill of the actor's allocation using the specified
5874 obj_props[PROP_BACKGROUND_COLOR] =
5875 clutter_param_spec_color ("background-color",
5876 P_("Background color"),
5877 P_("The actor's background color"),
5878 CLUTTER_COLOR_Transparent,
5879 CLUTTER_PARAM_READWRITE);
5882 * ClutterActor:first-child:
5884 * The actor's first child.
5888 obj_props[PROP_FIRST_CHILD] =
5889 g_param_spec_object ("first-child",
5891 P_("The actor's first child"),
5893 CLUTTER_PARAM_READABLE);
5896 * ClutterActor:last-child:
5898 * The actor's last child.
5902 obj_props[PROP_LAST_CHILD] =
5903 g_param_spec_object ("last-child",
5905 P_("The actor's last child"),
5907 CLUTTER_PARAM_READABLE);
5909 g_object_class_install_properties (object_class, PROP_LAST, obj_props);
5912 * ClutterActor::destroy:
5913 * @actor: the #ClutterActor which emitted the signal
5915 * The ::destroy signal notifies that all references held on the
5916 * actor which emitted it should be released.
5918 * The ::destroy signal should be used by all holders of a reference
5921 * This signal might result in the finalization of the #ClutterActor
5922 * if all references are released.
5924 * Composite actors and actors implementing the #ClutterContainer
5925 * interface should override the default implementation of the
5926 * class handler of this signal and call clutter_actor_destroy() on
5927 * their children. When overriding the default class handler, it is
5928 * required to chain up to the parent's implementation.
5932 actor_signals[DESTROY] =
5933 g_signal_new (I_("destroy"),
5934 G_TYPE_FROM_CLASS (object_class),
5935 G_SIGNAL_RUN_CLEANUP | G_SIGNAL_NO_RECURSE | G_SIGNAL_NO_HOOKS,
5936 G_STRUCT_OFFSET (ClutterActorClass, destroy),
5938 _clutter_marshal_VOID__VOID,
5941 * ClutterActor::show:
5942 * @actor: the object which received the signal
5944 * The ::show signal is emitted when an actor is visible and
5945 * rendered on the stage.
5949 actor_signals[SHOW] =
5950 g_signal_new (I_("show"),
5951 G_TYPE_FROM_CLASS (object_class),
5953 G_STRUCT_OFFSET (ClutterActorClass, show),
5955 _clutter_marshal_VOID__VOID,
5958 * ClutterActor::hide:
5959 * @actor: the object which received the signal
5961 * The ::hide signal is emitted when an actor is no longer rendered
5966 actor_signals[HIDE] =
5967 g_signal_new (I_("hide"),
5968 G_TYPE_FROM_CLASS (object_class),
5970 G_STRUCT_OFFSET (ClutterActorClass, hide),
5972 _clutter_marshal_VOID__VOID,
5975 * ClutterActor::parent-set:
5976 * @actor: the object which received the signal
5977 * @old_parent: (allow-none): the previous parent of the actor, or %NULL
5979 * This signal is emitted when the parent of the actor changes.
5983 actor_signals[PARENT_SET] =
5984 g_signal_new (I_("parent-set"),
5985 G_TYPE_FROM_CLASS (object_class),
5987 G_STRUCT_OFFSET (ClutterActorClass, parent_set),
5989 _clutter_marshal_VOID__OBJECT,
5991 CLUTTER_TYPE_ACTOR);
5994 * ClutterActor::queue-redraw:
5995 * @actor: the actor we're bubbling the redraw request through
5996 * @origin: the actor which initiated the redraw request
5998 * The ::queue_redraw signal is emitted when clutter_actor_queue_redraw()
5999 * is called on @origin.
6001 * The default implementation for #ClutterActor chains up to the
6002 * parent actor and queues a redraw on the parent, thus "bubbling"
6003 * the redraw queue up through the actor graph. The default
6004 * implementation for #ClutterStage queues a clutter_stage_ensure_redraw()
6005 * in a main loop idle handler.
6007 * Note that the @origin actor may be the stage, or a container; it
6008 * does not have to be a leaf node in the actor graph.
6010 * Toolkits embedding a #ClutterStage which require a redraw and
6011 * relayout cycle can stop the emission of this signal using the
6012 * GSignal API, redraw the UI and then call clutter_stage_ensure_redraw()
6017 * on_redraw_complete (gpointer data)
6019 * ClutterStage *stage = data;
6021 * /* execute the Clutter drawing pipeline */
6022 * clutter_stage_ensure_redraw (stage);
6026 * on_stage_queue_redraw (ClutterStage *stage)
6028 * /* this prevents the default handler to run */
6029 * g_signal_stop_emission_by_name (stage, "queue-redraw");
6031 * /* queue a redraw with the host toolkit and call
6032 * * a function when the redraw has been completed
6034 * queue_a_redraw (G_CALLBACK (on_redraw_complete), stage);
6038 * <note><para>This signal is emitted before the Clutter paint
6039 * pipeline is executed. If you want to know when the pipeline has
6040 * been completed you should connect to the ::paint signal on the
6041 * Stage with g_signal_connect_after().</para></note>
6045 actor_signals[QUEUE_REDRAW] =
6046 g_signal_new (I_("queue-redraw"),
6047 G_TYPE_FROM_CLASS (object_class),
6049 G_SIGNAL_NO_RECURSE |
6051 G_STRUCT_OFFSET (ClutterActorClass, queue_redraw),
6053 _clutter_marshal_VOID__OBJECT,
6055 CLUTTER_TYPE_ACTOR);
6058 * ClutterActor::queue-relayout
6059 * @actor: the actor being queued for relayout
6061 * The ::queue_layout signal is emitted when clutter_actor_queue_relayout()
6062 * is called on an actor.
6064 * The default implementation for #ClutterActor chains up to the
6065 * parent actor and queues a relayout on the parent, thus "bubbling"
6066 * the relayout queue up through the actor graph.
6068 * The main purpose of this signal is to allow relayout to be propagated
6069 * properly in the procense of #ClutterClone actors. Applications will
6070 * not normally need to connect to this signal.
6074 actor_signals[QUEUE_RELAYOUT] =
6075 g_signal_new (I_("queue-relayout"),
6076 G_TYPE_FROM_CLASS (object_class),
6078 G_SIGNAL_NO_RECURSE |
6080 G_STRUCT_OFFSET (ClutterActorClass, queue_relayout),
6082 _clutter_marshal_VOID__VOID,
6086 * ClutterActor::event:
6087 * @actor: the actor which received the event
6088 * @event: a #ClutterEvent
6090 * The ::event signal is emitted each time an event is received
6091 * by the @actor. This signal will be emitted on every actor,
6092 * following the hierarchy chain, until it reaches the top-level
6093 * container (the #ClutterStage).
6095 * Return value: %TRUE if the event has been handled by the actor,
6096 * or %FALSE to continue the emission.
6100 actor_signals[EVENT] =
6101 g_signal_new (I_("event"),
6102 G_TYPE_FROM_CLASS (object_class),
6104 G_STRUCT_OFFSET (ClutterActorClass, event),
6105 _clutter_boolean_handled_accumulator, NULL,
6106 _clutter_marshal_BOOLEAN__BOXED,
6108 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6110 * ClutterActor::button-press-event:
6111 * @actor: the actor which received the event
6112 * @event: (type ClutterButtonEvent): a #ClutterButtonEvent
6114 * The ::button-press-event signal is emitted each time a mouse button
6115 * is pressed on @actor.
6117 * Return value: %TRUE if the event has been handled by the actor,
6118 * or %FALSE to continue the emission.
6122 actor_signals[BUTTON_PRESS_EVENT] =
6123 g_signal_new (I_("button-press-event"),
6124 G_TYPE_FROM_CLASS (object_class),
6126 G_STRUCT_OFFSET (ClutterActorClass, button_press_event),
6127 _clutter_boolean_handled_accumulator, NULL,
6128 _clutter_marshal_BOOLEAN__BOXED,
6130 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6132 * ClutterActor::button-release-event:
6133 * @actor: the actor which received the event
6134 * @event: (type ClutterButtonEvent): a #ClutterButtonEvent
6136 * The ::button-release-event signal is emitted each time a mouse button
6137 * is released on @actor.
6139 * Return value: %TRUE if the event has been handled by the actor,
6140 * or %FALSE to continue the emission.
6144 actor_signals[BUTTON_RELEASE_EVENT] =
6145 g_signal_new (I_("button-release-event"),
6146 G_TYPE_FROM_CLASS (object_class),
6148 G_STRUCT_OFFSET (ClutterActorClass, button_release_event),
6149 _clutter_boolean_handled_accumulator, NULL,
6150 _clutter_marshal_BOOLEAN__BOXED,
6152 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6154 * ClutterActor::scroll-event:
6155 * @actor: the actor which received the event
6156 * @event: (type ClutterScrollEvent): a #ClutterScrollEvent
6158 * The ::scroll-event signal is emitted each time the mouse is
6159 * scrolled on @actor
6161 * Return value: %TRUE if the event has been handled by the actor,
6162 * or %FALSE to continue the emission.
6166 actor_signals[SCROLL_EVENT] =
6167 g_signal_new (I_("scroll-event"),
6168 G_TYPE_FROM_CLASS (object_class),
6170 G_STRUCT_OFFSET (ClutterActorClass, scroll_event),
6171 _clutter_boolean_handled_accumulator, NULL,
6172 _clutter_marshal_BOOLEAN__BOXED,
6174 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6176 * ClutterActor::key-press-event:
6177 * @actor: the actor which received the event
6178 * @event: (type ClutterKeyEvent): a #ClutterKeyEvent
6180 * The ::key-press-event signal is emitted each time a keyboard button
6181 * is pressed while @actor has key focus (see clutter_stage_set_key_focus()).
6183 * Return value: %TRUE if the event has been handled by the actor,
6184 * or %FALSE to continue the emission.
6188 actor_signals[KEY_PRESS_EVENT] =
6189 g_signal_new (I_("key-press-event"),
6190 G_TYPE_FROM_CLASS (object_class),
6192 G_STRUCT_OFFSET (ClutterActorClass, key_press_event),
6193 _clutter_boolean_handled_accumulator, NULL,
6194 _clutter_marshal_BOOLEAN__BOXED,
6196 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6198 * ClutterActor::key-release-event:
6199 * @actor: the actor which received the event
6200 * @event: (type ClutterKeyEvent): a #ClutterKeyEvent
6202 * The ::key-release-event signal is emitted each time a keyboard button
6203 * is released while @actor has key focus (see
6204 * clutter_stage_set_key_focus()).
6206 * Return value: %TRUE if the event has been handled by the actor,
6207 * or %FALSE to continue the emission.
6211 actor_signals[KEY_RELEASE_EVENT] =
6212 g_signal_new (I_("key-release-event"),
6213 G_TYPE_FROM_CLASS (object_class),
6215 G_STRUCT_OFFSET (ClutterActorClass, key_release_event),
6216 _clutter_boolean_handled_accumulator, NULL,
6217 _clutter_marshal_BOOLEAN__BOXED,
6219 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6221 * ClutterActor::motion-event:
6222 * @actor: the actor which received the event
6223 * @event: (type ClutterMotionEvent): a #ClutterMotionEvent
6225 * The ::motion-event signal is emitted each time the mouse pointer is
6226 * moved over @actor.
6228 * Return value: %TRUE if the event has been handled by the actor,
6229 * or %FALSE to continue the emission.
6233 actor_signals[MOTION_EVENT] =
6234 g_signal_new (I_("motion-event"),
6235 G_TYPE_FROM_CLASS (object_class),
6237 G_STRUCT_OFFSET (ClutterActorClass, motion_event),
6238 _clutter_boolean_handled_accumulator, NULL,
6239 _clutter_marshal_BOOLEAN__BOXED,
6241 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6244 * ClutterActor::key-focus-in:
6245 * @actor: the actor which now has key focus
6247 * The ::key-focus-in signal is emitted when @actor receives key focus.
6251 actor_signals[KEY_FOCUS_IN] =
6252 g_signal_new (I_("key-focus-in"),
6253 G_TYPE_FROM_CLASS (object_class),
6255 G_STRUCT_OFFSET (ClutterActorClass, key_focus_in),
6257 _clutter_marshal_VOID__VOID,
6261 * ClutterActor::key-focus-out:
6262 * @actor: the actor which now has key focus
6264 * The ::key-focus-out signal is emitted when @actor loses key focus.
6268 actor_signals[KEY_FOCUS_OUT] =
6269 g_signal_new (I_("key-focus-out"),
6270 G_TYPE_FROM_CLASS (object_class),
6272 G_STRUCT_OFFSET (ClutterActorClass, key_focus_out),
6274 _clutter_marshal_VOID__VOID,
6278 * ClutterActor::enter-event:
6279 * @actor: the actor which the pointer has entered.
6280 * @event: (type ClutterCrossingEvent): a #ClutterCrossingEvent
6282 * The ::enter-event signal is emitted when the pointer enters the @actor
6284 * Return value: %TRUE if the event has been handled by the actor,
6285 * or %FALSE to continue the emission.
6289 actor_signals[ENTER_EVENT] =
6290 g_signal_new (I_("enter-event"),
6291 G_TYPE_FROM_CLASS (object_class),
6293 G_STRUCT_OFFSET (ClutterActorClass, enter_event),
6294 _clutter_boolean_handled_accumulator, NULL,
6295 _clutter_marshal_BOOLEAN__BOXED,
6297 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6300 * ClutterActor::leave-event:
6301 * @actor: the actor which the pointer has left
6302 * @event: (type ClutterCrossingEvent): a #ClutterCrossingEvent
6304 * The ::leave-event signal is emitted when the pointer leaves the @actor.
6306 * Return value: %TRUE if the event has been handled by the actor,
6307 * or %FALSE to continue the emission.
6311 actor_signals[LEAVE_EVENT] =
6312 g_signal_new (I_("leave-event"),
6313 G_TYPE_FROM_CLASS (object_class),
6315 G_STRUCT_OFFSET (ClutterActorClass, leave_event),
6316 _clutter_boolean_handled_accumulator, NULL,
6317 _clutter_marshal_BOOLEAN__BOXED,
6319 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6322 * ClutterActor::captured-event:
6323 * @actor: the actor which received the signal
6324 * @event: a #ClutterEvent
6326 * The ::captured-event signal is emitted when an event is captured
6327 * by Clutter. This signal will be emitted starting from the top-level
6328 * container (the #ClutterStage) to the actor which received the event
6329 * going down the hierarchy. This signal can be used to intercept every
6330 * event before the specialized events (like
6331 * ClutterActor::button-press-event or ::key-released-event) are
6334 * Return value: %TRUE if the event has been handled by the actor,
6335 * or %FALSE to continue the emission.
6339 actor_signals[CAPTURED_EVENT] =
6340 g_signal_new (I_("captured-event"),
6341 G_TYPE_FROM_CLASS (object_class),
6343 G_STRUCT_OFFSET (ClutterActorClass, captured_event),
6344 _clutter_boolean_handled_accumulator, NULL,
6345 _clutter_marshal_BOOLEAN__BOXED,
6347 CLUTTER_TYPE_EVENT | G_SIGNAL_TYPE_STATIC_SCOPE);
6350 * ClutterActor::paint:
6351 * @actor: the #ClutterActor that received the signal
6353 * The ::paint signal is emitted each time an actor is being painted.
6355 * Subclasses of #ClutterActor should override the class signal handler
6356 * and paint themselves in that function.
6358 * It is possible to connect a handler to the ::paint signal in order
6359 * to set up some custom aspect of a paint.
6363 actor_signals[PAINT] =
6364 g_signal_new (I_("paint"),
6365 G_TYPE_FROM_CLASS (object_class),
6367 G_SIGNAL_NO_RECURSE |
6369 G_STRUCT_OFFSET (ClutterActorClass, paint),
6371 _clutter_marshal_VOID__VOID,
6374 * ClutterActor::realize:
6375 * @actor: the #ClutterActor that received the signal
6377 * The ::realize signal is emitted each time an actor is being
6382 actor_signals[REALIZE] =
6383 g_signal_new (I_("realize"),
6384 G_TYPE_FROM_CLASS (object_class),
6386 G_STRUCT_OFFSET (ClutterActorClass, realize),
6388 _clutter_marshal_VOID__VOID,
6391 * ClutterActor::unrealize:
6392 * @actor: the #ClutterActor that received the signal
6394 * The ::unrealize signal is emitted each time an actor is being
6399 actor_signals[UNREALIZE] =
6400 g_signal_new (I_("unrealize"),
6401 G_TYPE_FROM_CLASS (object_class),
6403 G_STRUCT_OFFSET (ClutterActorClass, unrealize),
6405 _clutter_marshal_VOID__VOID,
6409 * ClutterActor::pick:
6410 * @actor: the #ClutterActor that received the signal
6411 * @color: the #ClutterColor to be used when picking
6413 * The ::pick signal is emitted each time an actor is being painted
6414 * in "pick mode". The pick mode is used to identify the actor during
6415 * the event handling phase, or by clutter_stage_get_actor_at_pos().
6416 * The actor should paint its shape using the passed @pick_color.
6418 * Subclasses of #ClutterActor should override the class signal handler
6419 * and paint themselves in that function.
6421 * It is possible to connect a handler to the ::pick signal in order
6422 * to set up some custom aspect of a paint in pick mode.
6426 actor_signals[PICK] =
6427 g_signal_new (I_("pick"),
6428 G_TYPE_FROM_CLASS (object_class),
6430 G_STRUCT_OFFSET (ClutterActorClass, pick),
6432 _clutter_marshal_VOID__BOXED,
6434 CLUTTER_TYPE_COLOR | G_SIGNAL_TYPE_STATIC_SCOPE);
6437 * ClutterActor::allocation-changed:
6438 * @actor: the #ClutterActor that emitted the signal
6439 * @box: a #ClutterActorBox with the new allocation
6440 * @flags: #ClutterAllocationFlags for the allocation
6442 * The ::allocation-changed signal is emitted when the
6443 * #ClutterActor:allocation property changes. Usually, application
6444 * code should just use the notifications for the :allocation property
6445 * but if you want to track the allocation flags as well, for instance
6446 * to know whether the absolute origin of @actor changed, then you might
6447 * want use this signal instead.
6451 actor_signals[ALLOCATION_CHANGED] =
6452 g_signal_new (I_("allocation-changed"),
6453 G_TYPE_FROM_CLASS (object_class),
6457 _clutter_marshal_VOID__BOXED_FLAGS,
6459 CLUTTER_TYPE_ACTOR_BOX | G_SIGNAL_TYPE_STATIC_SCOPE,
6460 CLUTTER_TYPE_ALLOCATION_FLAGS);
6464 clutter_actor_init (ClutterActor *self)
6466 ClutterActorPrivate *priv;
6468 self->priv = priv = CLUTTER_ACTOR_GET_PRIVATE (self);
6470 priv->id = _clutter_context_acquire_id (self);
6473 priv->opacity = 0xff;
6474 priv->show_on_set_parent = TRUE;
6476 priv->needs_width_request = TRUE;
6477 priv->needs_height_request = TRUE;
6478 priv->needs_allocation = TRUE;
6480 priv->cached_width_age = 1;
6481 priv->cached_height_age = 1;
6483 priv->opacity_override = -1;
6484 priv->enable_model_view_transform = TRUE;
6486 /* Initialize an empty paint volume to start with */
6487 _clutter_paint_volume_init_static (&priv->last_paint_volume, NULL);
6488 priv->last_paint_volume_valid = TRUE;
6490 priv->transform_valid = FALSE;
6494 * clutter_actor_new:
6496 * Creates a new #ClutterActor.
6498 * A newly created actor has a floating reference, which will be sunk
6499 * when it is added to another actor.
6501 * Return value: (transfer full): the newly created #ClutterActor
6506 clutter_actor_new (void)
6508 return g_object_new (CLUTTER_TYPE_ACTOR, NULL);
6512 * clutter_actor_destroy:
6513 * @self: a #ClutterActor
6515 * Destroys an actor. When an actor is destroyed, it will break any
6516 * references it holds to other objects. If the actor is inside a
6517 * container, the actor will be removed.
6519 * When you destroy a container, its children will be destroyed as well.
6521 * Note: you cannot destroy the #ClutterStage returned by
6522 * clutter_stage_get_default().
6525 clutter_actor_destroy (ClutterActor *self)
6527 g_return_if_fail (CLUTTER_IS_ACTOR (self));
6529 g_object_ref (self);
6531 /* avoid recursion while destroying */
6532 if (!CLUTTER_ACTOR_IN_DESTRUCTION (self))
6534 CLUTTER_SET_PRIVATE_FLAGS (self, CLUTTER_IN_DESTRUCTION);
6536 g_object_run_dispose (G_OBJECT (self));
6538 CLUTTER_UNSET_PRIVATE_FLAGS (self, CLUTTER_IN_DESTRUCTION);
6541 g_object_unref (self);
6545 _clutter_actor_finish_queue_redraw (ClutterActor *self,
6546 ClutterPaintVolume *clip)
6548 ClutterActorPrivate *priv = self->priv;
6549 ClutterPaintVolume *pv;
6552 /* Remove queue entry early in the process, otherwise a new
6553 queue_redraw() during signal handling could put back this
6554 object in the stage redraw list (but the entry is freed as
6555 soon as we return from this function, causing a segfault
6558 priv->queue_redraw_entry = NULL;
6560 /* If we've been explicitly passed a clip volume then there's
6561 * nothing more to calculate, but otherwise the only thing we know
6562 * is that the change is constrained to the given actor.
6564 * The idea is that if we know the paint volume for where the actor
6565 * was last drawn (in eye coordinates) and we also have the paint
6566 * volume for where it will be drawn next (in actor coordinates)
6567 * then if we queue a redraw for both these volumes that will cover
6568 * everything that needs to be redrawn to clear the old view and
6569 * show the latest view of the actor.
6571 * Don't clip this redraw if we don't know what position we had for
6572 * the previous redraw since we don't know where to set the clip so
6573 * it will clear the actor as it is currently.
6577 _clutter_actor_set_queue_redraw_clip (self, clip);
6580 else if (G_LIKELY (priv->last_paint_volume_valid))
6582 pv = _clutter_actor_get_paint_volume_mutable (self);
6585 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
6587 /* make sure we redraw the actors old position... */
6588 _clutter_actor_set_queue_redraw_clip (stage,
6589 &priv->last_paint_volume);
6590 _clutter_actor_signal_queue_redraw (stage, stage);
6591 _clutter_actor_set_queue_redraw_clip (stage, NULL);
6593 /* XXX: Ideally the redraw signal would take a clip volume
6594 * argument, but that would be an ABI break. Until we can
6595 * break the ABI we pass the argument out-of-band
6598 /* setup the clip for the actors new position... */
6599 _clutter_actor_set_queue_redraw_clip (self, pv);
6608 _clutter_actor_signal_queue_redraw (self, self);
6610 /* Just in case anyone is manually firing redraw signals without
6611 * using the public queue_redraw() API we are careful to ensure that
6612 * our out-of-band clip member is cleared before returning...
6614 * Note: A NULL clip denotes a full-stage, un-clipped redraw
6616 if (G_LIKELY (clipped))
6617 _clutter_actor_set_queue_redraw_clip (self, NULL);
6621 _clutter_actor_get_allocation_clip (ClutterActor *self,
6622 ClutterActorBox *clip)
6624 ClutterActorBox allocation;
6626 /* XXX: we don't care if we get an out of date allocation here
6627 * because clutter_actor_queue_redraw_with_clip knows to ignore
6628 * the clip if the actor's allocation is invalid.
6630 * This is noted because clutter_actor_get_allocation_box does some
6631 * unnecessary work to support buggy code with a comment suggesting
6632 * that it could be changed later which would be good for this use
6635 clutter_actor_get_allocation_box (self, &allocation);
6637 /* NB: clutter_actor_queue_redraw_with_clip expects a box in the
6638 * actor's own coordinate space but the allocation is in parent
6642 clip->x2 = allocation.x2 - allocation.x1;
6643 clip->y2 = allocation.y2 - allocation.y1;
6647 _clutter_actor_queue_redraw_full (ClutterActor *self,
6648 ClutterRedrawFlags flags,
6649 ClutterPaintVolume *volume,
6650 ClutterEffect *effect)
6652 ClutterActorPrivate *priv = self->priv;
6653 ClutterPaintVolume allocation_pv;
6654 ClutterPaintVolume *pv;
6655 gboolean should_free_pv;
6656 ClutterActor *stage;
6658 /* Here's an outline of the actor queue redraw mechanism:
6660 * The process starts in one of the following two functions which
6661 * are wrappers for this function:
6662 * clutter_actor_queue_redraw
6663 * _clutter_actor_queue_redraw_with_clip
6665 * additionally, an effect can queue a redraw by wrapping this
6666 * function in clutter_effect_queue_rerun
6668 * This functions queues an entry in a list associated with the
6669 * stage which is a list of actors that queued a redraw while
6670 * updating the timelines, performing layouting and processing other
6671 * mainloop sources before the next paint starts.
6673 * We aim to minimize the processing done at this point because
6674 * there is a good chance other events will happen while updating
6675 * the scenegraph that would invalidate any expensive work we might
6676 * otherwise try to do here. For example we don't try and resolve
6677 * the screen space bounding box of an actor at this stage so as to
6678 * minimize how much of the screen redraw because it's possible
6679 * something else will happen which will force a full redraw anyway.
6681 * When all updates are complete and we come to paint the stage then
6682 * we iterate this list and actually emit the "queue-redraw" signals
6683 * for each of the listed actors which will bubble up to the stage
6684 * for each actor and at that point we will transform the actors
6685 * paint volume into screen coordinates to determine the clip region
6686 * for what needs to be redrawn in the next paint.
6688 * Besides minimizing redundant work another reason for this
6689 * deferred design is that it's more likely we will be able to
6690 * determine the paint volume of an actor once we've finished
6691 * updating the scenegraph because its allocation should be up to
6692 * date. NB: If we can't determine an actors paint volume then we
6693 * can't automatically queue a clipped redraw which can make a big
6694 * difference to performance.
6696 * So the control flow goes like this:
6697 * One of clutter_actor_queue_redraw,
6698 * _clutter_actor_queue_redraw_with_clip
6699 * or clutter_effect_queue_rerun
6701 * then control moves to:
6702 * _clutter_stage_queue_actor_redraw
6704 * later during _clutter_stage_do_update, once relayouting is done
6705 * and the scenegraph has been updated we will call:
6706 * _clutter_stage_finish_queue_redraws
6708 * _clutter_stage_finish_queue_redraws will call
6709 * _clutter_actor_finish_queue_redraw for each listed actor.
6710 * Note: actors *are* allowed to queue further redraws during this
6711 * process (considering clone actors or texture_new_from_actor which
6712 * respond to their source queueing a redraw by queuing a redraw
6713 * themselves). We repeat the process until the list is empty.
6715 * This will result in the "queue-redraw" signal being fired for
6716 * each actor which will pass control to the default signal handler:
6717 * clutter_actor_real_queue_redraw
6719 * This will bubble up to the stages handler:
6720 * clutter_stage_real_queue_redraw
6722 * clutter_stage_real_queue_redraw will transform the actors paint
6723 * volume into screen space and add it as a clip region for the next
6727 /* ignore queueing a redraw for actors being destroyed */
6728 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
6731 stage = _clutter_actor_get_stage_internal (self);
6733 /* Ignore queueing a redraw for actors not descended from a stage */
6737 /* ignore queueing a redraw on stages that are being destroyed */
6738 if (CLUTTER_ACTOR_IN_DESTRUCTION (stage))
6741 if (flags & CLUTTER_REDRAW_CLIPPED_TO_ALLOCATION)
6743 ClutterActorBox allocation_clip;
6744 ClutterVertex origin;
6746 /* If the actor doesn't have a valid allocation then we will
6747 * queue a full stage redraw. */
6748 if (priv->needs_allocation)
6750 /* NB: NULL denotes an undefined clip which will result in a
6752 _clutter_actor_set_queue_redraw_clip (self, NULL);
6753 _clutter_actor_signal_queue_redraw (self, self);
6757 _clutter_paint_volume_init_static (&allocation_pv, self);
6758 pv = &allocation_pv;
6760 _clutter_actor_get_allocation_clip (self, &allocation_clip);
6762 origin.x = allocation_clip.x1;
6763 origin.y = allocation_clip.y1;
6765 clutter_paint_volume_set_origin (pv, &origin);
6766 clutter_paint_volume_set_width (pv,
6767 allocation_clip.x2 - allocation_clip.x1);
6768 clutter_paint_volume_set_height (pv,
6769 allocation_clip.y2 -
6770 allocation_clip.y1);
6771 should_free_pv = TRUE;
6776 should_free_pv = FALSE;
6779 self->priv->queue_redraw_entry =
6780 _clutter_stage_queue_actor_redraw (CLUTTER_STAGE (stage),
6781 priv->queue_redraw_entry,
6786 clutter_paint_volume_free (pv);
6788 /* If this is the first redraw queued then we can directly use the
6790 if (!priv->is_dirty)
6791 priv->effect_to_redraw = effect;
6792 /* Otherwise we need to merge it with the existing effect parameter */
6793 else if (effect != NULL)
6795 /* If there's already an effect then we need to use whichever is
6796 later in the chain of actors. Otherwise a full redraw has
6797 already been queued on the actor so we need to ignore the
6799 if (priv->effect_to_redraw != NULL)
6801 if (priv->effects == NULL)
6802 g_warning ("Redraw queued with an effect that is "
6803 "not applied to the actor");
6808 for (l = _clutter_meta_group_peek_metas (priv->effects);
6812 if (l->data == priv->effect_to_redraw ||
6814 priv->effect_to_redraw = l->data;
6821 /* If no effect is specified then we need to redraw the whole
6823 priv->effect_to_redraw = NULL;
6826 priv->is_dirty = TRUE;
6830 * clutter_actor_queue_redraw:
6831 * @self: A #ClutterActor
6833 * Queues up a redraw of an actor and any children. The redraw occurs
6834 * once the main loop becomes idle (after the current batch of events
6835 * has been processed, roughly).
6837 * Applications rarely need to call this, as redraws are handled
6838 * automatically by modification functions.
6840 * This function will not do anything if @self is not visible, or
6841 * if the actor is inside an invisible part of the scenegraph.
6843 * Also be aware that painting is a NOP for actors with an opacity of
6846 * When you are implementing a custom actor you must queue a redraw
6847 * whenever some private state changes that will affect painting or
6848 * picking of your actor.
6851 clutter_actor_queue_redraw (ClutterActor *self)
6853 g_return_if_fail (CLUTTER_IS_ACTOR (self));
6855 _clutter_actor_queue_redraw_full (self,
6857 NULL, /* clip volume */
6862 * _clutter_actor_queue_redraw_with_clip:
6863 * @self: A #ClutterActor
6864 * @flags: A mask of #ClutterRedrawFlags controlling the behaviour of
6865 * this queue redraw.
6866 * @volume: A #ClutterPaintVolume describing the bounds of what needs to be
6867 * redrawn or %NULL if you are just using a @flag to state your
6870 * Queues up a clipped redraw of an actor and any children. The redraw
6871 * occurs once the main loop becomes idle (after the current batch of
6872 * events has been processed, roughly).
6874 * If no flags are given the clip volume is defined by @volume
6875 * specified in actor coordinates and tells Clutter that only content
6876 * within this volume has been changed so Clutter can optionally
6877 * optimize the redraw.
6879 * If the %CLUTTER_REDRAW_CLIPPED_TO_ALLOCATION @flag is used, @volume
6880 * should be %NULL and this tells Clutter to use the actor's current
6881 * allocation as a clip box. This flag can only be used for 2D actors,
6882 * because any actor with depth may be projected outside its
6885 * Applications rarely need to call this, as redraws are handled
6886 * automatically by modification functions.
6888 * This function will not do anything if @self is not visible, or if
6889 * the actor is inside an invisible part of the scenegraph.
6891 * Also be aware that painting is a NOP for actors with an opacity of
6894 * When you are implementing a custom actor you must queue a redraw
6895 * whenever some private state changes that will affect painting or
6896 * picking of your actor.
6899 _clutter_actor_queue_redraw_with_clip (ClutterActor *self,
6900 ClutterRedrawFlags flags,
6901 ClutterPaintVolume *volume)
6903 _clutter_actor_queue_redraw_full (self,
6905 volume, /* clip volume */
6910 _clutter_actor_queue_only_relayout (ClutterActor *self)
6912 ClutterActorPrivate *priv = self->priv;
6914 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
6917 if (priv->needs_width_request &&
6918 priv->needs_height_request &&
6919 priv->needs_allocation)
6920 return; /* save some cpu cycles */
6922 #if CLUTTER_ENABLE_DEBUG
6923 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self) && CLUTTER_ACTOR_IN_RELAYOUT (self))
6925 g_warning ("The actor '%s' is currently inside an allocation "
6926 "cycle; calling clutter_actor_queue_relayout() is "
6928 _clutter_actor_get_debug_name (self));
6930 #endif /* CLUTTER_ENABLE_DEBUG */
6932 g_signal_emit (self, actor_signals[QUEUE_RELAYOUT], 0);
6936 * clutter_actor_queue_redraw_with_clip:
6937 * @self: a #ClutterActor
6938 * @clip: (allow-none): a rectangular clip region, or %NULL
6940 * Queues a redraw on @self limited to a specific, actor-relative
6943 * If @clip is %NULL this function is equivalent to
6944 * clutter_actor_queue_redraw().
6949 clutter_actor_queue_redraw_with_clip (ClutterActor *self,
6950 const cairo_rectangle_int_t *clip)
6952 ClutterPaintVolume volume;
6953 ClutterVertex origin;
6955 g_return_if_fail (CLUTTER_IS_ACTOR (self));
6959 clutter_actor_queue_redraw (self);
6963 _clutter_paint_volume_init_static (&volume, self);
6969 clutter_paint_volume_set_origin (&volume, &origin);
6970 clutter_paint_volume_set_width (&volume, clip->width);
6971 clutter_paint_volume_set_height (&volume, clip->height);
6973 _clutter_actor_queue_redraw_full (self, 0, &volume, NULL);
6975 clutter_paint_volume_free (&volume);
6979 * clutter_actor_queue_relayout:
6980 * @self: A #ClutterActor
6982 * Indicates that the actor's size request or other layout-affecting
6983 * properties may have changed. This function is used inside #ClutterActor
6984 * subclass implementations, not by applications directly.
6986 * Queueing a new layout automatically queues a redraw as well.
6991 clutter_actor_queue_relayout (ClutterActor *self)
6993 g_return_if_fail (CLUTTER_IS_ACTOR (self));
6995 _clutter_actor_queue_only_relayout (self);
6996 clutter_actor_queue_redraw (self);
7000 * clutter_actor_get_preferred_size:
7001 * @self: a #ClutterActor
7002 * @min_width_p: (out) (allow-none): return location for the minimum
7004 * @min_height_p: (out) (allow-none): return location for the minimum
7006 * @natural_width_p: (out) (allow-none): return location for the natural
7008 * @natural_height_p: (out) (allow-none): return location for the natural
7011 * Computes the preferred minimum and natural size of an actor, taking into
7012 * account the actor's geometry management (either height-for-width
7013 * or width-for-height).
7015 * The width and height used to compute the preferred height and preferred
7016 * width are the actor's natural ones.
7018 * If you need to control the height for the preferred width, or the width for
7019 * the preferred height, you should use clutter_actor_get_preferred_width()
7020 * and clutter_actor_get_preferred_height(), and check the actor's preferred
7021 * geometry management using the #ClutterActor:request-mode property.
7026 clutter_actor_get_preferred_size (ClutterActor *self,
7027 gfloat *min_width_p,
7028 gfloat *min_height_p,
7029 gfloat *natural_width_p,
7030 gfloat *natural_height_p)
7032 ClutterActorPrivate *priv;
7033 gfloat min_width, min_height;
7034 gfloat natural_width, natural_height;
7036 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7040 min_width = min_height = 0;
7041 natural_width = natural_height = 0;
7043 if (priv->request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
7045 CLUTTER_NOTE (LAYOUT, "Preferred size (height-for-width)");
7046 clutter_actor_get_preferred_width (self, -1,
7049 clutter_actor_get_preferred_height (self, natural_width,
7055 CLUTTER_NOTE (LAYOUT, "Preferred size (width-for-height)");
7056 clutter_actor_get_preferred_height (self, -1,
7059 clutter_actor_get_preferred_width (self, natural_height,
7065 *min_width_p = min_width;
7068 *min_height_p = min_height;
7070 if (natural_width_p)
7071 *natural_width_p = natural_width;
7073 if (natural_height_p)
7074 *natural_height_p = natural_height;
7079 * @align: a #ClutterActorAlign
7080 * @direction: a #ClutterTextDirection
7082 * Retrieves the correct alignment depending on the text direction
7084 * Return value: the effective alignment
7086 static ClutterActorAlign
7087 effective_align (ClutterActorAlign align,
7088 ClutterTextDirection direction)
7090 ClutterActorAlign res;
7094 case CLUTTER_ACTOR_ALIGN_START:
7095 res = (direction == CLUTTER_TEXT_DIRECTION_RTL)
7096 ? CLUTTER_ACTOR_ALIGN_END
7097 : CLUTTER_ACTOR_ALIGN_START;
7100 case CLUTTER_ACTOR_ALIGN_END:
7101 res = (direction == CLUTTER_TEXT_DIRECTION_RTL)
7102 ? CLUTTER_ACTOR_ALIGN_START
7103 : CLUTTER_ACTOR_ALIGN_END;
7115 adjust_for_margin (float margin_start,
7117 float *minimum_size,
7118 float *natural_size,
7119 float *allocated_start,
7120 float *allocated_end)
7122 *minimum_size -= (margin_start + margin_end);
7123 *natural_size -= (margin_start + margin_end);
7124 *allocated_start += margin_start;
7125 *allocated_end -= margin_end;
7129 adjust_for_alignment (ClutterActorAlign alignment,
7131 float *allocated_start,
7132 float *allocated_end)
7134 float allocated_size = *allocated_end - *allocated_start;
7138 case CLUTTER_ACTOR_ALIGN_FILL:
7142 case CLUTTER_ACTOR_ALIGN_START:
7144 *allocated_end = *allocated_start + MIN (natural_size, allocated_size);
7147 case CLUTTER_ACTOR_ALIGN_END:
7148 if (allocated_size > natural_size)
7150 *allocated_start += (allocated_size - natural_size);
7151 *allocated_end = *allocated_start + natural_size;
7155 case CLUTTER_ACTOR_ALIGN_CENTER:
7156 if (allocated_size > natural_size)
7158 *allocated_start += ceilf ((allocated_size - natural_size) / 2);
7159 *allocated_end = *allocated_start + MIN (allocated_size, natural_size);
7166 * clutter_actor_adjust_width:
7167 * @self: a #ClutterActor
7168 * @minimum_width: (inout): the actor's preferred minimum width, which
7169 * will be adjusted depending on the margin
7170 * @natural_width: (inout): the actor's preferred natural width, which
7171 * will be adjusted depending on the margin
7172 * @adjusted_x1: (out): the adjusted x1 for the actor's bounding box
7173 * @adjusted_x2: (out): the adjusted x2 for the actor's bounding box
7175 * Adjusts the preferred and allocated position and size of an actor,
7176 * depending on the margin and alignment properties.
7179 clutter_actor_adjust_width (ClutterActor *self,
7180 gfloat *minimum_width,
7181 gfloat *natural_width,
7182 gfloat *adjusted_x1,
7183 gfloat *adjusted_x2)
7185 ClutterTextDirection text_dir;
7186 const ClutterLayoutInfo *info;
7188 info = _clutter_actor_get_layout_info_or_defaults (self);
7189 text_dir = clutter_actor_get_text_direction (self);
7191 CLUTTER_NOTE (LAYOUT, "Adjusting allocated X and width");
7193 /* this will tweak natural_width to remove the margin, so that
7194 * adjust_for_alignment() will use the correct size
7196 adjust_for_margin (info->margin.left, info->margin.right,
7197 minimum_width, natural_width,
7198 adjusted_x1, adjusted_x2);
7200 adjust_for_alignment (effective_align (info->x_align, text_dir),
7202 adjusted_x1, adjusted_x2);
7206 * clutter_actor_adjust_height:
7207 * @self: a #ClutterActor
7208 * @minimum_height: (inout): the actor's preferred minimum height, which
7209 * will be adjusted depending on the margin
7210 * @natural_height: (inout): the actor's preferred natural height, which
7211 * will be adjusted depending on the margin
7212 * @adjusted_y1: (out): the adjusted y1 for the actor's bounding box
7213 * @adjusted_y2: (out): the adjusted y2 for the actor's bounding box
7215 * Adjusts the preferred and allocated position and size of an actor,
7216 * depending on the margin and alignment properties.
7219 clutter_actor_adjust_height (ClutterActor *self,
7220 gfloat *minimum_height,
7221 gfloat *natural_height,
7222 gfloat *adjusted_y1,
7223 gfloat *adjusted_y2)
7225 const ClutterLayoutInfo *info;
7227 info = _clutter_actor_get_layout_info_or_defaults (self);
7229 CLUTTER_NOTE (LAYOUT, "Adjusting allocated Y and height");
7231 /* this will tweak natural_height to remove the margin, so that
7232 * adjust_for_alignment() will use the correct size
7234 adjust_for_margin (info->margin.top, info->margin.bottom,
7235 minimum_height, natural_height,
7239 /* we don't use effective_align() here, because text direction
7240 * only affects the horizontal axis
7242 adjust_for_alignment (info->y_align,
7249 /* looks for a cached size request for this for_size. If not
7250 * found, returns the oldest entry so it can be overwritten */
7252 _clutter_actor_get_cached_size_request (gfloat for_size,
7253 SizeRequest *cached_size_requests,
7254 SizeRequest **result)
7258 *result = &cached_size_requests[0];
7260 for (i = 0; i < N_CACHED_SIZE_REQUESTS; i++)
7264 sr = &cached_size_requests[i];
7267 sr->for_size == for_size)
7269 CLUTTER_NOTE (LAYOUT, "Size cache hit for size: %.2f", for_size);
7273 else if (sr->age < (*result)->age)
7279 CLUTTER_NOTE (LAYOUT, "Size cache miss for size: %.2f", for_size);
7285 * clutter_actor_get_preferred_width:
7286 * @self: A #ClutterActor
7287 * @for_height: available height when computing the preferred width,
7288 * or a negative value to indicate that no height is defined
7289 * @min_width_p: (out) (allow-none): return location for minimum width,
7291 * @natural_width_p: (out) (allow-none): return location for the natural
7294 * Computes the requested minimum and natural widths for an actor,
7295 * optionally depending on the specified height, or if they are
7296 * already computed, returns the cached values.
7298 * An actor may not get its request - depending on the layout
7299 * manager that's in effect.
7301 * A request should not incorporate the actor's scale or anchor point;
7302 * those transformations do not affect layout, only rendering.
7307 clutter_actor_get_preferred_width (ClutterActor *self,
7309 gfloat *min_width_p,
7310 gfloat *natural_width_p)
7312 float request_min_width, request_natural_width;
7313 SizeRequest *cached_size_request;
7314 const ClutterLayoutInfo *info;
7315 ClutterActorPrivate *priv;
7316 gboolean found_in_cache;
7318 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7322 info = _clutter_actor_get_layout_info_or_defaults (self);
7324 /* we shortcircuit the case of a fixed size set using set_width() */
7325 if (priv->min_width_set && priv->natural_width_set)
7327 if (min_width_p != NULL)
7328 *min_width_p = info->min_width + (info->margin.left + info->margin.right);
7330 if (natural_width_p != NULL)
7331 *natural_width_p = info->natural_width + (info->margin.left + info->margin.right);
7336 /* the remaining cases are:
7338 * - either min_width or natural_width have been set
7339 * - neither min_width or natural_width have been set
7341 * in both cases, we go through the cache (and through the actor in case
7342 * of cache misses) and determine the authoritative value depending on
7346 if (!priv->needs_width_request)
7349 _clutter_actor_get_cached_size_request (for_height,
7350 priv->width_requests,
7351 &cached_size_request);
7355 /* if the actor needs a width request we use the first slot */
7356 found_in_cache = FALSE;
7357 cached_size_request = &priv->width_requests[0];
7360 if (!found_in_cache)
7362 gfloat minimum_width, natural_width;
7363 ClutterActorClass *klass;
7365 minimum_width = natural_width = 0;
7367 /* adjust for the margin */
7368 if (for_height >= 0)
7370 for_height -= (info->margin.top + info->margin.bottom);
7375 CLUTTER_NOTE (LAYOUT, "Width request for %.2f px", for_height);
7377 klass = CLUTTER_ACTOR_GET_CLASS (self);
7378 klass->get_preferred_width (self, for_height,
7382 /* adjust for the margin */
7383 minimum_width += (info->margin.left + info->margin.right);
7384 natural_width += (info->margin.left + info->margin.right);
7386 /* Due to accumulated float errors, it's better not to warn
7387 * on this, but just fix it.
7389 if (natural_width < minimum_width)
7390 natural_width = minimum_width;
7392 cached_size_request->min_size = minimum_width;
7393 cached_size_request->natural_size = natural_width;
7394 cached_size_request->for_size = for_height;
7395 cached_size_request->age = priv->cached_width_age;
7397 priv->cached_width_age += 1;
7398 priv->needs_width_request = FALSE;
7401 if (!priv->min_width_set)
7402 request_min_width = cached_size_request->min_size;
7404 request_min_width = info->min_width;
7406 if (!priv->natural_width_set)
7407 request_natural_width = cached_size_request->natural_size;
7409 request_natural_width = info->natural_width;
7412 *min_width_p = request_min_width;
7414 if (natural_width_p)
7415 *natural_width_p = request_natural_width;
7419 * clutter_actor_get_preferred_height:
7420 * @self: A #ClutterActor
7421 * @for_width: available width to assume in computing desired height,
7422 * or a negative value to indicate that no width is defined
7423 * @min_height_p: (out) (allow-none): return location for minimum height,
7425 * @natural_height_p: (out) (allow-none): return location for natural
7428 * Computes the requested minimum and natural heights for an actor,
7429 * or if they are already computed, returns the cached values.
7431 * An actor may not get its request - depending on the layout
7432 * manager that's in effect.
7434 * A request should not incorporate the actor's scale or anchor point;
7435 * those transformations do not affect layout, only rendering.
7440 clutter_actor_get_preferred_height (ClutterActor *self,
7442 gfloat *min_height_p,
7443 gfloat *natural_height_p)
7445 float request_min_height, request_natural_height;
7446 SizeRequest *cached_size_request;
7447 const ClutterLayoutInfo *info;
7448 ClutterActorPrivate *priv;
7449 gboolean found_in_cache;
7451 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7455 info = _clutter_actor_get_layout_info_or_defaults (self);
7457 /* we shortcircuit the case of a fixed size set using set_height() */
7458 if (priv->min_height_set && priv->natural_height_set)
7460 if (min_height_p != NULL)
7461 *min_height_p = info->min_height + (info->margin.top + info->margin.bottom);
7463 if (natural_height_p != NULL)
7464 *natural_height_p = info->natural_height + (info->margin.top + info->margin.bottom);
7469 /* the remaining cases are:
7471 * - either min_height or natural_height have been set
7472 * - neither min_height or natural_height have been set
7474 * in both cases, we go through the cache (and through the actor in case
7475 * of cache misses) and determine the authoritative value depending on
7479 if (!priv->needs_height_request)
7482 _clutter_actor_get_cached_size_request (for_width,
7483 priv->height_requests,
7484 &cached_size_request);
7488 found_in_cache = FALSE;
7489 cached_size_request = &priv->height_requests[0];
7492 if (!found_in_cache)
7494 gfloat minimum_height, natural_height;
7495 ClutterActorClass *klass;
7497 minimum_height = natural_height = 0;
7499 CLUTTER_NOTE (LAYOUT, "Height request for %.2f px", for_width);
7501 /* adjust for margin */
7504 for_width -= (info->margin.left + info->margin.right);
7509 klass = CLUTTER_ACTOR_GET_CLASS (self);
7510 klass->get_preferred_height (self, for_width,
7514 /* adjust for margin */
7515 minimum_height += (info->margin.top + info->margin.bottom);
7516 natural_height += (info->margin.top + info->margin.bottom);
7518 /* Due to accumulated float errors, it's better not to warn
7519 * on this, but just fix it.
7521 if (natural_height < minimum_height)
7522 natural_height = minimum_height;
7524 cached_size_request->min_size = minimum_height;
7525 cached_size_request->natural_size = natural_height;
7526 cached_size_request->for_size = for_width;
7527 cached_size_request->age = priv->cached_height_age;
7529 priv->cached_height_age += 1;
7530 priv->needs_height_request = FALSE;
7533 if (!priv->min_height_set)
7534 request_min_height = cached_size_request->min_size;
7536 request_min_height = info->min_height;
7538 if (!priv->natural_height_set)
7539 request_natural_height = cached_size_request->natural_size;
7541 request_natural_height = info->natural_height;
7544 *min_height_p = request_min_height;
7546 if (natural_height_p)
7547 *natural_height_p = request_natural_height;
7551 * clutter_actor_get_allocation_box:
7552 * @self: A #ClutterActor
7553 * @box: (out): the function fills this in with the actor's allocation
7555 * Gets the layout box an actor has been assigned. The allocation can
7556 * only be assumed valid inside a paint() method; anywhere else, it
7557 * may be out-of-date.
7559 * An allocation does not incorporate the actor's scale or anchor point;
7560 * those transformations do not affect layout, only rendering.
7562 * <note>Do not call any of the clutter_actor_get_allocation_*() family
7563 * of functions inside the implementation of the get_preferred_width()
7564 * or get_preferred_height() virtual functions.</note>
7569 clutter_actor_get_allocation_box (ClutterActor *self,
7570 ClutterActorBox *box)
7572 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7574 /* XXX - if needs_allocation=TRUE, we can either 1) g_return_if_fail,
7575 * which limits calling get_allocation to inside paint() basically; or
7576 * we can 2) force a layout, which could be expensive if someone calls
7577 * get_allocation somewhere silly; or we can 3) just return the latest
7578 * value, allowing it to be out-of-date, and assume people know what
7581 * The least-surprises approach that keeps existing code working is
7582 * likely to be 2). People can end up doing some inefficient things,
7583 * though, and in general code that requires 2) is probably broken.
7586 /* this implements 2) */
7587 if (G_UNLIKELY (self->priv->needs_allocation))
7589 ClutterActor *stage = _clutter_actor_get_stage_internal (self);
7591 /* do not queue a relayout on an unparented actor */
7593 _clutter_stage_maybe_relayout (stage);
7596 /* commenting out the code above and just keeping this assigment
7599 *box = self->priv->allocation;
7603 * clutter_actor_get_allocation_geometry:
7604 * @self: A #ClutterActor
7605 * @geom: (out): allocation geometry in pixels
7607 * Gets the layout box an actor has been assigned. The allocation can
7608 * only be assumed valid inside a paint() method; anywhere else, it
7609 * may be out-of-date.
7611 * An allocation does not incorporate the actor's scale or anchor point;
7612 * those transformations do not affect layout, only rendering.
7614 * The returned rectangle is in pixels.
7619 clutter_actor_get_allocation_geometry (ClutterActor *self,
7620 ClutterGeometry *geom)
7622 ClutterActorBox box;
7624 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7625 g_return_if_fail (geom != NULL);
7627 clutter_actor_get_allocation_box (self, &box);
7629 geom->x = CLUTTER_NEARBYINT (clutter_actor_box_get_x (&box));
7630 geom->y = CLUTTER_NEARBYINT (clutter_actor_box_get_y (&box));
7631 geom->width = CLUTTER_NEARBYINT (clutter_actor_box_get_width (&box));
7632 geom->height = CLUTTER_NEARBYINT (clutter_actor_box_get_height (&box));
7636 clutter_actor_update_constraints (ClutterActor *self,
7637 ClutterActorBox *allocation)
7639 ClutterActorPrivate *priv = self->priv;
7640 const GList *constraints, *l;
7642 if (priv->constraints == NULL)
7645 constraints = _clutter_meta_group_peek_metas (priv->constraints);
7646 for (l = constraints; l != NULL; l = l->next)
7648 ClutterConstraint *constraint = l->data;
7649 ClutterActorMeta *meta = l->data;
7651 if (clutter_actor_meta_get_enabled (meta))
7653 _clutter_constraint_update_allocation (constraint,
7661 * clutter_actor_adjust_allocation:
7662 * @self: a #ClutterActor
7663 * @allocation: (inout): the allocation to adjust
7665 * Adjusts the passed allocation box taking into account the actor's
7666 * layout information, like alignment, expansion, and margin.
7669 clutter_actor_adjust_allocation (ClutterActor *self,
7670 ClutterActorBox *allocation)
7672 ClutterActorBox adj_allocation;
7673 float alloc_width, alloc_height;
7674 float min_width, min_height;
7675 float nat_width, nat_height;
7676 ClutterRequestMode req_mode;
7678 adj_allocation = *allocation;
7680 clutter_actor_box_get_size (allocation, &alloc_width, &alloc_height);
7682 /* we want to hit the cache, so we use the public API */
7683 req_mode = clutter_actor_get_request_mode (self);
7685 if (req_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
7687 clutter_actor_get_preferred_width (self, -1,
7690 clutter_actor_get_preferred_height (self, alloc_width,
7694 else if (req_mode == CLUTTER_REQUEST_WIDTH_FOR_HEIGHT)
7696 clutter_actor_get_preferred_height (self, -1,
7699 clutter_actor_get_preferred_height (self, alloc_height,
7704 #ifdef CLUTTER_ENABLE_DEBUG
7705 /* warn about underallocations */
7706 if (_clutter_diagnostic_enabled () &&
7707 (floorf (min_width - alloc_width) > 0 ||
7708 floorf (min_height - alloc_height) > 0))
7710 ClutterActor *parent = clutter_actor_get_parent (self);
7712 /* the only actors that are allowed to be underallocated are the Stage,
7713 * as it doesn't have an implicit size, and Actors that specifically
7714 * told us that they want to opt-out from layout control mechanisms
7715 * through the NO_LAYOUT escape hatch.
7717 if (parent != NULL &&
7718 !(self->flags & CLUTTER_ACTOR_NO_LAYOUT) != 0)
7720 g_warning (G_STRLOC ": The actor '%s' is getting an allocation "
7721 "of %.2f x %.2f from its parent actor '%s', but its "
7722 "requested minimum size is of %.2f x %.2f",
7723 _clutter_actor_get_debug_name (self),
7724 alloc_width, alloc_height,
7725 _clutter_actor_get_debug_name (parent),
7726 min_width, min_height);
7731 clutter_actor_adjust_width (self,
7735 &adj_allocation.x2);
7737 clutter_actor_adjust_height (self,
7741 &adj_allocation.y2);
7743 /* we maintain the invariant that an allocation cannot be adjusted
7744 * to be outside the parent-given box
7746 if (adj_allocation.x1 < allocation->x1 ||
7747 adj_allocation.y1 < allocation->y1 ||
7748 adj_allocation.x2 > allocation->x2 ||
7749 adj_allocation.y2 > allocation->y2)
7751 g_warning (G_STRLOC ": The actor '%s' tried to adjust its allocation "
7752 "to { %.2f, %.2f, %.2f, %.2f }, which is outside of its "
7753 "original allocation of { %.2f, %.2f, %.2f, %.2f }",
7754 _clutter_actor_get_debug_name (self),
7755 adj_allocation.x1, adj_allocation.y1,
7756 adj_allocation.x2 - adj_allocation.x1,
7757 adj_allocation.y2 - adj_allocation.y1,
7758 allocation->x1, allocation->y1,
7759 allocation->x2 - allocation->x1,
7760 allocation->y2 - allocation->y1);
7764 *allocation = adj_allocation;
7768 * clutter_actor_allocate:
7769 * @self: A #ClutterActor
7770 * @box: new allocation of the actor, in parent-relative coordinates
7771 * @flags: flags that control the allocation
7773 * Called by the parent of an actor to assign the actor its size.
7774 * Should never be called by applications (except when implementing
7775 * a container or layout manager).
7777 * Actors can know from their allocation box whether they have moved
7778 * with respect to their parent actor. The @flags parameter describes
7779 * additional information about the allocation, for instance whether
7780 * the parent has moved with respect to the stage, for example because
7781 * a grandparent's origin has moved.
7786 clutter_actor_allocate (ClutterActor *self,
7787 const ClutterActorBox *box,
7788 ClutterAllocationFlags flags)
7790 ClutterActorPrivate *priv;
7791 ClutterActorClass *klass;
7792 ClutterActorBox old_allocation, real_allocation;
7793 gboolean origin_changed, child_moved, size_changed;
7794 gboolean stage_allocation_changed;
7796 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7797 if (G_UNLIKELY (_clutter_actor_get_stage_internal (self) == NULL))
7799 g_warning ("Spurious clutter_actor_allocate called for actor %p/%s "
7800 "which isn't a descendent of the stage!\n",
7801 self, _clutter_actor_get_debug_name (self));
7807 old_allocation = priv->allocation;
7808 real_allocation = *box;
7810 /* constraints are allowed to modify the allocation only here; we do
7811 * this prior to all the other checks so that we can bail out if the
7812 * allocation did not change
7814 clutter_actor_update_constraints (self, &real_allocation);
7816 /* adjust the allocation depending on the align/margin properties */
7817 clutter_actor_adjust_allocation (self, &real_allocation);
7819 if (real_allocation.x2 < real_allocation.x1 ||
7820 real_allocation.y2 < real_allocation.y1)
7822 g_warning (G_STRLOC ": Actor '%s' tried to allocate a size of %.2f x %.2f",
7823 _clutter_actor_get_debug_name (self),
7824 real_allocation.x2 - real_allocation.x1,
7825 real_allocation.y2 - real_allocation.y1);
7828 /* we allow 0-sized actors, but not negative-sized ones */
7829 real_allocation.x2 = MAX (real_allocation.x2, real_allocation.x1);
7830 real_allocation.y2 = MAX (real_allocation.y2, real_allocation.y1);
7832 origin_changed = (flags & CLUTTER_ABSOLUTE_ORIGIN_CHANGED);
7834 child_moved = (real_allocation.x1 != old_allocation.x1 ||
7835 real_allocation.y1 != old_allocation.y1);
7837 size_changed = (real_allocation.x2 != old_allocation.x2 ||
7838 real_allocation.y2 != old_allocation.y2);
7840 if (origin_changed || child_moved || size_changed)
7841 stage_allocation_changed = TRUE;
7843 stage_allocation_changed = FALSE;
7845 /* If we get an allocation "out of the blue"
7846 * (we did not queue relayout), then we want to
7847 * ignore it. But if we have needs_allocation set,
7848 * we want to guarantee that allocate() virtual
7849 * method is always called, i.e. that queue_relayout()
7850 * always results in an allocate() invocation on
7853 * The optimization here is to avoid re-allocating
7854 * actors that did not queue relayout and were
7857 if (!priv->needs_allocation && !stage_allocation_changed)
7859 CLUTTER_NOTE (LAYOUT, "No allocation needed");
7863 /* When ABSOLUTE_ORIGIN_CHANGED is passed in to
7864 * clutter_actor_allocate(), it indicates whether the parent has its
7865 * absolute origin moved; when passed in to ClutterActor::allocate()
7866 * virtual method though, it indicates whether the child has its
7867 * absolute origin moved. So we set it when child_moved is TRUE
7870 flags |= CLUTTER_ABSOLUTE_ORIGIN_CHANGED;
7872 CLUTTER_SET_PRIVATE_FLAGS (self, CLUTTER_IN_RELAYOUT);
7874 klass = CLUTTER_ACTOR_GET_CLASS (self);
7875 klass->allocate (self, &real_allocation, flags);
7877 CLUTTER_UNSET_PRIVATE_FLAGS (self, CLUTTER_IN_RELAYOUT);
7879 if (stage_allocation_changed)
7880 clutter_actor_queue_redraw (self);
7884 * clutter_actor_set_allocation:
7885 * @self: a #ClutterActor
7886 * @box: a #ClutterActorBox
7887 * @flags: allocation flags
7889 * Stores the allocation of @self as defined by @box.
7891 * This function can only be called from within the implementation of
7892 * the #ClutterActorClass.allocate() virtual function.
7894 * The allocation should have been adjusted to take into account constraints,
7895 * alignment, and margin properties. If you are implementing a #ClutterActor
7896 * subclass that provides its own layout management policy for its children
7897 * instead of using a #ClutterLayoutManager delegate, you should not call
7898 * this function on the children of @self; instead, you should call
7899 * clutter_actor_allocate(), which will adjust the allocation box for
7902 * This function should only be used by subclasses of #ClutterActor
7903 * that wish to store their allocation but cannot chain up to the
7904 * parent's implementation; the default implementation of the
7905 * #ClutterActorClass.allocate() virtual function will call this
7908 * It is important to note that, while chaining up was the recommended
7909 * behaviour for #ClutterActor subclasses prior to the introduction of
7910 * this function, it is recommended to call clutter_actor_set_allocation()
7913 * If the #ClutterActor is using a #ClutterLayoutManager delegate object
7914 * to handle the allocation of its children, this function will call
7915 * the clutter_layout_manager_allocate() function only if the
7916 * %CLUTTER_DELEGATE_LAYOUT flag is set on @flags, otherwise it is
7917 * expected that the subclass will call clutter_layout_manager_allocate()
7918 * by itself. For instance, the following code:
7922 * my_actor_allocate (ClutterActor *actor,
7923 * const ClutterActorBox *allocation,
7924 * ClutterAllocationFlags flags)
7926 * ClutterActorBox new_alloc;
7927 * ClutterAllocationFlags new_flags;
7929 * adjust_allocation (allocation, &new_alloc);
7931 * new_flags = flags | CLUTTER_DELEGATE_LAYOUT;
7933 * /* this will use the layout manager set on the actor */
7934 * clutter_actor_set_allocation (actor, &new_alloc, new_flags);
7938 * is equivalent to this:
7942 * my_actor_allocate (ClutterActor *actor,
7943 * const ClutterActorBox *allocation,
7944 * ClutterAllocationFlags flags)
7946 * ClutterLayoutManager *layout;
7947 * ClutterActorBox new_alloc;
7949 * adjust_allocation (allocation, &new_alloc);
7951 * clutter_actor_set_allocation (actor, &new_alloc, flags);
7953 * layout = clutter_actor_get_layout_manager (actor);
7954 * clutter_layout_manager_allocate (layout,
7955 * CLUTTER_CONTAINER (actor),
7964 clutter_actor_set_allocation (ClutterActor *self,
7965 const ClutterActorBox *box,
7966 ClutterAllocationFlags flags)
7968 ClutterActorPrivate *priv;
7971 g_return_if_fail (CLUTTER_IS_ACTOR (self));
7972 g_return_if_fail (box != NULL);
7974 if (G_UNLIKELY (!CLUTTER_ACTOR_IN_RELAYOUT (self)))
7976 g_critical (G_STRLOC ": The clutter_actor_set_allocation() function "
7977 "can only be called from within the implementation of "
7978 "the ClutterActor::allocate() virtual function.");
7984 g_object_freeze_notify (G_OBJECT (self));
7986 changed = clutter_actor_set_allocation_internal (self, box, flags);
7988 /* we allocate our children before we notify changes in our geometry,
7989 * so that people connecting to properties will be able to get valid
7990 * data out of the sub-tree of the scene graph that has this actor at
7993 clutter_actor_maybe_layout_children (self, box, flags);
7997 ClutterActorBox signal_box = priv->allocation;
7998 ClutterAllocationFlags signal_flags = priv->allocation_flags;
8000 g_signal_emit (self, actor_signals[ALLOCATION_CHANGED], 0,
8005 g_object_thaw_notify (G_OBJECT (self));
8009 * clutter_actor_set_geometry:
8010 * @self: A #ClutterActor
8011 * @geometry: A #ClutterGeometry
8013 * Sets the actor's fixed position and forces its minimum and natural
8014 * size, in pixels. This means the untransformed actor will have the
8015 * given geometry. This is the same as calling clutter_actor_set_position()
8016 * and clutter_actor_set_size().
8018 * Deprecated: 1.10: Use clutter_actor_set_position() and
8019 * clutter_actor_set_size() instead.
8022 clutter_actor_set_geometry (ClutterActor *self,
8023 const ClutterGeometry *geometry)
8025 g_object_freeze_notify (G_OBJECT (self));
8027 clutter_actor_set_position (self, geometry->x, geometry->y);
8028 clutter_actor_set_size (self, geometry->width, geometry->height);
8030 g_object_thaw_notify (G_OBJECT (self));
8034 * clutter_actor_get_geometry:
8035 * @self: A #ClutterActor
8036 * @geometry: (out caller-allocates): A location to store actors #ClutterGeometry
8038 * Gets the size and position of an actor relative to its parent
8039 * actor. This is the same as calling clutter_actor_get_position() and
8040 * clutter_actor_get_size(). It tries to "do what you mean" and get the
8041 * requested size and position if the actor's allocation is invalid.
8043 * Deprecated: 1.10: Use clutter_actor_get_position() and
8044 * clutter_actor_get_size(), or clutter_actor_get_allocation_geometry()
8048 clutter_actor_get_geometry (ClutterActor *self,
8049 ClutterGeometry *geometry)
8051 gfloat x, y, width, height;
8053 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8054 g_return_if_fail (geometry != NULL);
8056 clutter_actor_get_position (self, &x, &y);
8057 clutter_actor_get_size (self, &width, &height);
8059 geometry->x = (int) x;
8060 geometry->y = (int) y;
8061 geometry->width = (int) width;
8062 geometry->height = (int) height;
8066 * clutter_actor_set_position:
8067 * @self: A #ClutterActor
8068 * @x: New left position of actor in pixels.
8069 * @y: New top position of actor in pixels.
8071 * Sets the actor's fixed position in pixels relative to any parent
8074 * If a layout manager is in use, this position will override the
8075 * layout manager and force a fixed position.
8078 clutter_actor_set_position (ClutterActor *self,
8082 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8084 g_object_freeze_notify (G_OBJECT (self));
8086 clutter_actor_set_x (self, x);
8087 clutter_actor_set_y (self, y);
8089 g_object_thaw_notify (G_OBJECT (self));
8093 * clutter_actor_get_fixed_position_set:
8094 * @self: A #ClutterActor
8096 * Checks whether an actor has a fixed position set (and will thus be
8097 * unaffected by any layout manager).
8099 * Return value: %TRUE if the fixed position is set on the actor
8104 clutter_actor_get_fixed_position_set (ClutterActor *self)
8106 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
8108 return self->priv->position_set;
8112 * clutter_actor_set_fixed_position_set:
8113 * @self: A #ClutterActor
8114 * @is_set: whether to use fixed position
8116 * Sets whether an actor has a fixed position set (and will thus be
8117 * unaffected by any layout manager).
8122 clutter_actor_set_fixed_position_set (ClutterActor *self,
8125 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8127 if (self->priv->position_set == (is_set != FALSE))
8130 self->priv->position_set = is_set != FALSE;
8131 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_FIXED_POSITION_SET]);
8133 clutter_actor_queue_relayout (self);
8137 * clutter_actor_move_by:
8138 * @self: A #ClutterActor
8139 * @dx: Distance to move Actor on X axis.
8140 * @dy: Distance to move Actor on Y axis.
8142 * Moves an actor by the specified distance relative to its current
8143 * position in pixels.
8145 * This function modifies the fixed position of an actor and thus removes
8146 * it from any layout management. Another way to move an actor is with an
8147 * anchor point, see clutter_actor_set_anchor_point().
8152 clutter_actor_move_by (ClutterActor *self,
8156 const ClutterLayoutInfo *info;
8159 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8161 info = _clutter_actor_get_layout_info_or_defaults (self);
8165 clutter_actor_set_position (self, x + dx, y + dy);
8169 clutter_actor_set_min_width (ClutterActor *self,
8172 ClutterActorPrivate *priv = self->priv;
8173 ClutterActorBox old = { 0, };
8174 ClutterLayoutInfo *info;
8176 /* if we are setting the size on a top-level actor and the
8177 * backend only supports static top-levels (e.g. framebuffers)
8178 * then we ignore the passed value and we override it with
8179 * the stage implementation's preferred size.
8181 if (CLUTTER_ACTOR_IS_TOPLEVEL (self) &&
8182 clutter_feature_available (CLUTTER_FEATURE_STAGE_STATIC))
8185 info = _clutter_actor_get_layout_info (self);
8187 if (priv->min_width_set && min_width == info->min_width)
8190 g_object_freeze_notify (G_OBJECT (self));
8192 clutter_actor_store_old_geometry (self, &old);
8194 info->min_width = min_width;
8195 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MIN_WIDTH]);
8196 clutter_actor_set_min_width_set (self, TRUE);
8198 clutter_actor_notify_if_geometry_changed (self, &old);
8200 g_object_thaw_notify (G_OBJECT (self));
8202 clutter_actor_queue_relayout (self);
8206 clutter_actor_set_min_height (ClutterActor *self,
8210 ClutterActorPrivate *priv = self->priv;
8211 ClutterActorBox old = { 0, };
8212 ClutterLayoutInfo *info;
8214 /* if we are setting the size on a top-level actor and the
8215 * backend only supports static top-levels (e.g. framebuffers)
8216 * then we ignore the passed value and we override it with
8217 * the stage implementation's preferred size.
8219 if (CLUTTER_ACTOR_IS_TOPLEVEL (self) &&
8220 clutter_feature_available (CLUTTER_FEATURE_STAGE_STATIC))
8223 info = _clutter_actor_get_layout_info (self);
8225 if (priv->min_height_set && min_height == info->min_height)
8228 g_object_freeze_notify (G_OBJECT (self));
8230 clutter_actor_store_old_geometry (self, &old);
8232 info->min_height = min_height;
8233 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MIN_HEIGHT]);
8234 clutter_actor_set_min_height_set (self, TRUE);
8236 clutter_actor_notify_if_geometry_changed (self, &old);
8238 g_object_thaw_notify (G_OBJECT (self));
8240 clutter_actor_queue_relayout (self);
8244 clutter_actor_set_natural_width (ClutterActor *self,
8245 gfloat natural_width)
8247 ClutterActorPrivate *priv = self->priv;
8248 ClutterActorBox old = { 0, };
8249 ClutterLayoutInfo *info;
8251 /* if we are setting the size on a top-level actor and the
8252 * backend only supports static top-levels (e.g. framebuffers)
8253 * then we ignore the passed value and we override it with
8254 * the stage implementation's preferred size.
8256 if (CLUTTER_ACTOR_IS_TOPLEVEL (self) &&
8257 clutter_feature_available (CLUTTER_FEATURE_STAGE_STATIC))
8260 info = _clutter_actor_get_layout_info (self);
8262 if (priv->natural_width_set && natural_width == info->natural_width)
8265 g_object_freeze_notify (G_OBJECT (self));
8267 clutter_actor_store_old_geometry (self, &old);
8269 info->natural_width = natural_width;
8270 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_NATURAL_WIDTH]);
8271 clutter_actor_set_natural_width_set (self, TRUE);
8273 clutter_actor_notify_if_geometry_changed (self, &old);
8275 g_object_thaw_notify (G_OBJECT (self));
8277 clutter_actor_queue_relayout (self);
8281 clutter_actor_set_natural_height (ClutterActor *self,
8282 gfloat natural_height)
8284 ClutterActorPrivate *priv = self->priv;
8285 ClutterActorBox old = { 0, };
8286 ClutterLayoutInfo *info;
8288 /* if we are setting the size on a top-level actor and the
8289 * backend only supports static top-levels (e.g. framebuffers)
8290 * then we ignore the passed value and we override it with
8291 * the stage implementation's preferred size.
8293 if (CLUTTER_ACTOR_IS_TOPLEVEL (self) &&
8294 clutter_feature_available (CLUTTER_FEATURE_STAGE_STATIC))
8297 info = _clutter_actor_get_layout_info (self);
8299 if (priv->natural_height_set && natural_height == info->natural_height)
8302 g_object_freeze_notify (G_OBJECT (self));
8304 clutter_actor_store_old_geometry (self, &old);
8306 info->natural_height = natural_height;
8307 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_NATURAL_HEIGHT]);
8308 clutter_actor_set_natural_height_set (self, TRUE);
8310 clutter_actor_notify_if_geometry_changed (self, &old);
8312 g_object_thaw_notify (G_OBJECT (self));
8314 clutter_actor_queue_relayout (self);
8318 clutter_actor_set_min_width_set (ClutterActor *self,
8319 gboolean use_min_width)
8321 ClutterActorPrivate *priv = self->priv;
8322 ClutterActorBox old = { 0, };
8324 if (priv->min_width_set == (use_min_width != FALSE))
8327 clutter_actor_store_old_geometry (self, &old);
8329 priv->min_width_set = use_min_width != FALSE;
8330 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MIN_WIDTH_SET]);
8332 clutter_actor_notify_if_geometry_changed (self, &old);
8334 clutter_actor_queue_relayout (self);
8338 clutter_actor_set_min_height_set (ClutterActor *self,
8339 gboolean use_min_height)
8341 ClutterActorPrivate *priv = self->priv;
8342 ClutterActorBox old = { 0, };
8344 if (priv->min_height_set == (use_min_height != FALSE))
8347 clutter_actor_store_old_geometry (self, &old);
8349 priv->min_height_set = use_min_height != FALSE;
8350 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MIN_HEIGHT_SET]);
8352 clutter_actor_notify_if_geometry_changed (self, &old);
8354 clutter_actor_queue_relayout (self);
8358 clutter_actor_set_natural_width_set (ClutterActor *self,
8359 gboolean use_natural_width)
8361 ClutterActorPrivate *priv = self->priv;
8362 ClutterActorBox old = { 0, };
8364 if (priv->natural_width_set == (use_natural_width != FALSE))
8367 clutter_actor_store_old_geometry (self, &old);
8369 priv->natural_width_set = use_natural_width != FALSE;
8370 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_NATURAL_WIDTH_SET]);
8372 clutter_actor_notify_if_geometry_changed (self, &old);
8374 clutter_actor_queue_relayout (self);
8378 clutter_actor_set_natural_height_set (ClutterActor *self,
8379 gboolean use_natural_height)
8381 ClutterActorPrivate *priv = self->priv;
8382 ClutterActorBox old = { 0, };
8384 if (priv->natural_height_set == (use_natural_height != FALSE))
8387 clutter_actor_store_old_geometry (self, &old);
8389 priv->natural_height_set = use_natural_height != FALSE;
8390 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_NATURAL_HEIGHT_SET]);
8392 clutter_actor_notify_if_geometry_changed (self, &old);
8394 clutter_actor_queue_relayout (self);
8398 * clutter_actor_set_request_mode:
8399 * @self: a #ClutterActor
8400 * @mode: the request mode
8402 * Sets the geometry request mode of @self.
8404 * The @mode determines the order for invoking
8405 * clutter_actor_get_preferred_width() and
8406 * clutter_actor_get_preferred_height()
8411 clutter_actor_set_request_mode (ClutterActor *self,
8412 ClutterRequestMode mode)
8414 ClutterActorPrivate *priv;
8416 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8420 if (priv->request_mode == mode)
8423 priv->request_mode = mode;
8425 priv->needs_width_request = TRUE;
8426 priv->needs_height_request = TRUE;
8428 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_REQUEST_MODE]);
8430 clutter_actor_queue_relayout (self);
8434 * clutter_actor_get_request_mode:
8435 * @self: a #ClutterActor
8437 * Retrieves the geometry request mode of @self
8439 * Return value: the request mode for the actor
8444 clutter_actor_get_request_mode (ClutterActor *self)
8446 g_return_val_if_fail (CLUTTER_IS_ACTOR (self),
8447 CLUTTER_REQUEST_HEIGHT_FOR_WIDTH);
8449 return self->priv->request_mode;
8452 /* variant of set_width() without checks and without notification
8453 * freeze+thaw, for internal usage only
8456 clutter_actor_set_width_internal (ClutterActor *self,
8461 /* the Stage will use the :min-width to control the minimum
8462 * width to be resized to, so we should not be setting it
8463 * along with the :natural-width
8465 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
8466 clutter_actor_set_min_width (self, width);
8468 clutter_actor_set_natural_width (self, width);
8472 /* we only unset the :natural-width for the Stage */
8473 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
8474 clutter_actor_set_min_width_set (self, FALSE);
8476 clutter_actor_set_natural_width_set (self, FALSE);
8480 /* variant of set_height() without checks and without notification
8481 * freeze+thaw, for internal usage only
8484 clutter_actor_set_height_internal (ClutterActor *self,
8489 /* see the comment above in set_width_internal() */
8490 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
8491 clutter_actor_set_min_height (self, height);
8493 clutter_actor_set_natural_height (self, height);
8497 /* see the comment above in set_width_internal() */
8498 if (!CLUTTER_ACTOR_IS_TOPLEVEL (self))
8499 clutter_actor_set_min_height_set (self, FALSE);
8501 clutter_actor_set_natural_height_set (self, FALSE);
8506 * clutter_actor_set_size:
8507 * @self: A #ClutterActor
8508 * @width: New width of actor in pixels, or -1
8509 * @height: New height of actor in pixels, or -1
8511 * Sets the actor's size request in pixels. This overrides any
8512 * "normal" size request the actor would have. For example
8513 * a text actor might normally request the size of the text;
8514 * this function would force a specific size instead.
8516 * If @width and/or @height are -1 the actor will use its
8517 * "normal" size request instead of overriding it, i.e.
8518 * you can "unset" the size with -1.
8520 * This function sets or unsets both the minimum and natural size.
8523 clutter_actor_set_size (ClutterActor *self,
8527 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8529 g_object_freeze_notify (G_OBJECT (self));
8531 clutter_actor_set_width_internal (self, width);
8532 clutter_actor_set_height_internal (self, height);
8534 g_object_thaw_notify (G_OBJECT (self));
8538 * clutter_actor_get_size:
8539 * @self: A #ClutterActor
8540 * @width: (out) (allow-none): return location for the width, or %NULL.
8541 * @height: (out) (allow-none): return location for the height, or %NULL.
8543 * This function tries to "do what you mean" and return
8544 * the size an actor will have. If the actor has a valid
8545 * allocation, the allocation will be returned; otherwise,
8546 * the actors natural size request will be returned.
8548 * If you care whether you get the request vs. the allocation, you
8549 * should probably call a different function like
8550 * clutter_actor_get_allocation_box() or
8551 * clutter_actor_get_preferred_width().
8556 clutter_actor_get_size (ClutterActor *self,
8560 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8563 *width = clutter_actor_get_width (self);
8566 *height = clutter_actor_get_height (self);
8570 * clutter_actor_get_position:
8571 * @self: a #ClutterActor
8572 * @x: (out) (allow-none): return location for the X coordinate, or %NULL
8573 * @y: (out) (allow-none): return location for the Y coordinate, or %NULL
8575 * This function tries to "do what you mean" and tell you where the
8576 * actor is, prior to any transformations. Retrieves the fixed
8577 * position of an actor in pixels, if one has been set; otherwise, if
8578 * the allocation is valid, returns the actor's allocated position;
8579 * otherwise, returns 0,0.
8581 * The returned position is in pixels.
8586 clutter_actor_get_position (ClutterActor *self,
8590 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8593 *x = clutter_actor_get_x (self);
8596 *y = clutter_actor_get_y (self);
8600 * clutter_actor_get_transformed_position:
8601 * @self: A #ClutterActor
8602 * @x: (out) (allow-none): return location for the X coordinate, or %NULL
8603 * @y: (out) (allow-none): return location for the Y coordinate, or %NULL
8605 * Gets the absolute position of an actor, in pixels relative to the stage.
8610 clutter_actor_get_transformed_position (ClutterActor *self,
8617 v1.x = v1.y = v1.z = 0;
8618 clutter_actor_apply_transform_to_point (self, &v1, &v2);
8628 * clutter_actor_get_transformed_size:
8629 * @self: A #ClutterActor
8630 * @width: (out) (allow-none): return location for the width, or %NULL
8631 * @height: (out) (allow-none): return location for the height, or %NULL
8633 * Gets the absolute size of an actor in pixels, taking into account the
8636 * If the actor has a valid allocation, the allocated size will be used.
8637 * If the actor has not a valid allocation then the preferred size will
8638 * be transformed and returned.
8640 * If you want the transformed allocation, see
8641 * clutter_actor_get_abs_allocation_vertices() instead.
8643 * <note>When the actor (or one of its ancestors) is rotated around the
8644 * X or Y axis, it no longer appears as on the stage as a rectangle, but
8645 * as a generic quadrangle; in that case this function returns the size
8646 * of the smallest rectangle that encapsulates the entire quad. Please
8647 * note that in this case no assumptions can be made about the relative
8648 * position of this envelope to the absolute position of the actor, as
8649 * returned by clutter_actor_get_transformed_position(); if you need this
8650 * information, you need to use clutter_actor_get_abs_allocation_vertices()
8651 * to get the coords of the actual quadrangle.</note>
8656 clutter_actor_get_transformed_size (ClutterActor *self,
8660 ClutterActorPrivate *priv;
8662 gfloat x_min, x_max, y_min, y_max;
8665 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8669 /* if the actor hasn't been allocated yet, get the preferred
8670 * size and transform that
8672 if (priv->needs_allocation)
8674 gfloat natural_width, natural_height;
8675 ClutterActorBox box;
8677 /* Make a fake allocation to transform.
8679 * NB: _clutter_actor_transform_and_project_box expects a box in
8680 * the actor's coordinate space... */
8685 natural_width = natural_height = 0;
8686 clutter_actor_get_preferred_size (self, NULL, NULL,
8690 box.x2 = natural_width;
8691 box.y2 = natural_height;
8693 _clutter_actor_transform_and_project_box (self, &box, v);
8696 clutter_actor_get_abs_allocation_vertices (self, v);
8698 x_min = x_max = v[0].x;
8699 y_min = y_max = v[0].y;
8701 for (i = 1; i < G_N_ELEMENTS (v); ++i)
8717 *width = x_max - x_min;
8720 *height = y_max - y_min;
8724 * clutter_actor_get_width:
8725 * @self: A #ClutterActor
8727 * Retrieves the width of a #ClutterActor.
8729 * If the actor has a valid allocation, this function will return the
8730 * width of the allocated area given to the actor.
8732 * If the actor does not have a valid allocation, this function will
8733 * return the actor's natural width, that is the preferred width of
8736 * If you care whether you get the preferred width or the width that
8737 * has been assigned to the actor, you should probably call a different
8738 * function like clutter_actor_get_allocation_box() to retrieve the
8739 * allocated size or clutter_actor_get_preferred_width() to retrieve the
8742 * If an actor has a fixed width, for instance a width that has been
8743 * assigned using clutter_actor_set_width(), the width returned will
8744 * be the same value.
8746 * Return value: the width of the actor, in pixels
8749 clutter_actor_get_width (ClutterActor *self)
8751 ClutterActorPrivate *priv;
8753 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
8757 if (priv->needs_allocation)
8759 gfloat natural_width = 0;
8761 if (self->priv->request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
8762 clutter_actor_get_preferred_width (self, -1, NULL, &natural_width);
8765 gfloat natural_height = 0;
8767 clutter_actor_get_preferred_height (self, -1, NULL, &natural_height);
8768 clutter_actor_get_preferred_width (self, natural_height,
8773 return natural_width;
8776 return priv->allocation.x2 - priv->allocation.x1;
8780 * clutter_actor_get_height:
8781 * @self: A #ClutterActor
8783 * Retrieves the height of a #ClutterActor.
8785 * If the actor has a valid allocation, this function will return the
8786 * height of the allocated area given to the actor.
8788 * If the actor does not have a valid allocation, this function will
8789 * return the actor's natural height, that is the preferred height of
8792 * If you care whether you get the preferred height or the height that
8793 * has been assigned to the actor, you should probably call a different
8794 * function like clutter_actor_get_allocation_box() to retrieve the
8795 * allocated size or clutter_actor_get_preferred_height() to retrieve the
8798 * If an actor has a fixed height, for instance a height that has been
8799 * assigned using clutter_actor_set_height(), the height returned will
8800 * be the same value.
8802 * Return value: the height of the actor, in pixels
8805 clutter_actor_get_height (ClutterActor *self)
8807 ClutterActorPrivate *priv;
8809 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
8813 if (priv->needs_allocation)
8815 gfloat natural_height = 0;
8817 if (priv->request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
8819 gfloat natural_width = 0;
8821 clutter_actor_get_preferred_width (self, -1, NULL, &natural_width);
8822 clutter_actor_get_preferred_height (self, natural_width,
8823 NULL, &natural_height);
8826 clutter_actor_get_preferred_height (self, -1, NULL, &natural_height);
8828 return natural_height;
8831 return priv->allocation.y2 - priv->allocation.y1;
8835 * clutter_actor_set_width:
8836 * @self: A #ClutterActor
8837 * @width: Requested new width for the actor, in pixels, or -1
8839 * Forces a width on an actor, causing the actor's preferred width
8840 * and height (if any) to be ignored.
8842 * If @width is -1 the actor will use its preferred width request
8843 * instead of overriding it, i.e. you can "unset" the width with -1.
8845 * This function sets both the minimum and natural size of the actor.
8850 clutter_actor_set_width (ClutterActor *self,
8853 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8855 g_object_freeze_notify (G_OBJECT (self));
8857 clutter_actor_set_width_internal (self, width);
8859 g_object_thaw_notify (G_OBJECT (self));
8863 * clutter_actor_set_height:
8864 * @self: A #ClutterActor
8865 * @height: Requested new height for the actor, in pixels, or -1
8867 * Forces a height on an actor, causing the actor's preferred width
8868 * and height (if any) to be ignored.
8870 * If @height is -1 the actor will use its preferred height instead of
8871 * overriding it, i.e. you can "unset" the height with -1.
8873 * This function sets both the minimum and natural size of the actor.
8878 clutter_actor_set_height (ClutterActor *self,
8881 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8883 g_object_freeze_notify (G_OBJECT (self));
8885 clutter_actor_set_height_internal (self, height);
8887 g_object_thaw_notify (G_OBJECT (self));
8891 * clutter_actor_set_x:
8892 * @self: a #ClutterActor
8893 * @x: the actor's position on the X axis
8895 * Sets the actor's X coordinate, relative to its parent, in pixels.
8897 * Overrides any layout manager and forces a fixed position for
8903 clutter_actor_set_x (ClutterActor *self,
8906 ClutterActorBox old = { 0, };
8907 ClutterActorPrivate *priv;
8908 ClutterLayoutInfo *info;
8910 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8914 info = _clutter_actor_get_layout_info (self);
8916 if (priv->position_set && info->fixed_x == x)
8919 clutter_actor_store_old_geometry (self, &old);
8922 clutter_actor_set_fixed_position_set (self, TRUE);
8924 clutter_actor_notify_if_geometry_changed (self, &old);
8926 clutter_actor_queue_relayout (self);
8930 * clutter_actor_set_y:
8931 * @self: a #ClutterActor
8932 * @y: the actor's position on the Y axis
8934 * Sets the actor's Y coordinate, relative to its parent, in pixels.#
8936 * Overrides any layout manager and forces a fixed position for
8942 clutter_actor_set_y (ClutterActor *self,
8945 ClutterActorBox old = { 0, };
8946 ClutterActorPrivate *priv;
8947 ClutterLayoutInfo *info;
8949 g_return_if_fail (CLUTTER_IS_ACTOR (self));
8953 info = _clutter_actor_get_layout_info (self);
8955 if (priv->position_set && info->fixed_y == y)
8958 clutter_actor_store_old_geometry (self, &old);
8961 clutter_actor_set_fixed_position_set (self, TRUE);
8963 clutter_actor_notify_if_geometry_changed (self, &old);
8965 clutter_actor_queue_relayout (self);
8969 * clutter_actor_get_x:
8970 * @self: A #ClutterActor
8972 * Retrieves the X coordinate of a #ClutterActor.
8974 * This function tries to "do what you mean", by returning the
8975 * correct value depending on the actor's state.
8977 * If the actor has a valid allocation, this function will return
8978 * the X coordinate of the origin of the allocation box.
8980 * If the actor has any fixed coordinate set using clutter_actor_set_x(),
8981 * clutter_actor_set_position() or clutter_actor_set_geometry(), this
8982 * function will return that coordinate.
8984 * If both the allocation and a fixed position are missing, this function
8987 * Return value: the X coordinate, in pixels, ignoring any
8988 * transformation (i.e. scaling, rotation)
8991 clutter_actor_get_x (ClutterActor *self)
8993 ClutterActorPrivate *priv;
8995 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
8999 if (priv->needs_allocation)
9001 if (priv->position_set)
9003 const ClutterLayoutInfo *info;
9005 info = _clutter_actor_get_layout_info_or_defaults (self);
9007 return info->fixed_x;
9013 return priv->allocation.x1;
9017 * clutter_actor_get_y:
9018 * @self: A #ClutterActor
9020 * Retrieves the Y coordinate of a #ClutterActor.
9022 * This function tries to "do what you mean", by returning the
9023 * correct value depending on the actor's state.
9025 * If the actor has a valid allocation, this function will return
9026 * the Y coordinate of the origin of the allocation box.
9028 * If the actor has any fixed coordinate set using clutter_actor_set_y(),
9029 * clutter_actor_set_position() or clutter_actor_set_geometry(), this
9030 * function will return that coordinate.
9032 * If both the allocation and a fixed position are missing, this function
9035 * Return value: the Y coordinate, in pixels, ignoring any
9036 * transformation (i.e. scaling, rotation)
9039 clutter_actor_get_y (ClutterActor *self)
9041 ClutterActorPrivate *priv;
9043 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9047 if (priv->needs_allocation)
9049 if (priv->position_set)
9051 const ClutterLayoutInfo *info;
9053 info = _clutter_actor_get_layout_info_or_defaults (self);
9055 return info->fixed_y;
9061 return priv->allocation.y1;
9065 * clutter_actor_set_scale:
9066 * @self: A #ClutterActor
9067 * @scale_x: double factor to scale actor by horizontally.
9068 * @scale_y: double factor to scale actor by vertically.
9070 * Scales an actor with the given factors. The scaling is relative to
9071 * the scale center and the anchor point. The scale center is
9072 * unchanged by this function and defaults to 0,0.
9077 clutter_actor_set_scale (ClutterActor *self,
9081 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9083 g_object_freeze_notify (G_OBJECT (self));
9085 clutter_actor_set_scale_factor (self, CLUTTER_X_AXIS, scale_x);
9086 clutter_actor_set_scale_factor (self, CLUTTER_Y_AXIS, scale_y);
9088 g_object_thaw_notify (G_OBJECT (self));
9092 * clutter_actor_set_scale_full:
9093 * @self: A #ClutterActor
9094 * @scale_x: double factor to scale actor by horizontally.
9095 * @scale_y: double factor to scale actor by vertically.
9096 * @center_x: X coordinate of the center of the scale.
9097 * @center_y: Y coordinate of the center of the scale
9099 * Scales an actor with the given factors around the given center
9100 * point. The center point is specified in pixels relative to the
9101 * anchor point (usually the top left corner of the actor).
9106 clutter_actor_set_scale_full (ClutterActor *self,
9112 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9114 g_object_freeze_notify (G_OBJECT (self));
9116 clutter_actor_set_scale_factor (self, CLUTTER_X_AXIS, scale_x);
9117 clutter_actor_set_scale_factor (self, CLUTTER_Y_AXIS, scale_y);
9118 clutter_actor_set_scale_center (self, CLUTTER_X_AXIS, center_x);
9119 clutter_actor_set_scale_center (self, CLUTTER_Y_AXIS, center_y);
9121 g_object_thaw_notify (G_OBJECT (self));
9125 * clutter_actor_set_scale_with_gravity:
9126 * @self: A #ClutterActor
9127 * @scale_x: double factor to scale actor by horizontally.
9128 * @scale_y: double factor to scale actor by vertically.
9129 * @gravity: the location of the scale center expressed as a compass
9132 * Scales an actor with the given factors around the given
9133 * center point. The center point is specified as one of the compass
9134 * directions in #ClutterGravity. For example, setting it to north
9135 * will cause the top of the actor to remain unchanged and the rest of
9136 * the actor to expand left, right and downwards.
9141 clutter_actor_set_scale_with_gravity (ClutterActor *self,
9144 ClutterGravity gravity)
9146 ClutterTransformInfo *info;
9149 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9151 obj = G_OBJECT (self);
9153 g_object_freeze_notify (obj);
9155 info = _clutter_actor_get_transform_info (self);
9156 info->scale_x = scale_x;
9157 info->scale_y = scale_y;
9159 if (gravity == CLUTTER_GRAVITY_NONE)
9160 clutter_anchor_coord_set_units (&info->scale_center, 0, 0, 0);
9162 clutter_anchor_coord_set_gravity (&info->scale_center, gravity);
9164 self->priv->transform_valid = FALSE;
9166 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_X]);
9167 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_Y]);
9168 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_CENTER_X]);
9169 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_CENTER_Y]);
9170 g_object_notify_by_pspec (obj, obj_props[PROP_SCALE_GRAVITY]);
9172 clutter_actor_queue_redraw (self);
9174 g_object_thaw_notify (obj);
9178 * clutter_actor_get_scale:
9179 * @self: A #ClutterActor
9180 * @scale_x: (out) (allow-none): Location to store horizonal
9181 * scale factor, or %NULL.
9182 * @scale_y: (out) (allow-none): Location to store vertical
9183 * scale factor, or %NULL.
9185 * Retrieves an actors scale factors.
9190 clutter_actor_get_scale (ClutterActor *self,
9194 const ClutterTransformInfo *info;
9196 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9198 info = _clutter_actor_get_transform_info_or_defaults (self);
9201 *scale_x = info->scale_x;
9204 *scale_y = info->scale_y;
9208 * clutter_actor_get_scale_center:
9209 * @self: A #ClutterActor
9210 * @center_x: (out) (allow-none): Location to store the X position
9211 * of the scale center, or %NULL.
9212 * @center_y: (out) (allow-none): Location to store the Y position
9213 * of the scale center, or %NULL.
9215 * Retrieves the scale center coordinate in pixels relative to the top
9216 * left corner of the actor. If the scale center was specified using a
9217 * #ClutterGravity this will calculate the pixel offset using the
9218 * current size of the actor.
9223 clutter_actor_get_scale_center (ClutterActor *self,
9227 const ClutterTransformInfo *info;
9229 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9231 info = _clutter_actor_get_transform_info_or_defaults (self);
9233 clutter_anchor_coord_get_units (self, &info->scale_center,
9240 * clutter_actor_get_scale_gravity:
9241 * @self: A #ClutterActor
9243 * Retrieves the scale center as a compass direction. If the scale
9244 * center was specified in pixels or units this will return
9245 * %CLUTTER_GRAVITY_NONE.
9247 * Return value: the scale gravity
9252 clutter_actor_get_scale_gravity (ClutterActor *self)
9254 const ClutterTransformInfo *info;
9256 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), CLUTTER_GRAVITY_NONE);
9258 info = _clutter_actor_get_transform_info_or_defaults (self);
9260 return clutter_anchor_coord_get_gravity (&info->scale_center);
9264 * clutter_actor_set_opacity:
9265 * @self: A #ClutterActor
9266 * @opacity: New opacity value for the actor.
9268 * Sets the actor's opacity, with zero being completely transparent and
9269 * 255 (0xff) being fully opaque.
9272 clutter_actor_set_opacity (ClutterActor *self,
9275 ClutterActorPrivate *priv;
9277 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9281 if (priv->opacity != opacity)
9283 priv->opacity = opacity;
9285 /* Queue a redraw from the flatten effect so that it can use
9286 its cached image if available instead of having to redraw the
9287 actual actor. If it doesn't end up using the FBO then the
9288 effect is still able to continue the paint anyway. If there
9289 is no flatten effect yet then this is equivalent to queueing
9291 _clutter_actor_queue_redraw_full (self,
9294 priv->flatten_effect);
9296 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_OPACITY]);
9301 * clutter_actor_get_paint_opacity_internal:
9302 * @self: a #ClutterActor
9304 * Retrieves the absolute opacity of the actor, as it appears on the stage
9306 * This function does not do type checks
9308 * Return value: the absolute opacity of the actor
9311 clutter_actor_get_paint_opacity_internal (ClutterActor *self)
9313 ClutterActorPrivate *priv = self->priv;
9314 ClutterActor *parent;
9316 /* override the top-level opacity to always be 255; even in
9317 * case of ClutterStage:use-alpha being TRUE we want the rest
9318 * of the scene to be painted
9320 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
9323 if (priv->opacity_override >= 0)
9324 return priv->opacity_override;
9326 parent = priv->parent;
9328 /* Factor in the actual actors opacity with parents */
9331 guint8 opacity = clutter_actor_get_paint_opacity_internal (parent);
9333 if (opacity != 0xff)
9334 return (opacity * priv->opacity) / 0xff;
9337 return priv->opacity;
9342 * clutter_actor_get_paint_opacity:
9343 * @self: A #ClutterActor
9345 * Retrieves the absolute opacity of the actor, as it appears on the stage.
9347 * This function traverses the hierarchy chain and composites the opacity of
9348 * the actor with that of its parents.
9350 * This function is intended for subclasses to use in the paint virtual
9351 * function, to paint themselves with the correct opacity.
9353 * Return value: The actor opacity value.
9358 clutter_actor_get_paint_opacity (ClutterActor *self)
9360 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9362 return clutter_actor_get_paint_opacity_internal (self);
9366 * clutter_actor_get_opacity:
9367 * @self: a #ClutterActor
9369 * Retrieves the opacity value of an actor, as set by
9370 * clutter_actor_set_opacity().
9372 * For retrieving the absolute opacity of the actor inside a paint
9373 * virtual function, see clutter_actor_get_paint_opacity().
9375 * Return value: the opacity of the actor
9378 clutter_actor_get_opacity (ClutterActor *self)
9380 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9382 return self->priv->opacity;
9386 * clutter_actor_set_offscreen_redirect:
9387 * @self: A #ClutterActor
9388 * @redirect: New offscreen redirect flags for the actor.
9390 * Defines the circumstances where the actor should be redirected into
9391 * an offscreen image. The offscreen image is used to flatten the
9392 * actor into a single image while painting for two main reasons.
9393 * Firstly, when the actor is painted a second time without any of its
9394 * contents changing it can simply repaint the cached image without
9395 * descending further down the actor hierarchy. Secondly, it will make
9396 * the opacity look correct even if there are overlapping primitives
9399 * Caching the actor could in some cases be a performance win and in
9400 * some cases be a performance lose so it is important to determine
9401 * which value is right for an actor before modifying this value. For
9402 * example, there is never any reason to flatten an actor that is just
9403 * a single texture (such as a #ClutterTexture) because it is
9404 * effectively already cached in an image so the offscreen would be
9405 * redundant. Also if the actor contains primitives that are far apart
9406 * with a large transparent area in the middle (such as a large
9407 * CluterGroup with a small actor in the top left and a small actor in
9408 * the bottom right) then the cached image will contain the entire
9409 * image of the large area and the paint will waste time blending all
9410 * of the transparent pixels in the middle.
9412 * The default method of implementing opacity on a container simply
9413 * forwards on the opacity to all of the children. If the children are
9414 * overlapping then it will appear as if they are two separate glassy
9415 * objects and there will be a break in the color where they
9416 * overlap. By redirecting to an offscreen buffer it will be as if the
9417 * two opaque objects are combined into one and then made transparent
9418 * which is usually what is expected.
9420 * The image below demonstrates the difference between redirecting and
9421 * not. The image shows two Clutter groups, each containing a red and
9422 * a green rectangle which overlap. The opacity on the group is set to
9423 * 128 (which is 50%). When the offscreen redirect is not used, the
9424 * red rectangle can be seen through the blue rectangle as if the two
9425 * rectangles were separately transparent. When the redirect is used
9426 * the group as a whole is transparent instead so the red rectangle is
9427 * not visible where they overlap.
9429 * <figure id="offscreen-redirect">
9430 * <title>Sample of using an offscreen redirect for transparency</title>
9431 * <graphic fileref="offscreen-redirect.png" format="PNG"/>
9434 * The default value for this property is 0, so we effectively will
9435 * never redirect an actor offscreen by default. This means that there
9436 * are times that transparent actors may look glassy as described
9437 * above. The reason this is the default is because there is a
9438 * performance trade off between quality and performance here. In many
9439 * cases the default form of glassy opacity looks good enough, but if
9440 * it's not you will need to set the
9441 * %CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY flag to enable
9442 * redirection for opacity.
9444 * Custom actors that don't contain any overlapping primitives are
9445 * recommended to override the has_overlaps() virtual to return %FALSE
9446 * for maximum efficiency.
9451 clutter_actor_set_offscreen_redirect (ClutterActor *self,
9452 ClutterOffscreenRedirect redirect)
9454 ClutterActorPrivate *priv;
9456 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9460 if (priv->offscreen_redirect != redirect)
9462 priv->offscreen_redirect = redirect;
9464 /* Queue a redraw from the effect so that it can use its cached
9465 image if available instead of having to redraw the actual
9466 actor. If it doesn't end up using the FBO then the effect is
9467 still able to continue the paint anyway. If there is no
9468 effect then this is equivalent to queuing a full redraw */
9469 _clutter_actor_queue_redraw_full (self,
9472 priv->flatten_effect);
9474 g_object_notify_by_pspec (G_OBJECT (self),
9475 obj_props[PROP_OFFSCREEN_REDIRECT]);
9480 * clutter_actor_get_offscreen_redirect:
9481 * @self: a #ClutterActor
9483 * Retrieves whether to redirect the actor to an offscreen buffer, as
9484 * set by clutter_actor_set_offscreen_redirect().
9486 * Return value: the value of the offscreen-redirect property of the actor
9490 ClutterOffscreenRedirect
9491 clutter_actor_get_offscreen_redirect (ClutterActor *self)
9493 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9495 return self->priv->offscreen_redirect;
9499 * clutter_actor_set_name:
9500 * @self: A #ClutterActor
9501 * @name: Textual tag to apply to actor
9503 * Sets the given name to @self. The name can be used to identify
9507 clutter_actor_set_name (ClutterActor *self,
9510 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9512 g_free (self->priv->name);
9513 self->priv->name = g_strdup (name);
9515 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_NAME]);
9519 * clutter_actor_get_name:
9520 * @self: A #ClutterActor
9522 * Retrieves the name of @self.
9524 * Return value: the name of the actor, or %NULL. The returned string is
9525 * owned by the actor and should not be modified or freed.
9528 clutter_actor_get_name (ClutterActor *self)
9530 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
9532 return self->priv->name;
9536 * clutter_actor_get_gid:
9537 * @self: A #ClutterActor
9539 * Retrieves the unique id for @self.
9541 * Return value: Globally unique value for this object instance.
9545 * Deprecated: 1.8: The id is not used any longer.
9548 clutter_actor_get_gid (ClutterActor *self)
9550 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9552 return self->priv->id;
9556 * clutter_actor_set_depth:
9557 * @self: a #ClutterActor
9560 * Sets the Z coordinate of @self to @depth.
9562 * The unit used by @depth is dependant on the perspective setup. See
9563 * also clutter_stage_set_perspective().
9566 clutter_actor_set_depth (ClutterActor *self,
9569 ClutterActorPrivate *priv;
9571 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9575 if (priv->z != depth)
9577 /* Sets Z value - XXX 2.0: should we invert? */
9580 priv->transform_valid = FALSE;
9582 /* FIXME - remove this crap; sadly, there are still containers
9583 * in Clutter that depend on this utter brain damage
9585 clutter_container_sort_depth_order (CLUTTER_CONTAINER (self));
9587 clutter_actor_queue_redraw (self);
9589 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_DEPTH]);
9594 * clutter_actor_get_depth:
9595 * @self: a #ClutterActor
9597 * Retrieves the depth of @self.
9599 * Return value: the depth of the actor
9602 clutter_actor_get_depth (ClutterActor *self)
9604 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), -1);
9606 return self->priv->z;
9610 * clutter_actor_set_rotation:
9611 * @self: a #ClutterActor
9612 * @axis: the axis of rotation
9613 * @angle: the angle of rotation
9614 * @x: X coordinate of the rotation center
9615 * @y: Y coordinate of the rotation center
9616 * @z: Z coordinate of the rotation center
9618 * Sets the rotation angle of @self around the given axis.
9620 * The rotation center coordinates used depend on the value of @axis:
9622 * <listitem><para>%CLUTTER_X_AXIS requires @y and @z</para></listitem>
9623 * <listitem><para>%CLUTTER_Y_AXIS requires @x and @z</para></listitem>
9624 * <listitem><para>%CLUTTER_Z_AXIS requires @x and @y</para></listitem>
9627 * The rotation coordinates are relative to the anchor point of the
9628 * actor, set using clutter_actor_set_anchor_point(). If no anchor
9629 * point is set, the upper left corner is assumed as the origin.
9634 clutter_actor_set_rotation (ClutterActor *self,
9635 ClutterRotateAxis axis,
9643 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9649 g_object_freeze_notify (G_OBJECT (self));
9651 clutter_actor_set_rotation_angle_internal (self, axis, angle);
9652 clutter_actor_set_rotation_center_internal (self, axis, &v);
9654 g_object_thaw_notify (G_OBJECT (self));
9658 * clutter_actor_set_z_rotation_from_gravity:
9659 * @self: a #ClutterActor
9660 * @angle: the angle of rotation
9661 * @gravity: the center point of the rotation
9663 * Sets the rotation angle of @self around the Z axis using the center
9664 * point specified as a compass point. For example to rotate such that
9665 * the center of the actor remains static you can use
9666 * %CLUTTER_GRAVITY_CENTER. If the actor changes size the center point
9667 * will move accordingly.
9672 clutter_actor_set_z_rotation_from_gravity (ClutterActor *self,
9674 ClutterGravity gravity)
9676 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9678 if (gravity == CLUTTER_GRAVITY_NONE)
9679 clutter_actor_set_rotation (self, CLUTTER_Z_AXIS, angle, 0, 0, 0);
9682 GObject *obj = G_OBJECT (self);
9683 ClutterTransformInfo *info;
9685 info = _clutter_actor_get_transform_info (self);
9687 g_object_freeze_notify (obj);
9689 clutter_actor_set_rotation_angle_internal (self, CLUTTER_Z_AXIS, angle);
9691 clutter_anchor_coord_set_gravity (&info->rz_center, gravity);
9692 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_Z_GRAVITY]);
9693 g_object_notify_by_pspec (obj, obj_props[PROP_ROTATION_CENTER_Z]);
9695 g_object_thaw_notify (obj);
9700 * clutter_actor_get_rotation:
9701 * @self: a #ClutterActor
9702 * @axis: the axis of rotation
9703 * @x: (out): return value for the X coordinate of the center of rotation
9704 * @y: (out): return value for the Y coordinate of the center of rotation
9705 * @z: (out): return value for the Z coordinate of the center of rotation
9707 * Retrieves the angle and center of rotation on the given axis,
9708 * set using clutter_actor_set_rotation().
9710 * Return value: the angle of rotation
9715 clutter_actor_get_rotation (ClutterActor *self,
9716 ClutterRotateAxis axis,
9721 const ClutterTransformInfo *info;
9722 const AnchorCoord *anchor_coord;
9725 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
9727 info = _clutter_actor_get_transform_info_or_defaults (self);
9731 case CLUTTER_X_AXIS:
9732 anchor_coord = &info->rx_center;
9733 retval = info->rx_angle;
9736 case CLUTTER_Y_AXIS:
9737 anchor_coord = &info->ry_center;
9738 retval = info->ry_angle;
9741 case CLUTTER_Z_AXIS:
9742 anchor_coord = &info->rz_center;
9743 retval = info->rz_angle;
9747 anchor_coord = NULL;
9752 clutter_anchor_coord_get_units (self, anchor_coord, x, y, z);
9758 * clutter_actor_get_z_rotation_gravity:
9759 * @self: A #ClutterActor
9761 * Retrieves the center for the rotation around the Z axis as a
9762 * compass direction. If the center was specified in pixels or units
9763 * this will return %CLUTTER_GRAVITY_NONE.
9765 * Return value: the Z rotation center
9770 clutter_actor_get_z_rotation_gravity (ClutterActor *self)
9772 const ClutterTransformInfo *info;
9774 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0.0);
9776 info = _clutter_actor_get_transform_info_or_defaults (self);
9778 return clutter_anchor_coord_get_gravity (&info->rz_center);
9782 * clutter_actor_set_clip:
9783 * @self: A #ClutterActor
9784 * @xoff: X offset of the clip rectangle
9785 * @yoff: Y offset of the clip rectangle
9786 * @width: Width of the clip rectangle
9787 * @height: Height of the clip rectangle
9789 * Sets clip area for @self. The clip area is always computed from the
9790 * upper left corner of the actor, even if the anchor point is set
9796 clutter_actor_set_clip (ClutterActor *self,
9802 ClutterActorPrivate *priv;
9804 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9808 if (priv->has_clip &&
9809 priv->clip.x == xoff &&
9810 priv->clip.y == yoff &&
9811 priv->clip.width == width &&
9812 priv->clip.height == height)
9815 priv->clip.x = xoff;
9816 priv->clip.y = yoff;
9817 priv->clip.width = width;
9818 priv->clip.height = height;
9820 priv->has_clip = TRUE;
9822 clutter_actor_queue_redraw (self);
9824 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_HAS_CLIP]);
9825 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_CLIP]);
9829 * clutter_actor_remove_clip:
9830 * @self: A #ClutterActor
9832 * Removes clip area from @self.
9835 clutter_actor_remove_clip (ClutterActor *self)
9837 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9839 if (!self->priv->has_clip)
9842 self->priv->has_clip = FALSE;
9844 clutter_actor_queue_redraw (self);
9846 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_HAS_CLIP]);
9850 * clutter_actor_has_clip:
9851 * @self: a #ClutterActor
9853 * Determines whether the actor has a clip area set or not.
9855 * Return value: %TRUE if the actor has a clip area set.
9860 clutter_actor_has_clip (ClutterActor *self)
9862 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
9864 return self->priv->has_clip;
9868 * clutter_actor_get_clip:
9869 * @self: a #ClutterActor
9870 * @xoff: (out) (allow-none): return location for the X offset of
9871 * the clip rectangle, or %NULL
9872 * @yoff: (out) (allow-none): return location for the Y offset of
9873 * the clip rectangle, or %NULL
9874 * @width: (out) (allow-none): return location for the width of
9875 * the clip rectangle, or %NULL
9876 * @height: (out) (allow-none): return location for the height of
9877 * the clip rectangle, or %NULL
9879 * Gets the clip area for @self, if any is set
9884 clutter_actor_get_clip (ClutterActor *self,
9890 ClutterActorPrivate *priv;
9892 g_return_if_fail (CLUTTER_IS_ACTOR (self));
9896 if (!priv->has_clip)
9900 *xoff = priv->clip.x;
9903 *yoff = priv->clip.y;
9906 *width = priv->clip.width;
9909 *height = priv->clip.height;
9913 * clutter_actor_get_children:
9914 * @self: a #ClutterActor
9916 * Retrieves the list of children of @self.
9918 * Return value: (transfer container) (element-type ClutterActor): A newly
9919 * allocated #GList of #ClutterActor<!-- -->s. Use g_list_free() when
9925 clutter_actor_get_children (ClutterActor *self)
9930 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
9932 /* we walk the list backward so that we can use prepend(),
9935 for (iter = self->priv->last_child, res = NULL;
9937 iter = iter->priv->prev_sibling)
9939 res = g_list_prepend (res, iter);
9946 * insert_child_at_depth:
9947 * @self: a #ClutterActor
9948 * @child: a #ClutterActor
9950 * Inserts @child inside the list of children held by @self, using
9951 * the depth as the insertion criteria.
9953 * This sadly makes the insertion not O(1), but we can keep the
9954 * list sorted so that the painters algorithm we use for painting
9955 * the children will work correctly.
9958 insert_child_at_depth (ClutterActor *self,
9959 ClutterActor *child,
9960 gpointer dummy G_GNUC_UNUSED)
9964 child->priv->parent = self;
9966 /* special-case the first child */
9967 if (self->priv->n_children == 0)
9969 self->priv->first_child = child;
9970 self->priv->last_child = child;
9972 child->priv->next_sibling = NULL;
9973 child->priv->prev_sibling = NULL;
9978 /* Find the right place to insert the child so that it will still be
9979 sorted and the child will be after all of the actors at the same
9981 for (iter = self->priv->first_child;
9983 iter = iter->priv->next_sibling)
9985 if (iter->priv->z > child->priv->z)
9991 ClutterActor *tmp = iter->priv->prev_sibling;
9994 tmp->priv->next_sibling = child;
9996 /* Insert the node before the found one */
9997 child->priv->prev_sibling = iter->priv->prev_sibling;
9998 child->priv->next_sibling = iter;
9999 iter->priv->prev_sibling = child;
10003 ClutterActor *tmp = self->priv->last_child;
10006 tmp->priv->next_sibling = child;
10008 /* insert the node at the end of the list */
10009 child->priv->prev_sibling = self->priv->last_child;
10010 child->priv->next_sibling = NULL;
10013 if (child->priv->prev_sibling == NULL)
10014 self->priv->first_child = child;
10016 if (child->priv->next_sibling == NULL)
10017 self->priv->last_child = child;
10021 insert_child_at_index (ClutterActor *self,
10022 ClutterActor *child,
10025 gint index_ = GPOINTER_TO_INT (data_);
10027 child->priv->parent = self;
10031 ClutterActor *tmp = self->priv->first_child;
10034 tmp->priv->prev_sibling = child;
10036 child->priv->prev_sibling = NULL;
10037 child->priv->next_sibling = tmp;
10039 else if (index_ < 0 || index_ >= self->priv->n_children)
10041 ClutterActor *tmp = self->priv->last_child;
10044 tmp->priv->next_sibling = child;
10046 child->priv->prev_sibling = tmp;
10047 child->priv->next_sibling = NULL;
10051 ClutterActor *iter;
10054 for (iter = self->priv->first_child, i = 0;
10056 iter = iter->priv->next_sibling, i += 1)
10060 ClutterActor *tmp = iter->priv->prev_sibling;
10062 child->priv->prev_sibling = tmp;
10063 child->priv->next_sibling = iter;
10065 iter->priv->prev_sibling = child;
10068 tmp->priv->next_sibling = child;
10075 if (child->priv->prev_sibling == NULL)
10076 self->priv->first_child = child;
10078 if (child->priv->next_sibling == NULL)
10079 self->priv->last_child = child;
10083 insert_child_above (ClutterActor *self,
10084 ClutterActor *child,
10087 ClutterActor *sibling = data;
10089 child->priv->parent = self;
10091 if (sibling == NULL)
10092 sibling = self->priv->last_child;
10094 child->priv->prev_sibling = sibling;
10096 if (sibling != NULL)
10098 ClutterActor *tmp = sibling->priv->next_sibling;
10100 child->priv->next_sibling = tmp;
10103 tmp->priv->prev_sibling = child;
10105 sibling->priv->next_sibling = child;
10108 child->priv->next_sibling = NULL;
10110 if (child->priv->prev_sibling == NULL)
10111 self->priv->first_child = child;
10113 if (child->priv->next_sibling == NULL)
10114 self->priv->last_child = child;
10118 insert_child_below (ClutterActor *self,
10119 ClutterActor *child,
10122 ClutterActor *sibling = data;
10124 child->priv->parent = self;
10126 if (sibling == NULL)
10127 sibling = self->priv->first_child;
10129 child->priv->next_sibling = sibling;
10131 if (sibling != NULL)
10133 ClutterActor *tmp = sibling->priv->prev_sibling;
10135 child->priv->prev_sibling = tmp;
10138 tmp->priv->next_sibling = child;
10140 sibling->priv->prev_sibling = child;
10143 child->priv->prev_sibling = NULL;
10145 if (child->priv->prev_sibling == NULL)
10146 self->priv->first_child = child;
10148 if (child->priv->next_sibling == NULL)
10149 self->priv->last_child = child;
10152 typedef void (* ClutterActorAddChildFunc) (ClutterActor *parent,
10153 ClutterActor *child,
10157 ADD_CHILD_CREATE_META = 1 << 0,
10158 ADD_CHILD_EMIT_PARENT_SET = 1 << 1,
10159 ADD_CHILD_EMIT_ACTOR_ADDED = 1 << 2,
10160 ADD_CHILD_CHECK_STATE = 1 << 3,
10161 ADD_CHILD_NOTIFY_FIRST_LAST = 1 << 4,
10163 /* default flags for public API */
10164 ADD_CHILD_DEFAULT_FLAGS = ADD_CHILD_CREATE_META |
10165 ADD_CHILD_EMIT_PARENT_SET |
10166 ADD_CHILD_EMIT_ACTOR_ADDED |
10167 ADD_CHILD_CHECK_STATE |
10168 ADD_CHILD_NOTIFY_FIRST_LAST,
10170 /* flags for legacy/deprecated API */
10171 ADD_CHILD_LEGACY_FLAGS = ADD_CHILD_EMIT_PARENT_SET |
10172 ADD_CHILD_CHECK_STATE |
10173 ADD_CHILD_NOTIFY_FIRST_LAST
10174 } ClutterActorAddChildFlags;
10177 * clutter_actor_add_child_internal:
10178 * @self: a #ClutterActor
10179 * @child: a #ClutterActor
10180 * @flags: control flags for actions
10181 * @add_func: delegate function
10182 * @data: (closure): data to pass to @add_func
10184 * Adds @child to the list of children of @self.
10186 * The actual insertion inside the list is delegated to @add_func: this
10187 * function will just set up the state, perform basic checks, and emit
10190 * The @flags argument is used to perform additional operations.
10193 clutter_actor_add_child_internal (ClutterActor *self,
10194 ClutterActor *child,
10195 ClutterActorAddChildFlags flags,
10196 ClutterActorAddChildFunc add_func,
10199 ClutterTextDirection text_dir;
10200 gboolean create_meta;
10201 gboolean emit_parent_set, emit_actor_added;
10202 gboolean check_state;
10203 gboolean notify_first_last;
10204 ClutterActor *old_first_child, *old_last_child;
10206 if (child->priv->parent != NULL)
10208 g_warning ("The actor '%s' already has a parent, '%s'. You must "
10209 "use clutter_actor_remove_child() first.",
10210 _clutter_actor_get_debug_name (child),
10211 _clutter_actor_get_debug_name (child->priv->parent));
10215 if (CLUTTER_ACTOR_IS_TOPLEVEL (child))
10217 g_warning ("The actor '%s' is a top-level actor, and cannot be "
10218 "a child of another actor.",
10219 _clutter_actor_get_debug_name (child));
10224 /* XXX - this check disallows calling methods that change the stacking
10225 * order within the destruction sequence, by triggering a critical
10226 * warning first, and leaving the actor in an undefined state, which
10227 * then ends up being caught by an assertion.
10229 * the reproducible sequence is:
10231 * - actor gets destroyed;
10232 * - another actor, linked to the first, will try to change the
10233 * stacking order of the first actor;
10234 * - changing the stacking order is a composite operation composed
10235 * by the following steps:
10236 * 1. ref() the child;
10237 * 2. remove_child_internal(), which removes the reference;
10238 * 3. add_child_internal(), which adds a reference;
10239 * - the state of the actor is not changed between (2) and (3), as
10240 * it could be an expensive recomputation;
10241 * - if (3) bails out, then the actor is in an undefined state, but
10243 * - the destruction sequence terminates, but the actor is unparented
10244 * while its state indicates being parented instead.
10245 * - assertion failure.
10247 * the obvious fix would be to decompose each set_child_*_sibling()
10248 * method into proper remove_child()/add_child(), with state validation;
10249 * this may cause excessive work, though, and trigger a cascade of other
10250 * bugs in code that assumes that a change in the stacking order is an
10251 * atomic operation.
10253 * another potential fix is to just remove this check here, and let
10254 * code doing stacking order changes inside the destruction sequence
10255 * of an actor continue doing the work.
10257 * the third fix is to silently bail out early from every
10258 * set_child_*_sibling() and set_child_at_index() method, and avoid
10261 * I have a preference for the second solution, since it involves the
10262 * least amount of work, and the least amount of code duplication.
10264 * see bug: https://bugzilla.gnome.org/show_bug.cgi?id=670647
10266 if (CLUTTER_ACTOR_IN_DESTRUCTION (child))
10268 g_warning ("The actor '%s' is currently being destroyed, and "
10269 "cannot be added as a child of another actor.",
10270 _clutter_actor_get_debug_name (child));
10275 create_meta = (flags & ADD_CHILD_CREATE_META) != 0;
10276 emit_parent_set = (flags & ADD_CHILD_EMIT_PARENT_SET) != 0;
10277 emit_actor_added = (flags & ADD_CHILD_EMIT_ACTOR_ADDED) != 0;
10278 check_state = (flags & ADD_CHILD_CHECK_STATE) != 0;
10279 notify_first_last = (flags & ADD_CHILD_NOTIFY_FIRST_LAST) != 0;
10281 old_first_child = self->priv->first_child;
10282 old_last_child = self->priv->last_child;
10284 g_object_freeze_notify (G_OBJECT (self));
10287 clutter_container_create_child_meta (CLUTTER_CONTAINER (self), child);
10289 g_object_ref_sink (child);
10290 child->priv->parent = NULL;
10291 child->priv->next_sibling = NULL;
10292 child->priv->prev_sibling = NULL;
10294 /* delegate the actual insertion */
10295 add_func (self, child, data);
10297 g_assert (child->priv->parent == self);
10299 self->priv->n_children += 1;
10301 self->priv->age += 1;
10303 /* if push_internal() has been called then we automatically set
10304 * the flag on the actor
10306 if (self->priv->internal_child)
10307 CLUTTER_SET_PRIVATE_FLAGS (child, CLUTTER_INTERNAL_CHILD);
10309 /* clutter_actor_reparent() will emit ::parent-set for us */
10310 if (emit_parent_set && !CLUTTER_ACTOR_IN_REPARENT (child))
10311 g_signal_emit (child, actor_signals[PARENT_SET], 0, NULL);
10315 /* If parent is mapped or realized, we need to also be mapped or
10316 * realized once we're inside the parent.
10318 clutter_actor_update_map_state (child, MAP_STATE_CHECK);
10320 /* propagate the parent's text direction to the child */
10321 text_dir = clutter_actor_get_text_direction (self);
10322 clutter_actor_set_text_direction (child, text_dir);
10325 if (child->priv->show_on_set_parent)
10326 clutter_actor_show (child);
10328 if (CLUTTER_ACTOR_IS_MAPPED (child))
10329 clutter_actor_queue_redraw (child);
10331 /* maintain the invariant that if an actor needs layout,
10332 * its parents do as well
10334 if (child->priv->needs_width_request ||
10335 child->priv->needs_height_request ||
10336 child->priv->needs_allocation)
10338 /* we work around the short-circuiting we do
10339 * in clutter_actor_queue_relayout() since we
10340 * want to force a relayout
10342 child->priv->needs_width_request = TRUE;
10343 child->priv->needs_height_request = TRUE;
10344 child->priv->needs_allocation = TRUE;
10346 clutter_actor_queue_relayout (child->priv->parent);
10349 if (emit_actor_added)
10350 g_signal_emit_by_name (self, "actor-added", child);
10352 if (notify_first_last)
10354 if (old_first_child != self->priv->first_child)
10355 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_FIRST_CHILD]);
10357 if (old_last_child != self->priv->last_child)
10358 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_LAST_CHILD]);
10361 g_object_thaw_notify (G_OBJECT (self));
10365 * clutter_actor_add_child:
10366 * @self: a #ClutterActor
10367 * @child: a #ClutterActor
10369 * Adds @child to the children of @self.
10371 * This function will acquire a reference on @child that will only
10372 * be released when calling clutter_actor_remove_child().
10374 * This function will take into consideration the #ClutterActor:depth
10375 * of @child, and will keep the list of children sorted.
10377 * This function will emit the #ClutterContainer::actor-added signal
10383 clutter_actor_add_child (ClutterActor *self,
10384 ClutterActor *child)
10386 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10387 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10388 g_return_if_fail (self != child);
10389 g_return_if_fail (child->priv->parent == NULL);
10391 clutter_actor_add_child_internal (self, child,
10392 ADD_CHILD_DEFAULT_FLAGS,
10393 insert_child_at_depth,
10398 * clutter_actor_insert_child_at_index:
10399 * @self: a #ClutterActor
10400 * @child: a #ClutterActor
10401 * @index_: the index
10403 * Inserts @child into the list of children of @self, using the
10404 * given @index_. If @index_ is greater than the number of children
10405 * in @self, or is less than 0, then the new child is added at the end.
10407 * This function will acquire a reference on @child that will only
10408 * be released when calling clutter_actor_remove_child().
10410 * This function will not take into consideration the #ClutterActor:depth
10413 * This function will emit the #ClutterContainer::actor-added signal
10419 clutter_actor_insert_child_at_index (ClutterActor *self,
10420 ClutterActor *child,
10423 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10424 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10425 g_return_if_fail (self != child);
10426 g_return_if_fail (child->priv->parent == NULL);
10428 clutter_actor_add_child_internal (self, child,
10429 ADD_CHILD_DEFAULT_FLAGS,
10430 insert_child_at_index,
10431 GINT_TO_POINTER (index_));
10435 * clutter_actor_insert_child_above:
10436 * @self: a #ClutterActor
10437 * @child: a #ClutterActor
10438 * @sibling: (allow-none): a child of @self, or %NULL
10440 * Inserts @child into the list of children of @self, above another
10441 * child of @self or, if @sibling is %NULL, above all the children
10444 * This function will acquire a reference on @child that will only
10445 * be released when calling clutter_actor_remove_child().
10447 * This function will not take into consideration the #ClutterActor:depth
10450 * This function will emit the #ClutterContainer::actor-added signal
10456 clutter_actor_insert_child_above (ClutterActor *self,
10457 ClutterActor *child,
10458 ClutterActor *sibling)
10460 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10461 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10462 g_return_if_fail (self != child);
10463 g_return_if_fail (child != sibling);
10464 g_return_if_fail (child->priv->parent == NULL);
10465 g_return_if_fail (sibling == NULL ||
10466 (CLUTTER_IS_ACTOR (sibling) &&
10467 sibling->priv->parent == self));
10469 clutter_actor_add_child_internal (self, child,
10470 ADD_CHILD_DEFAULT_FLAGS,
10471 insert_child_above,
10476 * clutter_actor_insert_child_below:
10477 * @self: a #ClutterActor
10478 * @child: a #ClutterActor
10479 * @sibling: (allow-none): a child of @self, or %NULL
10481 * Inserts @child into the list of children of @self, below another
10482 * child of @self or, if @sibling is %NULL, below all the children
10485 * This function will acquire a reference on @child that will only
10486 * be released when calling clutter_actor_remove_child().
10488 * This function will not take into consideration the #ClutterActor:depth
10491 * This function will emit the #ClutterContainer::actor-added signal
10497 clutter_actor_insert_child_below (ClutterActor *self,
10498 ClutterActor *child,
10499 ClutterActor *sibling)
10501 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10502 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10503 g_return_if_fail (self != child);
10504 g_return_if_fail (child != sibling);
10505 g_return_if_fail (child->priv->parent == NULL);
10506 g_return_if_fail (sibling == NULL ||
10507 (CLUTTER_IS_ACTOR (sibling) &&
10508 sibling->priv->parent == self));
10510 clutter_actor_add_child_internal (self, child,
10511 ADD_CHILD_DEFAULT_FLAGS,
10512 insert_child_below,
10517 * clutter_actor_set_parent:
10518 * @self: A #ClutterActor
10519 * @parent: A new #ClutterActor parent
10521 * Sets the parent of @self to @parent.
10523 * This function will result in @parent acquiring a reference on @self,
10524 * eventually by sinking its floating reference first. The reference
10525 * will be released by clutter_actor_unparent().
10527 * This function should only be called by legacy #ClutterActor<!-- -->s
10528 * implementing the #ClutterContainer interface.
10530 * Deprecated: 1.10: Use clutter_actor_add_child() instead.
10533 clutter_actor_set_parent (ClutterActor *self,
10534 ClutterActor *parent)
10536 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10537 g_return_if_fail (CLUTTER_IS_ACTOR (parent));
10538 g_return_if_fail (self != parent);
10539 g_return_if_fail (self->priv->parent == NULL);
10541 /* as this function will be called inside ClutterContainer::add
10542 * implementations or when building up a composite actor, we have
10543 * to preserve the old behaviour, and not create child meta or
10544 * emit the ::actor-added signal, to avoid recursion or double
10547 clutter_actor_add_child_internal (parent, self,
10548 ADD_CHILD_LEGACY_FLAGS,
10549 insert_child_at_depth,
10554 * clutter_actor_get_parent:
10555 * @self: A #ClutterActor
10557 * Retrieves the parent of @self.
10559 * Return Value: (transfer none): The #ClutterActor parent, or %NULL
10560 * if no parent is set
10563 clutter_actor_get_parent (ClutterActor *self)
10565 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
10567 return self->priv->parent;
10571 * clutter_actor_get_paint_visibility:
10572 * @self: A #ClutterActor
10574 * Retrieves the 'paint' visibility of an actor recursively checking for non
10577 * This is by definition the same as %CLUTTER_ACTOR_IS_MAPPED.
10579 * Return Value: %TRUE if the actor is visibile and will be painted.
10584 clutter_actor_get_paint_visibility (ClutterActor *actor)
10586 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), FALSE);
10588 return CLUTTER_ACTOR_IS_MAPPED (actor);
10592 * clutter_actor_remove_child:
10593 * @self: a #ClutterActor
10594 * @child: a #ClutterActor
10596 * Removes @child from the children of @self.
10598 * This function will release the reference added by
10599 * clutter_actor_add_child(), so if you want to keep using @child
10600 * you will have to acquire a referenced on it before calling this
10603 * This function will emit the #ClutterContainer::actor-removed
10609 clutter_actor_remove_child (ClutterActor *self,
10610 ClutterActor *child)
10612 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10613 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10614 g_return_if_fail (self != child);
10615 g_return_if_fail (child->priv->parent != NULL);
10616 g_return_if_fail (child->priv->parent == self);
10618 clutter_actor_remove_child_internal (self, child,
10619 REMOVE_CHILD_DEFAULT_FLAGS);
10623 * clutter_actor_remove_all_children:
10624 * @self: a #ClutterActor
10626 * Removes all children of @self.
10628 * This function releases the reference added by inserting a child actor
10629 * in the list of children of @self.
10631 * If the reference count of a child drops to zero, the child will be
10632 * destroyed. If you want to ensure the destruction of all the children
10633 * of @self, use clutter_actor_destroy_all_children().
10638 clutter_actor_remove_all_children (ClutterActor *self)
10640 ClutterActorIter iter;
10642 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10644 if (self->priv->n_children == 0)
10647 g_object_freeze_notify (G_OBJECT (self));
10649 clutter_actor_iter_init (&iter, self);
10650 while (clutter_actor_iter_next (&iter, NULL))
10651 clutter_actor_iter_remove (&iter);
10653 g_object_thaw_notify (G_OBJECT (self));
10656 g_assert (self->priv->first_child == NULL);
10657 g_assert (self->priv->last_child == NULL);
10658 g_assert (self->priv->n_children == 0);
10662 * clutter_actor_destroy_all_children:
10663 * @self: a #ClutterActor
10665 * Destroys all children of @self.
10667 * This function releases the reference added by inserting a child
10668 * actor in the list of children of @self, and ensures that the
10669 * #ClutterActor::destroy signal is emitted on each child of the
10672 * By default, #ClutterActor will emit the #ClutterActor::destroy signal
10673 * when its reference count drops to 0; the default handler of the
10674 * #ClutterActor::destroy signal will destroy all the children of an
10675 * actor. This function ensures that all children are destroyed, instead
10676 * of just removed from @self, unlike clutter_actor_remove_all_children()
10677 * which will merely release the reference and remove each child.
10679 * Unless you acquired an additional reference on each child of @self
10680 * prior to calling clutter_actor_remove_all_children() and want to reuse
10681 * the actors, you should use clutter_actor_destroy_all_children() in
10682 * order to make sure that children are destroyed and signal handlers
10683 * are disconnected even in cases where circular references prevent this
10684 * from automatically happening through reference counting alone.
10689 clutter_actor_destroy_all_children (ClutterActor *self)
10691 ClutterActorIter iter;
10693 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10695 if (self->priv->n_children == 0)
10698 g_object_freeze_notify (G_OBJECT (self));
10700 clutter_actor_iter_init (&iter, self);
10701 while (clutter_actor_iter_next (&iter, NULL))
10702 clutter_actor_iter_destroy (&iter);
10704 g_object_thaw_notify (G_OBJECT (self));
10707 g_assert (self->priv->first_child == NULL);
10708 g_assert (self->priv->last_child == NULL);
10709 g_assert (self->priv->n_children == 0);
10712 typedef struct _InsertBetweenData {
10713 ClutterActor *prev_sibling;
10714 ClutterActor *next_sibling;
10715 } InsertBetweenData;
10718 insert_child_between (ClutterActor *self,
10719 ClutterActor *child,
10722 InsertBetweenData *data = data_;
10723 ClutterActor *prev_sibling = data->prev_sibling;
10724 ClutterActor *next_sibling = data->next_sibling;
10726 child->priv->parent = self;
10727 child->priv->prev_sibling = prev_sibling;
10728 child->priv->next_sibling = next_sibling;
10730 if (prev_sibling != NULL)
10731 prev_sibling->priv->next_sibling = child;
10733 if (next_sibling != NULL)
10734 next_sibling->priv->prev_sibling = child;
10736 if (child->priv->prev_sibling == NULL)
10737 self->priv->first_child = child;
10739 if (child->priv->next_sibling == NULL)
10740 self->priv->last_child = child;
10744 * clutter_actor_replace_child:
10745 * @self: a #ClutterActor
10746 * @old_child: the child of @self to replace
10747 * @new_child: the #ClutterActor to replace @old_child
10749 * Replaces @old_child with @new_child in the list of children of @self.
10754 clutter_actor_replace_child (ClutterActor *self,
10755 ClutterActor *old_child,
10756 ClutterActor *new_child)
10758 ClutterActor *prev_sibling, *next_sibling;
10759 InsertBetweenData clos;
10761 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10762 g_return_if_fail (CLUTTER_IS_ACTOR (old_child));
10763 g_return_if_fail (old_child->priv->parent == self);
10764 g_return_if_fail (CLUTTER_IS_ACTOR (new_child));
10765 g_return_if_fail (old_child != new_child);
10766 g_return_if_fail (new_child != self);
10767 g_return_if_fail (new_child->priv->parent == NULL);
10769 prev_sibling = old_child->priv->prev_sibling;
10770 next_sibling = old_child->priv->next_sibling;
10771 clutter_actor_remove_child_internal (self, old_child,
10772 REMOVE_CHILD_DEFAULT_FLAGS);
10774 clos.prev_sibling = prev_sibling;
10775 clos.next_sibling = next_sibling;
10776 clutter_actor_add_child_internal (self, new_child,
10777 ADD_CHILD_DEFAULT_FLAGS,
10778 insert_child_between,
10783 * clutter_actor_unparent:
10784 * @self: a #ClutterActor
10786 * Removes the parent of @self.
10788 * This will cause the parent of @self to release the reference
10789 * acquired when calling clutter_actor_set_parent(), so if you
10790 * want to keep @self you will have to acquire a reference of
10791 * your own, through g_object_ref().
10793 * This function should only be called by legacy #ClutterActor<!-- -->s
10794 * implementing the #ClutterContainer interface.
10798 * Deprecated: 1.10: Use clutter_actor_remove_child() instead.
10801 clutter_actor_unparent (ClutterActor *self)
10803 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10805 if (self->priv->parent == NULL)
10808 clutter_actor_remove_child_internal (self->priv->parent, self,
10809 REMOVE_CHILD_LEGACY_FLAGS);
10813 * clutter_actor_reparent:
10814 * @self: a #ClutterActor
10815 * @new_parent: the new #ClutterActor parent
10817 * Resets the parent actor of @self.
10819 * This function is logically equivalent to calling clutter_actor_unparent()
10820 * and clutter_actor_set_parent(), but more efficiently implemented, as it
10821 * ensures the child is not finalized when unparented, and emits the
10822 * #ClutterActor::parent-set signal only once.
10824 * In reality, calling this function is less useful than it sounds, as some
10825 * application code may rely on changes in the intermediate state between
10826 * removal and addition of the actor from its old parent to the @new_parent.
10827 * Thus, it is strongly encouraged to avoid using this function in application
10832 * Deprecated: 1.10: Use clutter_actor_remove_child() and
10833 * clutter_actor_add_child() instead; remember to take a reference on
10834 * the actor being removed before calling clutter_actor_remove_child()
10835 * to avoid the reference count dropping to zero and the actor being
10839 clutter_actor_reparent (ClutterActor *self,
10840 ClutterActor *new_parent)
10842 ClutterActorPrivate *priv;
10844 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10845 g_return_if_fail (CLUTTER_IS_ACTOR (new_parent));
10846 g_return_if_fail (self != new_parent);
10848 if (CLUTTER_ACTOR_IS_TOPLEVEL (self))
10850 g_warning ("Cannot set a parent on a toplevel actor");
10854 if (CLUTTER_ACTOR_IN_DESTRUCTION (self))
10856 g_warning ("Cannot set a parent currently being destroyed");
10862 if (priv->parent != new_parent)
10864 ClutterActor *old_parent;
10866 CLUTTER_SET_PRIVATE_FLAGS (self, CLUTTER_IN_REPARENT);
10868 old_parent = priv->parent;
10870 g_object_ref (self);
10872 if (old_parent != NULL)
10874 /* go through the Container implementation if this is a regular
10875 * child and not an internal one
10877 if (!CLUTTER_ACTOR_IS_INTERNAL_CHILD (self))
10879 ClutterContainer *parent = CLUTTER_CONTAINER (old_parent);
10881 /* this will have to call unparent() */
10882 clutter_container_remove_actor (parent, self);
10885 clutter_actor_remove_child_internal (old_parent, self,
10886 REMOVE_CHILD_LEGACY_FLAGS);
10889 /* Note, will call set_parent() */
10890 if (!CLUTTER_ACTOR_IS_INTERNAL_CHILD (self))
10891 clutter_container_add_actor (CLUTTER_CONTAINER (new_parent), self);
10893 clutter_actor_add_child_internal (new_parent, self,
10894 ADD_CHILD_LEGACY_FLAGS,
10895 insert_child_at_depth,
10898 /* we emit the ::parent-set signal once */
10899 g_signal_emit (self, actor_signals[PARENT_SET], 0, old_parent);
10901 CLUTTER_UNSET_PRIVATE_FLAGS (self, CLUTTER_IN_REPARENT);
10903 /* the IN_REPARENT flag suspends state updates */
10904 clutter_actor_update_map_state (self, MAP_STATE_CHECK);
10906 g_object_unref (self);
10911 * clutter_actor_contains:
10912 * @self: A #ClutterActor
10913 * @descendant: A #ClutterActor, possibly contained in @self
10915 * Determines if @descendant is contained inside @self (either as an
10916 * immediate child, or as a deeper descendant). If @self and
10917 * @descendant point to the same actor then it will also return %TRUE.
10919 * Return value: whether @descendent is contained within @self
10924 clutter_actor_contains (ClutterActor *self,
10925 ClutterActor *descendant)
10927 ClutterActor *actor;
10929 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
10930 g_return_val_if_fail (CLUTTER_IS_ACTOR (descendant), FALSE);
10932 for (actor = descendant; actor; actor = actor->priv->parent)
10940 * clutter_actor_set_child_above_sibling:
10941 * @self: a #ClutterActor
10942 * @child: a #ClutterActor child of @self
10943 * @sibling: (allow-none): a #ClutterActor child of @self, or %NULL
10945 * Sets @child to be above @sibling in the list of children of @self.
10947 * If @sibling is %NULL, @child will be the new last child of @self.
10949 * This function is logically equivalent to removing @child and using
10950 * clutter_actor_insert_child_above(), but it will not emit signals
10951 * or change state on @child.
10956 clutter_actor_set_child_above_sibling (ClutterActor *self,
10957 ClutterActor *child,
10958 ClutterActor *sibling)
10960 g_return_if_fail (CLUTTER_IS_ACTOR (self));
10961 g_return_if_fail (CLUTTER_IS_ACTOR (child));
10962 g_return_if_fail (child->priv->parent == self);
10963 g_return_if_fail (child != sibling);
10964 g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
10966 if (sibling != NULL)
10967 g_return_if_fail (sibling->priv->parent == self);
10969 /* we don't want to change the state of child, or emit signals, or
10970 * regenerate ChildMeta instances here, but we still want to follow
10971 * the correct sequence of steps encoded in remove_child() and
10972 * add_child(), so that correctness is ensured, and we only go
10973 * through one known code path.
10975 g_object_ref (child);
10976 clutter_actor_remove_child_internal (self, child, 0);
10977 clutter_actor_add_child_internal (self, child,
10978 ADD_CHILD_NOTIFY_FIRST_LAST,
10979 insert_child_above,
10982 clutter_actor_queue_relayout (self);
10986 * clutter_actor_set_child_below_sibling:
10987 * @self: a #ClutterActor
10988 * @child: a #ClutterActor child of @self
10989 * @sibling: (allow-none): a #ClutterActor child of @self, or %NULL
10991 * Sets @child to be below @sibling in the list of children of @self.
10993 * If @sibling is %NULL, @child will be the new first child of @self.
10995 * This function is logically equivalent to removing @self and using
10996 * clutter_actor_insert_child_below(), but it will not emit signals
10997 * or change state on @child.
11002 clutter_actor_set_child_below_sibling (ClutterActor *self,
11003 ClutterActor *child,
11004 ClutterActor *sibling)
11006 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11007 g_return_if_fail (CLUTTER_IS_ACTOR (child));
11008 g_return_if_fail (child->priv->parent == self);
11009 g_return_if_fail (child != sibling);
11010 g_return_if_fail (sibling == NULL || CLUTTER_IS_ACTOR (sibling));
11012 if (sibling != NULL)
11013 g_return_if_fail (sibling->priv->parent == self);
11015 /* see the comment in set_child_above_sibling() */
11016 g_object_ref (child);
11017 clutter_actor_remove_child_internal (self, child, 0);
11018 clutter_actor_add_child_internal (self, child,
11019 ADD_CHILD_NOTIFY_FIRST_LAST,
11020 insert_child_below,
11023 clutter_actor_queue_relayout (self);
11027 * clutter_actor_set_child_at_index:
11028 * @self: a #ClutterActor
11029 * @child: a #ClutterActor child of @self
11030 * @index_: the new index for @child
11032 * Changes the index of @child in the list of children of @self.
11034 * This function is logically equivalent to removing @child and
11035 * calling clutter_actor_insert_child_at_index(), but it will not
11036 * emit signals or change state on @child.
11041 clutter_actor_set_child_at_index (ClutterActor *self,
11042 ClutterActor *child,
11045 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11046 g_return_if_fail (CLUTTER_IS_ACTOR (child));
11047 g_return_if_fail (child->priv->parent == self);
11048 g_return_if_fail (index_ <= self->priv->n_children);
11050 g_object_ref (child);
11051 clutter_actor_remove_child_internal (self, child, 0);
11052 clutter_actor_add_child_internal (self, child,
11053 ADD_CHILD_NOTIFY_FIRST_LAST,
11054 insert_child_at_index,
11055 GINT_TO_POINTER (index_));
11057 clutter_actor_queue_relayout (self);
11061 * clutter_actor_raise:
11062 * @self: A #ClutterActor
11063 * @below: (allow-none): A #ClutterActor to raise above.
11065 * Puts @self above @below.
11067 * Both actors must have the same parent, and the parent must implement
11068 * the #ClutterContainer interface
11070 * This function calls clutter_container_raise_child() internally.
11072 * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() instead.
11075 clutter_actor_raise (ClutterActor *self,
11076 ClutterActor *below)
11078 ClutterActor *parent;
11080 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11082 parent = clutter_actor_get_parent (self);
11083 if (parent == NULL)
11085 g_warning ("%s: Actor '%s' is not inside a container",
11087 _clutter_actor_get_debug_name (self));
11093 if (parent != clutter_actor_get_parent (below))
11095 g_warning ("%s Actor '%s' is not in the same container as "
11098 _clutter_actor_get_debug_name (self),
11099 _clutter_actor_get_debug_name (below));
11104 clutter_container_raise_child (CLUTTER_CONTAINER (parent), self, below);
11108 * clutter_actor_lower:
11109 * @self: A #ClutterActor
11110 * @above: (allow-none): A #ClutterActor to lower below
11112 * Puts @self below @above.
11114 * Both actors must have the same parent, and the parent must implement
11115 * the #ClutterContainer interface.
11117 * This function calls clutter_container_lower_child() internally.
11119 * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() instead.
11122 clutter_actor_lower (ClutterActor *self,
11123 ClutterActor *above)
11125 ClutterActor *parent;
11127 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11129 parent = clutter_actor_get_parent (self);
11130 if (parent == NULL)
11132 g_warning ("%s: Actor of type %s is not inside a container",
11134 _clutter_actor_get_debug_name (self));
11140 if (parent != clutter_actor_get_parent (above))
11142 g_warning ("%s: Actor '%s' is not in the same container as "
11145 _clutter_actor_get_debug_name (self),
11146 _clutter_actor_get_debug_name (above));
11151 clutter_container_lower_child (CLUTTER_CONTAINER (parent), self, above);
11155 * clutter_actor_raise_top:
11156 * @self: A #ClutterActor
11158 * Raises @self to the top.
11160 * This function calls clutter_actor_raise() internally.
11162 * Deprecated: 1.10: Use clutter_actor_set_child_above_sibling() with
11163 * a %NULL sibling, instead.
11166 clutter_actor_raise_top (ClutterActor *self)
11168 clutter_actor_raise (self, NULL);
11172 * clutter_actor_lower_bottom:
11173 * @self: A #ClutterActor
11175 * Lowers @self to the bottom.
11177 * This function calls clutter_actor_lower() internally.
11179 * Deprecated: 1.10: Use clutter_actor_set_child_below_sibling() with
11180 * a %NULL sibling, instead.
11183 clutter_actor_lower_bottom (ClutterActor *self)
11185 clutter_actor_lower (self, NULL);
11193 * clutter_actor_event:
11194 * @actor: a #ClutterActor
11195 * @event: a #ClutterEvent
11196 * @capture: TRUE if event in in capture phase, FALSE otherwise.
11198 * This function is used to emit an event on the main stage.
11199 * You should rarely need to use this function, except for
11200 * synthetising events.
11202 * Return value: the return value from the signal emission: %TRUE
11203 * if the actor handled the event, or %FALSE if the event was
11209 clutter_actor_event (ClutterActor *actor,
11210 ClutterEvent *event,
11213 gboolean retval = FALSE;
11214 gint signal_num = -1;
11216 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), FALSE);
11217 g_return_val_if_fail (event != NULL, FALSE);
11219 g_object_ref (actor);
11223 g_signal_emit (actor, actor_signals[CAPTURED_EVENT], 0,
11229 g_signal_emit (actor, actor_signals[EVENT], 0, event, &retval);
11233 switch (event->type)
11235 case CLUTTER_NOTHING:
11237 case CLUTTER_BUTTON_PRESS:
11238 signal_num = BUTTON_PRESS_EVENT;
11240 case CLUTTER_BUTTON_RELEASE:
11241 signal_num = BUTTON_RELEASE_EVENT;
11243 case CLUTTER_SCROLL:
11244 signal_num = SCROLL_EVENT;
11246 case CLUTTER_KEY_PRESS:
11247 signal_num = KEY_PRESS_EVENT;
11249 case CLUTTER_KEY_RELEASE:
11250 signal_num = KEY_RELEASE_EVENT;
11252 case CLUTTER_MOTION:
11253 signal_num = MOTION_EVENT;
11255 case CLUTTER_ENTER:
11256 signal_num = ENTER_EVENT;
11258 case CLUTTER_LEAVE:
11259 signal_num = LEAVE_EVENT;
11261 case CLUTTER_DELETE:
11262 case CLUTTER_DESTROY_NOTIFY:
11263 case CLUTTER_CLIENT_MESSAGE:
11269 if (signal_num != -1)
11270 g_signal_emit (actor, actor_signals[signal_num], 0,
11275 g_object_unref (actor);
11281 * clutter_actor_set_reactive:
11282 * @actor: a #ClutterActor
11283 * @reactive: whether the actor should be reactive to events
11285 * Sets @actor as reactive. Reactive actors will receive events.
11290 clutter_actor_set_reactive (ClutterActor *actor,
11293 g_return_if_fail (CLUTTER_IS_ACTOR (actor));
11295 if (reactive == CLUTTER_ACTOR_IS_REACTIVE (actor))
11299 CLUTTER_ACTOR_SET_FLAGS (actor, CLUTTER_ACTOR_REACTIVE);
11301 CLUTTER_ACTOR_UNSET_FLAGS (actor, CLUTTER_ACTOR_REACTIVE);
11303 g_object_notify_by_pspec (G_OBJECT (actor), obj_props[PROP_REACTIVE]);
11307 * clutter_actor_get_reactive:
11308 * @actor: a #ClutterActor
11310 * Checks whether @actor is marked as reactive.
11312 * Return value: %TRUE if the actor is reactive
11317 clutter_actor_get_reactive (ClutterActor *actor)
11319 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), FALSE);
11321 return CLUTTER_ACTOR_IS_REACTIVE (actor) ? TRUE : FALSE;
11325 * clutter_actor_get_anchor_point:
11326 * @self: a #ClutterActor
11327 * @anchor_x: (out): return location for the X coordinate of the anchor point
11328 * @anchor_y: (out): return location for the Y coordinate of the anchor point
11330 * Gets the current anchor point of the @actor in pixels.
11335 clutter_actor_get_anchor_point (ClutterActor *self,
11339 const ClutterTransformInfo *info;
11341 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11343 info = _clutter_actor_get_transform_info_or_defaults (self);
11344 clutter_anchor_coord_get_units (self, &info->anchor,
11351 * clutter_actor_set_anchor_point:
11352 * @self: a #ClutterActor
11353 * @anchor_x: X coordinate of the anchor point
11354 * @anchor_y: Y coordinate of the anchor point
11356 * Sets an anchor point for @self. The anchor point is a point in the
11357 * coordinate space of an actor to which the actor position within its
11358 * parent is relative; the default is (0, 0), i.e. the top-left corner
11364 clutter_actor_set_anchor_point (ClutterActor *self,
11368 ClutterTransformInfo *info;
11369 ClutterActorPrivate *priv;
11370 gboolean changed = FALSE;
11371 gfloat old_anchor_x, old_anchor_y;
11374 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11376 obj = G_OBJECT (self);
11378 info = _clutter_actor_get_transform_info (self);
11380 g_object_freeze_notify (obj);
11382 clutter_anchor_coord_get_units (self, &info->anchor,
11387 if (info->anchor.is_fractional)
11388 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_GRAVITY]);
11390 if (old_anchor_x != anchor_x)
11392 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_X]);
11396 if (old_anchor_y != anchor_y)
11398 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_Y]);
11402 clutter_anchor_coord_set_units (&info->anchor, anchor_x, anchor_y, 0);
11406 priv->transform_valid = FALSE;
11407 clutter_actor_queue_redraw (self);
11410 g_object_thaw_notify (obj);
11414 * clutter_actor_get_anchor_point_gravity:
11415 * @self: a #ClutterActor
11417 * Retrieves the anchor position expressed as a #ClutterGravity. If
11418 * the anchor point was specified using pixels or units this will
11419 * return %CLUTTER_GRAVITY_NONE.
11421 * Return value: the #ClutterGravity used by the anchor point
11426 clutter_actor_get_anchor_point_gravity (ClutterActor *self)
11428 const ClutterTransformInfo *info;
11430 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), CLUTTER_GRAVITY_NONE);
11432 info = _clutter_actor_get_transform_info_or_defaults (self);
11434 return clutter_anchor_coord_get_gravity (&info->anchor);
11438 * clutter_actor_move_anchor_point:
11439 * @self: a #ClutterActor
11440 * @anchor_x: X coordinate of the anchor point
11441 * @anchor_y: Y coordinate of the anchor point
11443 * Sets an anchor point for the actor, and adjusts the actor postion so that
11444 * the relative position of the actor toward its parent remains the same.
11449 clutter_actor_move_anchor_point (ClutterActor *self,
11453 gfloat old_anchor_x, old_anchor_y;
11454 const ClutterTransformInfo *info;
11456 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11458 info = _clutter_actor_get_transform_info (self);
11459 clutter_anchor_coord_get_units (self, &info->anchor,
11464 g_object_freeze_notify (G_OBJECT (self));
11466 clutter_actor_set_anchor_point (self, anchor_x, anchor_y);
11468 if (self->priv->position_set)
11469 clutter_actor_move_by (self,
11470 anchor_x - old_anchor_x,
11471 anchor_y - old_anchor_y);
11473 g_object_thaw_notify (G_OBJECT (self));
11477 * clutter_actor_move_anchor_point_from_gravity:
11478 * @self: a #ClutterActor
11479 * @gravity: #ClutterGravity.
11481 * Sets an anchor point on the actor based on the given gravity, adjusting the
11482 * actor postion so that its relative position within its parent remains
11485 * Since version 1.0 the anchor point will be stored as a gravity so
11486 * that if the actor changes size then the anchor point will move. For
11487 * example, if you set the anchor point to %CLUTTER_GRAVITY_SOUTH_EAST
11488 * and later double the size of the actor, the anchor point will move
11489 * to the bottom right.
11494 clutter_actor_move_anchor_point_from_gravity (ClutterActor *self,
11495 ClutterGravity gravity)
11497 gfloat old_anchor_x, old_anchor_y, new_anchor_x, new_anchor_y;
11498 const ClutterTransformInfo *info;
11499 ClutterActorPrivate *priv;
11501 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11504 info = _clutter_actor_get_transform_info (self);
11506 g_object_freeze_notify (G_OBJECT (self));
11508 clutter_anchor_coord_get_units (self, &info->anchor,
11512 clutter_actor_set_anchor_point_from_gravity (self, gravity);
11513 clutter_anchor_coord_get_units (self, &info->anchor,
11518 if (priv->position_set)
11519 clutter_actor_move_by (self,
11520 new_anchor_x - old_anchor_x,
11521 new_anchor_y - old_anchor_y);
11523 g_object_thaw_notify (G_OBJECT (self));
11527 * clutter_actor_set_anchor_point_from_gravity:
11528 * @self: a #ClutterActor
11529 * @gravity: #ClutterGravity.
11531 * Sets an anchor point on the actor, based on the given gravity (this is a
11532 * convenience function wrapping clutter_actor_set_anchor_point()).
11534 * Since version 1.0 the anchor point will be stored as a gravity so
11535 * that if the actor changes size then the anchor point will move. For
11536 * example, if you set the anchor point to %CLUTTER_GRAVITY_SOUTH_EAST
11537 * and later double the size of the actor, the anchor point will move
11538 * to the bottom right.
11543 clutter_actor_set_anchor_point_from_gravity (ClutterActor *self,
11544 ClutterGravity gravity)
11546 g_return_if_fail (CLUTTER_IS_ACTOR (self));
11548 if (gravity == CLUTTER_GRAVITY_NONE)
11549 clutter_actor_set_anchor_point (self, 0, 0);
11552 GObject *obj = G_OBJECT (self);
11553 ClutterTransformInfo *info;
11555 g_object_freeze_notify (obj);
11557 info = _clutter_actor_get_transform_info (self);
11558 clutter_anchor_coord_set_gravity (&info->anchor, gravity);
11560 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_GRAVITY]);
11561 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_X]);
11562 g_object_notify_by_pspec (obj, obj_props[PROP_ANCHOR_Y]);
11564 self->priv->transform_valid = FALSE;
11566 clutter_actor_queue_redraw (self);
11568 g_object_thaw_notify (obj);
11573 clutter_container_iface_init (ClutterContainerIface *iface)
11575 /* we don't override anything, as ClutterContainer already has a default
11576 * implementation that we can use, and which calls into our own API.
11591 parse_units (ClutterActor *self,
11592 ParseDimension dimension,
11595 GValue value = { 0, };
11598 if (JSON_NODE_TYPE (node) != JSON_NODE_VALUE)
11601 json_node_get_value (node, &value);
11603 if (G_VALUE_HOLDS (&value, G_TYPE_INT64))
11605 retval = (gfloat) g_value_get_int64 (&value);
11607 else if (G_VALUE_HOLDS (&value, G_TYPE_DOUBLE))
11609 retval = g_value_get_double (&value);
11611 else if (G_VALUE_HOLDS (&value, G_TYPE_STRING))
11613 ClutterUnits units;
11616 res = clutter_units_from_string (&units, g_value_get_string (&value));
11618 retval = clutter_units_to_pixels (&units);
11621 g_warning ("Invalid value '%s': integers, strings or floating point "
11622 "values can be used for the x, y, width and height "
11623 "properties. Valid modifiers for strings are 'px', 'mm', "
11625 g_value_get_string (&value));
11631 g_warning ("Invalid value of type '%s': integers, strings of floating "
11632 "point values can be used for the x, y, width, height "
11633 "anchor-x and anchor-y properties.",
11634 g_type_name (G_VALUE_TYPE (&value)));
11637 g_value_unset (&value);
11643 ClutterRotateAxis axis;
11652 static inline gboolean
11653 parse_rotation_array (ClutterActor *actor,
11655 RotationInfo *info)
11659 if (json_array_get_length (array) != 2)
11663 element = json_array_get_element (array, 0);
11664 if (JSON_NODE_TYPE (element) == JSON_NODE_VALUE)
11665 info->angle = json_node_get_double (element);
11670 element = json_array_get_element (array, 1);
11671 if (JSON_NODE_TYPE (element) == JSON_NODE_ARRAY)
11673 JsonArray *center = json_node_get_array (element);
11675 if (json_array_get_length (center) != 2)
11678 switch (info->axis)
11680 case CLUTTER_X_AXIS:
11681 info->center_y = parse_units (actor, PARSE_Y,
11682 json_array_get_element (center, 0));
11683 info->center_z = parse_units (actor, PARSE_Y,
11684 json_array_get_element (center, 1));
11687 case CLUTTER_Y_AXIS:
11688 info->center_x = parse_units (actor, PARSE_X,
11689 json_array_get_element (center, 0));
11690 info->center_z = parse_units (actor, PARSE_X,
11691 json_array_get_element (center, 1));
11694 case CLUTTER_Z_AXIS:
11695 info->center_x = parse_units (actor, PARSE_X,
11696 json_array_get_element (center, 0));
11697 info->center_y = parse_units (actor, PARSE_Y,
11698 json_array_get_element (center, 1));
11707 parse_rotation (ClutterActor *actor,
11709 RotationInfo *info)
11713 gboolean retval = FALSE;
11715 if (JSON_NODE_TYPE (node) != JSON_NODE_ARRAY)
11717 g_warning ("Invalid node of type '%s' found, expecting an array",
11718 json_node_type_name (node));
11722 array = json_node_get_array (node);
11723 len = json_array_get_length (array);
11725 for (i = 0; i < len; i++)
11727 JsonNode *element = json_array_get_element (array, i);
11728 JsonObject *object;
11731 if (JSON_NODE_TYPE (element) != JSON_NODE_OBJECT)
11733 g_warning ("Invalid node of type '%s' found, expecting an object",
11734 json_node_type_name (element));
11738 object = json_node_get_object (element);
11740 if (json_object_has_member (object, "x-axis"))
11742 member = json_object_get_member (object, "x-axis");
11744 info->axis = CLUTTER_X_AXIS;
11746 if (JSON_NODE_TYPE (member) == JSON_NODE_VALUE)
11748 info->angle = json_node_get_double (member);
11751 else if (JSON_NODE_TYPE (member) == JSON_NODE_ARRAY)
11752 retval = parse_rotation_array (actor,
11753 json_node_get_array (member),
11758 else if (json_object_has_member (object, "y-axis"))
11760 member = json_object_get_member (object, "y-axis");
11762 info->axis = CLUTTER_Y_AXIS;
11764 if (JSON_NODE_TYPE (member) == JSON_NODE_VALUE)
11766 info->angle = json_node_get_double (member);
11769 else if (JSON_NODE_TYPE (member) == JSON_NODE_ARRAY)
11770 retval = parse_rotation_array (actor,
11771 json_node_get_array (member),
11776 else if (json_object_has_member (object, "z-axis"))
11778 member = json_object_get_member (object, "z-axis");
11780 info->axis = CLUTTER_Z_AXIS;
11782 if (JSON_NODE_TYPE (member) == JSON_NODE_VALUE)
11784 info->angle = json_node_get_double (member);
11787 else if (JSON_NODE_TYPE (member) == JSON_NODE_ARRAY)
11788 retval = parse_rotation_array (actor,
11789 json_node_get_array (member),
11800 parse_actor_metas (ClutterScript *script,
11801 ClutterActor *actor,
11804 GList *elements, *l;
11805 GSList *retval = NULL;
11807 if (!JSON_NODE_HOLDS_ARRAY (node))
11810 elements = json_array_get_elements (json_node_get_array (node));
11812 for (l = elements; l != NULL; l = l->next)
11814 JsonNode *element = l->data;
11815 const gchar *id_ = _clutter_script_get_id_from_node (element);
11818 if (id_ == NULL || *id_ == '\0')
11821 meta = clutter_script_get_object (script, id_);
11825 retval = g_slist_prepend (retval, meta);
11828 g_list_free (elements);
11830 return g_slist_reverse (retval);
11834 parse_behaviours (ClutterScript *script,
11835 ClutterActor *actor,
11838 GList *elements, *l;
11839 GSList *retval = NULL;
11841 if (!JSON_NODE_HOLDS_ARRAY (node))
11844 elements = json_array_get_elements (json_node_get_array (node));
11846 for (l = elements; l != NULL; l = l->next)
11848 JsonNode *element = l->data;
11849 const gchar *id_ = _clutter_script_get_id_from_node (element);
11850 GObject *behaviour;
11852 if (id_ == NULL || *id_ == '\0')
11855 behaviour = clutter_script_get_object (script, id_);
11856 if (behaviour == NULL)
11859 retval = g_slist_prepend (retval, behaviour);
11862 g_list_free (elements);
11864 return g_slist_reverse (retval);
11868 clutter_actor_parse_custom_node (ClutterScriptable *scriptable,
11869 ClutterScript *script,
11874 ClutterActor *actor = CLUTTER_ACTOR (scriptable);
11875 gboolean retval = FALSE;
11877 if ((name[0] == 'x' && name[1] == '\0') ||
11878 (name[0] == 'y' && name[1] == '\0') ||
11879 (strcmp (name, "width") == 0) ||
11880 (strcmp (name, "height") == 0) ||
11881 (strcmp (name, "anchor_x") == 0) ||
11882 (strcmp (name, "anchor_y") == 0))
11884 ParseDimension dimension;
11887 if (name[0] == 'x')
11888 dimension = PARSE_X;
11889 else if (name[0] == 'y')
11890 dimension = PARSE_Y;
11891 else if (name[0] == 'w')
11892 dimension = PARSE_WIDTH;
11893 else if (name[0] == 'h')
11894 dimension = PARSE_HEIGHT;
11895 else if (name[0] == 'a' && name[7] == 'x')
11896 dimension = PARSE_ANCHOR_X;
11897 else if (name[0] == 'a' && name[7] == 'y')
11898 dimension = PARSE_ANCHOR_Y;
11902 units = parse_units (actor, dimension, node);
11904 /* convert back to pixels: all properties are pixel-based */
11905 g_value_init (value, G_TYPE_FLOAT);
11906 g_value_set_float (value, units);
11910 else if (strcmp (name, "rotation") == 0)
11912 RotationInfo *info;
11914 info = g_slice_new0 (RotationInfo);
11915 retval = parse_rotation (actor, node, info);
11919 g_value_init (value, G_TYPE_POINTER);
11920 g_value_set_pointer (value, info);
11923 g_slice_free (RotationInfo, info);
11925 else if (strcmp (name, "behaviours") == 0)
11929 #ifdef CLUTTER_ENABLE_DEBUG
11930 if (G_UNLIKELY (_clutter_diagnostic_enabled ()))
11931 _clutter_diagnostic_message ("The 'behaviours' key is deprecated "
11932 "and it should not be used in newly "
11933 "written ClutterScript definitions.");
11936 l = parse_behaviours (script, actor, node);
11938 g_value_init (value, G_TYPE_POINTER);
11939 g_value_set_pointer (value, l);
11943 else if (strcmp (name, "actions") == 0 ||
11944 strcmp (name, "constraints") == 0 ||
11945 strcmp (name, "effects") == 0)
11949 l = parse_actor_metas (script, actor, node);
11951 g_value_init (value, G_TYPE_POINTER);
11952 g_value_set_pointer (value, l);
11961 clutter_actor_set_custom_property (ClutterScriptable *scriptable,
11962 ClutterScript *script,
11964 const GValue *value)
11966 ClutterActor *actor = CLUTTER_ACTOR (scriptable);
11968 #ifdef CLUTTER_ENABLE_DEBUG
11969 if (G_UNLIKELY (CLUTTER_HAS_DEBUG (SCRIPT)))
11971 gchar *tmp = g_strdup_value_contents (value);
11973 CLUTTER_NOTE (SCRIPT,
11974 "in ClutterActor::set_custom_property('%s') = %s",
11980 #endif /* CLUTTER_ENABLE_DEBUG */
11982 if (strcmp (name, "rotation") == 0)
11984 RotationInfo *info;
11986 if (!G_VALUE_HOLDS (value, G_TYPE_POINTER))
11989 info = g_value_get_pointer (value);
11991 clutter_actor_set_rotation (actor,
11992 info->axis, info->angle,
11997 g_slice_free (RotationInfo, info);
12002 if (strcmp (name, "behaviours") == 0)
12004 GSList *behaviours, *l;
12006 if (!G_VALUE_HOLDS (value, G_TYPE_POINTER))
12009 behaviours = g_value_get_pointer (value);
12010 for (l = behaviours; l != NULL; l = l->next)
12012 ClutterBehaviour *behaviour = l->data;
12014 clutter_behaviour_apply (behaviour, actor);
12017 g_slist_free (behaviours);
12022 if (strcmp (name, "actions") == 0 ||
12023 strcmp (name, "constraints") == 0 ||
12024 strcmp (name, "effects") == 0)
12028 if (!G_VALUE_HOLDS (value, G_TYPE_POINTER))
12031 metas = g_value_get_pointer (value);
12032 for (l = metas; l != NULL; l = l->next)
12034 if (name[0] == 'a')
12035 clutter_actor_add_action (actor, l->data);
12037 if (name[0] == 'c')
12038 clutter_actor_add_constraint (actor, l->data);
12040 if (name[0] == 'e')
12041 clutter_actor_add_effect (actor, l->data);
12044 g_slist_free (metas);
12049 g_object_set_property (G_OBJECT (scriptable), name, value);
12053 clutter_scriptable_iface_init (ClutterScriptableIface *iface)
12055 iface->parse_custom_node = clutter_actor_parse_custom_node;
12056 iface->set_custom_property = clutter_actor_set_custom_property;
12059 static ClutterActorMeta *
12060 get_meta_from_animation_property (ClutterActor *actor,
12064 ClutterActorPrivate *priv = actor->priv;
12065 ClutterActorMeta *meta = NULL;
12068 /* if this is not a special property, fall through */
12069 if (name[0] != '@')
12072 /* detect the properties named using the following spec:
12074 * @<section>.<meta-name>.<property-name>
12076 * where <section> can be one of the following:
12082 * and <meta-name> is the name set on a specific ActorMeta
12085 tokens = g_strsplit (name + 1, ".", -1);
12086 if (tokens == NULL || g_strv_length (tokens) != 3)
12088 CLUTTER_NOTE (ANIMATION, "Invalid property name '%s'",
12090 g_strfreev (tokens);
12094 if (strcmp (tokens[0], "actions") == 0)
12095 meta = _clutter_meta_group_get_meta (priv->actions, tokens[1]);
12097 if (strcmp (tokens[0], "constraints") == 0)
12098 meta = _clutter_meta_group_get_meta (priv->constraints, tokens[1]);
12100 if (strcmp (tokens[0], "effects") == 0)
12101 meta = _clutter_meta_group_get_meta (priv->effects, tokens[1]);
12103 if (name_p != NULL)
12104 *name_p = g_strdup (tokens[2]);
12106 CLUTTER_NOTE (ANIMATION,
12107 "Looking for property '%s' of object '%s' in section '%s'",
12112 g_strfreev (tokens);
12117 static GParamSpec *
12118 clutter_actor_find_property (ClutterAnimatable *animatable,
12119 const gchar *property_name)
12121 ClutterActorMeta *meta = NULL;
12122 GObjectClass *klass = NULL;
12123 GParamSpec *pspec = NULL;
12124 gchar *p_name = NULL;
12126 meta = get_meta_from_animation_property (CLUTTER_ACTOR (animatable),
12132 klass = G_OBJECT_GET_CLASS (meta);
12134 pspec = g_object_class_find_property (klass, p_name);
12138 klass = G_OBJECT_GET_CLASS (animatable);
12140 pspec = g_object_class_find_property (klass, property_name);
12149 clutter_actor_get_initial_state (ClutterAnimatable *animatable,
12150 const gchar *property_name,
12153 ClutterActorMeta *meta = NULL;
12154 gchar *p_name = NULL;
12156 meta = get_meta_from_animation_property (CLUTTER_ACTOR (animatable),
12161 g_object_get_property (G_OBJECT (meta), p_name, initial);
12163 g_object_get_property (G_OBJECT (animatable), property_name, initial);
12169 clutter_actor_set_final_state (ClutterAnimatable *animatable,
12170 const gchar *property_name,
12171 const GValue *final)
12173 ClutterActorMeta *meta = NULL;
12174 gchar *p_name = NULL;
12176 meta = get_meta_from_animation_property (CLUTTER_ACTOR (animatable),
12180 g_object_set_property (G_OBJECT (meta), p_name, final);
12182 g_object_set_property (G_OBJECT (animatable), property_name, final);
12188 clutter_animatable_iface_init (ClutterAnimatableIface *iface)
12190 iface->find_property = clutter_actor_find_property;
12191 iface->get_initial_state = clutter_actor_get_initial_state;
12192 iface->set_final_state = clutter_actor_set_final_state;
12196 * clutter_actor_transform_stage_point:
12197 * @self: A #ClutterActor
12198 * @x: (in): x screen coordinate of the point to unproject
12199 * @y: (in): y screen coordinate of the point to unproject
12200 * @x_out: (out): return location for the unprojected x coordinance
12201 * @y_out: (out): return location for the unprojected y coordinance
12203 * This function translates screen coordinates (@x, @y) to
12204 * coordinates relative to the actor. For example, it can be used to translate
12205 * screen events from global screen coordinates into actor-local coordinates.
12207 * The conversion can fail, notably if the transform stack results in the
12208 * actor being projected on the screen as a mere line.
12210 * The conversion should not be expected to be pixel-perfect due to the
12211 * nature of the operation. In general the error grows when the skewing
12212 * of the actor rectangle on screen increases.
12214 * <note><para>This function can be computationally intensive.</para></note>
12216 * <note><para>This function only works when the allocation is up-to-date,
12217 * i.e. inside of paint().</para></note>
12219 * Return value: %TRUE if conversion was successful.
12224 clutter_actor_transform_stage_point (ClutterActor *self,
12230 ClutterVertex v[4];
12233 int du, dv, xi, yi;
12235 float xf, yf, wf, det;
12236 ClutterActorPrivate *priv;
12238 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
12242 /* This implementation is based on the quad -> quad projection algorithm
12243 * described by Paul Heckbert in:
12245 * http://www.cs.cmu.edu/~ph/texfund/texfund.pdf
12247 * and the sample implementation at:
12249 * http://www.cs.cmu.edu/~ph/src/texfund/
12251 * Our texture is a rectangle with origin [0, 0], so we are mapping from
12252 * quad to rectangle only, which significantly simplifies things; the
12253 * function calls have been unrolled, and most of the math is done in fixed
12257 clutter_actor_get_abs_allocation_vertices (self, v);
12259 /* Keeping these as ints simplifies the multiplication (no significant
12260 * loss of precision here).
12262 du = (int) (priv->allocation.x2 - priv->allocation.x1);
12263 dv = (int) (priv->allocation.y2 - priv->allocation.y1);
12268 #define UX2FP(x) (x)
12269 #define DET2FP(a,b,c,d) (((a) * (d)) - ((b) * (c)))
12271 /* First, find mapping from unit uv square to xy quadrilateral; this
12272 * equivalent to the pmap_square_quad() functions in the sample
12273 * implementation, which we can simplify, since our target is always
12276 px = v[0].x - v[1].x + v[3].x - v[2].x;
12277 py = v[0].y - v[1].y + v[3].y - v[2].y;
12281 /* affine transform */
12282 RQ[0][0] = UX2FP (v[1].x - v[0].x);
12283 RQ[1][0] = UX2FP (v[3].x - v[1].x);
12284 RQ[2][0] = UX2FP (v[0].x);
12285 RQ[0][1] = UX2FP (v[1].y - v[0].y);
12286 RQ[1][1] = UX2FP (v[3].y - v[1].y);
12287 RQ[2][1] = UX2FP (v[0].y);
12294 /* projective transform */
12295 double dx1, dx2, dy1, dy2, del;
12297 dx1 = UX2FP (v[1].x - v[3].x);
12298 dx2 = UX2FP (v[2].x - v[3].x);
12299 dy1 = UX2FP (v[1].y - v[3].y);
12300 dy2 = UX2FP (v[2].y - v[3].y);
12302 del = DET2FP (dx1, dx2, dy1, dy2);
12307 * The division here needs to be done in floating point for
12308 * precisions reasons.
12310 RQ[0][2] = (DET2FP (UX2FP (px), dx2, UX2FP (py), dy2) / del);
12311 RQ[1][2] = (DET2FP (dx1, UX2FP (px), dy1, UX2FP (py)) / del);
12312 RQ[1][2] = (DET2FP (dx1, UX2FP (px), dy1, UX2FP (py)) / del);
12314 RQ[0][0] = UX2FP (v[1].x - v[0].x) + (RQ[0][2] * UX2FP (v[1].x));
12315 RQ[1][0] = UX2FP (v[2].x - v[0].x) + (RQ[1][2] * UX2FP (v[2].x));
12316 RQ[2][0] = UX2FP (v[0].x);
12317 RQ[0][1] = UX2FP (v[1].y - v[0].y) + (RQ[0][2] * UX2FP (v[1].y));
12318 RQ[1][1] = UX2FP (v[2].y - v[0].y) + (RQ[1][2] * UX2FP (v[2].y));
12319 RQ[2][1] = UX2FP (v[0].y);
12323 * Now combine with transform from our rectangle (u0,v0,u1,v1) to unit
12324 * square. Since our rectangle is based at 0,0 we only need to scale.
12334 * Now RQ is transform from uv rectangle to xy quadrilateral; we need an
12337 ST[0][0] = DET2FP (RQ[1][1], RQ[1][2], RQ[2][1], RQ[2][2]);
12338 ST[1][0] = DET2FP (RQ[1][2], RQ[1][0], RQ[2][2], RQ[2][0]);
12339 ST[2][0] = DET2FP (RQ[1][0], RQ[1][1], RQ[2][0], RQ[2][1]);
12340 ST[0][1] = DET2FP (RQ[2][1], RQ[2][2], RQ[0][1], RQ[0][2]);
12341 ST[1][1] = DET2FP (RQ[2][2], RQ[2][0], RQ[0][2], RQ[0][0]);
12342 ST[2][1] = DET2FP (RQ[2][0], RQ[2][1], RQ[0][0], RQ[0][1]);
12343 ST[0][2] = DET2FP (RQ[0][1], RQ[0][2], RQ[1][1], RQ[1][2]);
12344 ST[1][2] = DET2FP (RQ[0][2], RQ[0][0], RQ[1][2], RQ[1][0]);
12345 ST[2][2] = DET2FP (RQ[0][0], RQ[0][1], RQ[1][0], RQ[1][1]);
12348 * Check the resulting matrix is OK.
12350 det = (RQ[0][0] * ST[0][0])
12351 + (RQ[0][1] * ST[0][1])
12352 + (RQ[0][2] * ST[0][2]);
12357 * Now transform our point with the ST matrix; the notional w
12358 * coordinate is 1, hence the last part is simply added.
12363 xf = xi * ST[0][0] + yi * ST[1][0] + ST[2][0];
12364 yf = xi * ST[0][1] + yi * ST[1][1] + ST[2][1];
12365 wf = xi * ST[0][2] + yi * ST[1][2] + ST[2][2];
12383 static ClutterGeometry*
12384 clutter_geometry_copy (const ClutterGeometry *geometry)
12386 return g_slice_dup (ClutterGeometry, geometry);
12390 clutter_geometry_free (ClutterGeometry *geometry)
12392 if (G_LIKELY (geometry != NULL))
12393 g_slice_free (ClutterGeometry, geometry);
12397 * clutter_geometry_union:
12398 * @geometry_a: a #ClutterGeometry
12399 * @geometry_b: another #ClutterGeometry
12400 * @result: (out): location to store the result
12402 * Find the union of two rectangles represented as #ClutterGeometry.
12407 clutter_geometry_union (const ClutterGeometry *geometry_a,
12408 const ClutterGeometry *geometry_b,
12409 ClutterGeometry *result)
12411 /* We don't try to handle rectangles that can't be represented
12412 * as a signed integer box */
12413 gint x_1 = MIN (geometry_a->x, geometry_b->x);
12414 gint y_1 = MIN (geometry_a->y, geometry_b->y);
12415 gint x_2 = MAX (geometry_a->x + (gint)geometry_a->width,
12416 geometry_b->x + (gint)geometry_b->width);
12417 gint y_2 = MAX (geometry_a->y + (gint)geometry_a->height,
12418 geometry_b->y + (gint)geometry_b->height);
12421 result->width = x_2 - x_1;
12422 result->height = y_2 - y_1;
12426 * clutter_geometry_intersects:
12427 * @geometry0: The first geometry to test
12428 * @geometry1: The second geometry to test
12430 * Determines if @geometry0 and geometry1 intersect returning %TRUE if
12431 * they do else %FALSE.
12433 * Return value: %TRUE of @geometry0 and geometry1 intersect else
12439 clutter_geometry_intersects (const ClutterGeometry *geometry0,
12440 const ClutterGeometry *geometry1)
12442 if (geometry1->x >= (geometry0->x + (gint)geometry0->width) ||
12443 geometry1->y >= (geometry0->y + (gint)geometry0->height) ||
12444 (geometry1->x + (gint)geometry1->width) <= geometry0->x ||
12445 (geometry1->y + (gint)geometry1->height) <= geometry0->y)
12452 clutter_geometry_progress (const GValue *a,
12457 const ClutterGeometry *a_geom = g_value_get_boxed (a);
12458 const ClutterGeometry *b_geom = g_value_get_boxed (b);
12459 ClutterGeometry res = { 0, };
12460 gint a_width = a_geom->width;
12461 gint b_width = b_geom->width;
12462 gint a_height = a_geom->height;
12463 gint b_height = b_geom->height;
12465 res.x = a_geom->x + (b_geom->x - a_geom->x) * progress;
12466 res.y = a_geom->y + (b_geom->y - a_geom->y) * progress;
12468 res.width = a_width + (b_width - a_width) * progress;
12469 res.height = a_height + (b_height - a_height) * progress;
12471 g_value_set_boxed (retval, &res);
12476 G_DEFINE_BOXED_TYPE_WITH_CODE (ClutterGeometry, clutter_geometry,
12477 clutter_geometry_copy,
12478 clutter_geometry_free,
12479 CLUTTER_REGISTER_INTERVAL_PROGRESS (clutter_geometry_progress));
12486 * clutter_vertex_new:
12491 * Creates a new #ClutterVertex for the point in 3D space
12492 * identified by the 3 coordinates @x, @y, @z
12494 * Return value: the newly allocate #ClutterVertex. Use
12495 * clutter_vertex_free() to free the resources
12500 clutter_vertex_new (gfloat x,
12504 ClutterVertex *vertex;
12506 vertex = g_slice_new (ClutterVertex);
12515 * clutter_vertex_copy:
12516 * @vertex: a #ClutterVertex
12520 * Return value: a newly allocated copy of #ClutterVertex. Use
12521 * clutter_vertex_free() to free the allocated resources
12526 clutter_vertex_copy (const ClutterVertex *vertex)
12528 if (G_LIKELY (vertex != NULL))
12529 return g_slice_dup (ClutterVertex, vertex);
12535 * clutter_vertex_free:
12536 * @vertex: a #ClutterVertex
12538 * Frees a #ClutterVertex allocated using clutter_vertex_copy()
12543 clutter_vertex_free (ClutterVertex *vertex)
12545 if (G_UNLIKELY (vertex != NULL))
12546 g_slice_free (ClutterVertex, vertex);
12550 * clutter_vertex_equal:
12551 * @vertex_a: a #ClutterVertex
12552 * @vertex_b: a #ClutterVertex
12554 * Compares @vertex_a and @vertex_b for equality
12556 * Return value: %TRUE if the passed #ClutterVertex are equal
12561 clutter_vertex_equal (const ClutterVertex *vertex_a,
12562 const ClutterVertex *vertex_b)
12564 g_return_val_if_fail (vertex_a != NULL && vertex_b != NULL, FALSE);
12566 if (vertex_a == vertex_b)
12569 return vertex_a->x == vertex_b->x &&
12570 vertex_a->y == vertex_b->y &&
12571 vertex_a->z == vertex_b->z;
12575 clutter_vertex_progress (const GValue *a,
12580 const ClutterVertex *av = g_value_get_boxed (a);
12581 const ClutterVertex *bv = g_value_get_boxed (b);
12582 ClutterVertex res = { 0, };
12584 res.x = av->x + (bv->x - av->x) * progress;
12585 res.y = av->y + (bv->y - av->y) * progress;
12586 res.z = av->z + (bv->z - av->z) * progress;
12588 g_value_set_boxed (retval, &res);
12593 G_DEFINE_BOXED_TYPE_WITH_CODE (ClutterVertex, clutter_vertex,
12594 clutter_vertex_copy,
12595 clutter_vertex_free,
12596 CLUTTER_REGISTER_INTERVAL_PROGRESS (clutter_vertex_progress));
12599 * clutter_actor_is_rotated:
12600 * @self: a #ClutterActor
12602 * Checks whether any rotation is applied to the actor.
12604 * Return value: %TRUE if the actor is rotated.
12609 clutter_actor_is_rotated (ClutterActor *self)
12611 const ClutterTransformInfo *info;
12613 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
12615 info = _clutter_actor_get_transform_info_or_defaults (self);
12617 if (info->rx_angle || info->ry_angle || info->rz_angle)
12624 * clutter_actor_is_scaled:
12625 * @self: a #ClutterActor
12627 * Checks whether the actor is scaled in either dimension.
12629 * Return value: %TRUE if the actor is scaled.
12634 clutter_actor_is_scaled (ClutterActor *self)
12636 const ClutterTransformInfo *info;
12638 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
12640 info = _clutter_actor_get_transform_info_or_defaults (self);
12642 if (info->scale_x != 1.0 || info->scale_y != 1.0)
12649 _clutter_actor_get_stage_internal (ClutterActor *actor)
12651 while (actor && !CLUTTER_ACTOR_IS_TOPLEVEL (actor))
12652 actor = actor->priv->parent;
12658 * clutter_actor_get_stage:
12659 * @actor: a #ClutterActor
12661 * Retrieves the #ClutterStage where @actor is contained.
12663 * Return value: (transfer none) (type Clutter.Stage): the stage
12664 * containing the actor, or %NULL
12669 clutter_actor_get_stage (ClutterActor *actor)
12671 g_return_val_if_fail (CLUTTER_IS_ACTOR (actor), NULL);
12673 return _clutter_actor_get_stage_internal (actor);
12677 * clutter_actor_allocate_available_size:
12678 * @self: a #ClutterActor
12679 * @x: the actor's X coordinate
12680 * @y: the actor's Y coordinate
12681 * @available_width: the maximum available width, or -1 to use the
12682 * actor's natural width
12683 * @available_height: the maximum available height, or -1 to use the
12684 * actor's natural height
12685 * @flags: flags controlling the allocation
12687 * Allocates @self taking into account the #ClutterActor<!-- -->'s
12688 * preferred size, but limiting it to the maximum available width
12689 * and height provided.
12691 * This function will do the right thing when dealing with the
12692 * actor's request mode.
12694 * The implementation of this function is equivalent to:
12697 * if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
12699 * clutter_actor_get_preferred_width (self, available_height,
12701 * &natural_width);
12702 * width = CLAMP (natural_width, min_width, available_width);
12704 * clutter_actor_get_preferred_height (self, width,
12706 * &natural_height);
12707 * height = CLAMP (natural_height, min_height, available_height);
12711 * clutter_actor_get_preferred_height (self, available_width,
12713 * &natural_height);
12714 * height = CLAMP (natural_height, min_height, available_height);
12716 * clutter_actor_get_preferred_width (self, height,
12718 * &natural_width);
12719 * width = CLAMP (natural_width, min_width, available_width);
12722 * box.x1 = x; box.y1 = y;
12723 * box.x2 = box.x1 + available_width;
12724 * box.y2 = box.y1 + available_height;
12725 * clutter_actor_allocate (self, &box, flags);
12728 * This function can be used by fluid layout managers to allocate
12729 * an actor's preferred size without making it bigger than the area
12730 * available for the container.
12735 clutter_actor_allocate_available_size (ClutterActor *self,
12738 gfloat available_width,
12739 gfloat available_height,
12740 ClutterAllocationFlags flags)
12742 ClutterActorPrivate *priv;
12743 gfloat width, height;
12744 gfloat min_width, min_height;
12745 gfloat natural_width, natural_height;
12746 ClutterActorBox box;
12748 g_return_if_fail (CLUTTER_IS_ACTOR (self));
12752 width = height = 0.0;
12754 switch (priv->request_mode)
12756 case CLUTTER_REQUEST_HEIGHT_FOR_WIDTH:
12757 clutter_actor_get_preferred_width (self, available_height,
12760 width = CLAMP (natural_width, min_width, available_width);
12762 clutter_actor_get_preferred_height (self, width,
12765 height = CLAMP (natural_height, min_height, available_height);
12768 case CLUTTER_REQUEST_WIDTH_FOR_HEIGHT:
12769 clutter_actor_get_preferred_height (self, available_width,
12772 height = CLAMP (natural_height, min_height, available_height);
12774 clutter_actor_get_preferred_width (self, height,
12777 width = CLAMP (natural_width, min_width, available_width);
12784 box.x2 = box.x1 + width;
12785 box.y2 = box.y1 + height;
12786 clutter_actor_allocate (self, &box, flags);
12790 * clutter_actor_allocate_preferred_size:
12791 * @self: a #ClutterActor
12792 * @flags: flags controlling the allocation
12794 * Allocates the natural size of @self.
12796 * This function is a utility call for #ClutterActor implementations
12797 * that allocates the actor's preferred natural size. It can be used
12798 * by fixed layout managers (like #ClutterGroup or so called
12799 * 'composite actors') inside the ClutterActor::allocate
12800 * implementation to give each child exactly how much space it
12803 * This function is not meant to be used by applications. It is also
12804 * not meant to be used outside the implementation of the
12805 * ClutterActor::allocate virtual function.
12810 clutter_actor_allocate_preferred_size (ClutterActor *self,
12811 ClutterAllocationFlags flags)
12813 gfloat actor_x, actor_y;
12814 gfloat natural_width, natural_height;
12815 ClutterActorBox actor_box;
12817 g_return_if_fail (CLUTTER_IS_ACTOR (self));
12819 actor_x = clutter_actor_get_x (self);
12820 actor_y = clutter_actor_get_y (self);
12822 clutter_actor_get_preferred_size (self,
12827 actor_box.x1 = actor_x;
12828 actor_box.y1 = actor_y;
12829 actor_box.x2 = actor_box.x1 + natural_width;
12830 actor_box.y2 = actor_box.y1 + natural_height;
12832 clutter_actor_allocate (self, &actor_box, flags);
12836 * clutter_actor_allocate_align_fill:
12837 * @self: a #ClutterActor
12838 * @box: a #ClutterActorBox, containing the available width and height
12839 * @x_align: the horizontal alignment, between 0 and 1
12840 * @y_align: the vertical alignment, between 0 and 1
12841 * @x_fill: whether the actor should fill horizontally
12842 * @y_fill: whether the actor should fill vertically
12843 * @flags: allocation flags to be passed to clutter_actor_allocate()
12845 * Allocates @self by taking into consideration the available allocation
12846 * area; an alignment factor on either axis; and whether the actor should
12847 * fill the allocation on either axis.
12849 * The @box should contain the available allocation width and height;
12850 * if the x1 and y1 members of #ClutterActorBox are not set to 0, the
12851 * allocation will be offset by their value.
12853 * This function takes into consideration the geometry request specified by
12854 * the #ClutterActor:request-mode property, and the text direction.
12856 * This function is useful for fluid layout managers, like #ClutterBinLayout
12857 * or #ClutterTableLayout
12862 clutter_actor_allocate_align_fill (ClutterActor *self,
12863 const ClutterActorBox *box,
12868 ClutterAllocationFlags flags)
12870 ClutterActorPrivate *priv;
12871 ClutterActorBox allocation = { 0, };
12872 gfloat x_offset, y_offset;
12873 gfloat available_width, available_height;
12874 gfloat child_width, child_height;
12876 g_return_if_fail (CLUTTER_IS_ACTOR (self));
12877 g_return_if_fail (box != NULL);
12878 g_return_if_fail (x_align >= 0.0 && x_align <= 1.0);
12879 g_return_if_fail (y_align >= 0.0 && y_align <= 1.0);
12883 clutter_actor_box_get_origin (box, &x_offset, &y_offset);
12884 clutter_actor_box_get_size (box, &available_width, &available_height);
12886 if (available_width < 0)
12887 available_width = 0;
12889 if (available_height < 0)
12890 available_height = 0;
12894 allocation.x1 = x_offset;
12895 allocation.x2 = allocation.x1 + available_width;
12900 allocation.y1 = y_offset;
12901 allocation.y2 = allocation.y1 + available_height;
12904 /* if we are filling horizontally and vertically then we're done */
12905 if (x_fill && y_fill)
12908 child_width = child_height = 0.0f;
12910 if (priv->request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
12912 gfloat min_width, natural_width;
12913 gfloat min_height, natural_height;
12915 clutter_actor_get_preferred_width (self, available_height,
12919 child_width = CLAMP (natural_width, min_width, available_width);
12923 clutter_actor_get_preferred_height (self, child_width,
12927 child_height = CLAMP (natural_height, min_height, available_height);
12932 gfloat min_width, natural_width;
12933 gfloat min_height, natural_height;
12935 clutter_actor_get_preferred_height (self, available_width,
12939 child_height = CLAMP (natural_height, min_height, available_height);
12943 clutter_actor_get_preferred_width (self, child_height,
12947 child_width = CLAMP (natural_width, min_width, available_width);
12951 /* invert the horizontal alignment for RTL languages */
12952 if (priv->text_direction == CLUTTER_TEXT_DIRECTION_RTL)
12953 x_align = 1.0 - x_align;
12957 allocation.x1 = x_offset
12958 + ((available_width - child_width) * x_align);
12959 allocation.x2 = allocation.x1 + child_width;
12964 allocation.y1 = y_offset
12965 + ((available_height - child_height) * y_align);
12966 allocation.y2 = allocation.y1 + child_height;
12970 clutter_actor_box_clamp_to_pixel (&allocation);
12971 clutter_actor_allocate (self, &allocation, flags);
12975 * clutter_actor_grab_key_focus:
12976 * @self: a #ClutterActor
12978 * Sets the key focus of the #ClutterStage including @self
12979 * to this #ClutterActor.
12984 clutter_actor_grab_key_focus (ClutterActor *self)
12986 ClutterActor *stage;
12988 g_return_if_fail (CLUTTER_IS_ACTOR (self));
12990 stage = _clutter_actor_get_stage_internal (self);
12992 clutter_stage_set_key_focus (CLUTTER_STAGE (stage), self);
12996 * clutter_actor_get_pango_context:
12997 * @self: a #ClutterActor
12999 * Retrieves the #PangoContext for @self. The actor's #PangoContext
13000 * is already configured using the appropriate font map, resolution
13001 * and font options.
13003 * Unlike clutter_actor_create_pango_context(), this context is owend
13004 * by the #ClutterActor and it will be updated each time the options
13005 * stored by the #ClutterBackend change.
13007 * You can use the returned #PangoContext to create a #PangoLayout
13008 * and render text using cogl_pango_render_layout() to reuse the
13009 * glyphs cache also used by Clutter.
13011 * Return value: (transfer none): the #PangoContext for a #ClutterActor.
13012 * The returned #PangoContext is owned by the actor and should not be
13013 * unreferenced by the application code
13018 clutter_actor_get_pango_context (ClutterActor *self)
13020 ClutterActorPrivate *priv;
13022 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
13026 if (priv->pango_context != NULL)
13027 return priv->pango_context;
13029 priv->pango_context = _clutter_context_get_pango_context ();
13030 g_object_ref (priv->pango_context);
13032 return priv->pango_context;
13036 * clutter_actor_create_pango_context:
13037 * @self: a #ClutterActor
13039 * Creates a #PangoContext for the given actor. The #PangoContext
13040 * is already configured using the appropriate font map, resolution
13041 * and font options.
13043 * See also clutter_actor_get_pango_context().
13045 * Return value: (transfer full): the newly created #PangoContext.
13046 * Use g_object_unref() on the returned value to deallocate its
13052 clutter_actor_create_pango_context (ClutterActor *self)
13054 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
13056 return _clutter_context_create_pango_context ();
13060 * clutter_actor_create_pango_layout:
13061 * @self: a #ClutterActor
13062 * @text: (allow-none) the text to set on the #PangoLayout, or %NULL
13064 * Creates a new #PangoLayout from the same #PangoContext used
13065 * by the #ClutterActor. The #PangoLayout is already configured
13066 * with the font map, resolution and font options, and the
13069 * If you want to keep around a #PangoLayout created by this
13070 * function you will have to connect to the #ClutterBackend::font-changed
13071 * and #ClutterBackend::resolution-changed signals, and call
13072 * pango_layout_context_changed() in response to them.
13074 * Return value: (transfer full): the newly created #PangoLayout.
13075 * Use g_object_unref() when done
13080 clutter_actor_create_pango_layout (ClutterActor *self,
13083 PangoContext *context;
13084 PangoLayout *layout;
13086 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
13088 context = clutter_actor_get_pango_context (self);
13089 layout = pango_layout_new (context);
13092 pango_layout_set_text (layout, text, -1);
13097 /* Allows overriding the calculated paint opacity. Used by ClutterClone and
13098 * ClutterOffscreenEffect.
13101 _clutter_actor_set_opacity_override (ClutterActor *self,
13104 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13106 self->priv->opacity_override = opacity;
13110 _clutter_actor_get_opacity_override (ClutterActor *self)
13112 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), -1);
13114 return self->priv->opacity_override;
13117 /* Allows you to disable applying the actors model view transform during
13118 * a paint. Used by ClutterClone. */
13120 _clutter_actor_set_enable_model_view_transform (ClutterActor *self,
13123 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13125 self->priv->enable_model_view_transform = enable;
13129 _clutter_actor_set_enable_paint_unmapped (ClutterActor *self,
13132 ClutterActorPrivate *priv;
13134 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13138 priv->enable_paint_unmapped = enable;
13140 if (priv->enable_paint_unmapped)
13142 /* Make sure that the parents of the widget are realized first;
13143 * otherwise checks in clutter_actor_update_map_state() will
13146 clutter_actor_realize (self);
13148 clutter_actor_update_map_state (self, MAP_STATE_MAKE_MAPPED);
13152 clutter_actor_update_map_state (self, MAP_STATE_MAKE_UNMAPPED);
13157 clutter_anchor_coord_get_units (ClutterActor *self,
13158 const AnchorCoord *coord,
13163 if (coord->is_fractional)
13165 gfloat actor_width, actor_height;
13167 clutter_actor_get_size (self, &actor_width, &actor_height);
13170 *x = actor_width * coord->v.fraction.x;
13173 *y = actor_height * coord->v.fraction.y;
13181 *x = coord->v.units.x;
13184 *y = coord->v.units.y;
13187 *z = coord->v.units.z;
13192 clutter_anchor_coord_set_units (AnchorCoord *coord,
13197 coord->is_fractional = FALSE;
13198 coord->v.units.x = x;
13199 coord->v.units.y = y;
13200 coord->v.units.z = z;
13203 static ClutterGravity
13204 clutter_anchor_coord_get_gravity (const AnchorCoord *coord)
13206 if (coord->is_fractional)
13208 if (coord->v.fraction.x == 0.0)
13210 if (coord->v.fraction.y == 0.0)
13211 return CLUTTER_GRAVITY_NORTH_WEST;
13212 else if (coord->v.fraction.y == 0.5)
13213 return CLUTTER_GRAVITY_WEST;
13214 else if (coord->v.fraction.y == 1.0)
13215 return CLUTTER_GRAVITY_SOUTH_WEST;
13217 return CLUTTER_GRAVITY_NONE;
13219 else if (coord->v.fraction.x == 0.5)
13221 if (coord->v.fraction.y == 0.0)
13222 return CLUTTER_GRAVITY_NORTH;
13223 else if (coord->v.fraction.y == 0.5)
13224 return CLUTTER_GRAVITY_CENTER;
13225 else if (coord->v.fraction.y == 1.0)
13226 return CLUTTER_GRAVITY_SOUTH;
13228 return CLUTTER_GRAVITY_NONE;
13230 else if (coord->v.fraction.x == 1.0)
13232 if (coord->v.fraction.y == 0.0)
13233 return CLUTTER_GRAVITY_NORTH_EAST;
13234 else if (coord->v.fraction.y == 0.5)
13235 return CLUTTER_GRAVITY_EAST;
13236 else if (coord->v.fraction.y == 1.0)
13237 return CLUTTER_GRAVITY_SOUTH_EAST;
13239 return CLUTTER_GRAVITY_NONE;
13242 return CLUTTER_GRAVITY_NONE;
13245 return CLUTTER_GRAVITY_NONE;
13249 clutter_anchor_coord_set_gravity (AnchorCoord *coord,
13250 ClutterGravity gravity)
13254 case CLUTTER_GRAVITY_NORTH:
13255 coord->v.fraction.x = 0.5;
13256 coord->v.fraction.y = 0.0;
13259 case CLUTTER_GRAVITY_NORTH_EAST:
13260 coord->v.fraction.x = 1.0;
13261 coord->v.fraction.y = 0.0;
13264 case CLUTTER_GRAVITY_EAST:
13265 coord->v.fraction.x = 1.0;
13266 coord->v.fraction.y = 0.5;
13269 case CLUTTER_GRAVITY_SOUTH_EAST:
13270 coord->v.fraction.x = 1.0;
13271 coord->v.fraction.y = 1.0;
13274 case CLUTTER_GRAVITY_SOUTH:
13275 coord->v.fraction.x = 0.5;
13276 coord->v.fraction.y = 1.0;
13279 case CLUTTER_GRAVITY_SOUTH_WEST:
13280 coord->v.fraction.x = 0.0;
13281 coord->v.fraction.y = 1.0;
13284 case CLUTTER_GRAVITY_WEST:
13285 coord->v.fraction.x = 0.0;
13286 coord->v.fraction.y = 0.5;
13289 case CLUTTER_GRAVITY_NORTH_WEST:
13290 coord->v.fraction.x = 0.0;
13291 coord->v.fraction.y = 0.0;
13294 case CLUTTER_GRAVITY_CENTER:
13295 coord->v.fraction.x = 0.5;
13296 coord->v.fraction.y = 0.5;
13300 coord->v.fraction.x = 0.0;
13301 coord->v.fraction.y = 0.0;
13305 coord->is_fractional = TRUE;
13309 clutter_anchor_coord_is_zero (const AnchorCoord *coord)
13311 if (coord->is_fractional)
13312 return coord->v.fraction.x == 0.0 && coord->v.fraction.y == 0.0;
13314 return (coord->v.units.x == 0.0
13315 && coord->v.units.y == 0.0
13316 && coord->v.units.z == 0.0);
13320 * clutter_actor_get_flags:
13321 * @self: a #ClutterActor
13323 * Retrieves the flags set on @self
13325 * Return value: a bitwise or of #ClutterActorFlags or 0
13330 clutter_actor_get_flags (ClutterActor *self)
13332 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
13334 return self->flags;
13338 * clutter_actor_set_flags:
13339 * @self: a #ClutterActor
13340 * @flags: the flags to set
13342 * Sets @flags on @self
13344 * This function will emit notifications for the changed properties
13349 clutter_actor_set_flags (ClutterActor *self,
13350 ClutterActorFlags flags)
13352 ClutterActorFlags old_flags;
13354 gboolean was_reactive_set, reactive_set;
13355 gboolean was_realized_set, realized_set;
13356 gboolean was_mapped_set, mapped_set;
13357 gboolean was_visible_set, visible_set;
13359 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13361 if (self->flags == flags)
13364 obj = G_OBJECT (self);
13365 g_object_ref (obj);
13366 g_object_freeze_notify (obj);
13368 old_flags = self->flags;
13370 was_reactive_set = ((old_flags & CLUTTER_ACTOR_REACTIVE) != 0);
13371 was_realized_set = ((old_flags & CLUTTER_ACTOR_REALIZED) != 0);
13372 was_mapped_set = ((old_flags & CLUTTER_ACTOR_MAPPED) != 0);
13373 was_visible_set = ((old_flags & CLUTTER_ACTOR_VISIBLE) != 0);
13375 self->flags |= flags;
13377 reactive_set = ((self->flags & CLUTTER_ACTOR_REACTIVE) != 0);
13378 realized_set = ((self->flags & CLUTTER_ACTOR_REALIZED) != 0);
13379 mapped_set = ((self->flags & CLUTTER_ACTOR_MAPPED) != 0);
13380 visible_set = ((self->flags & CLUTTER_ACTOR_VISIBLE) != 0);
13382 if (reactive_set != was_reactive_set)
13383 g_object_notify_by_pspec (obj, obj_props[PROP_REACTIVE]);
13385 if (realized_set != was_realized_set)
13386 g_object_notify_by_pspec (obj, obj_props[PROP_REALIZED]);
13388 if (mapped_set != was_mapped_set)
13389 g_object_notify_by_pspec (obj, obj_props[PROP_MAPPED]);
13391 if (visible_set != was_visible_set)
13392 g_object_notify_by_pspec (obj, obj_props[PROP_VISIBLE]);
13394 g_object_thaw_notify (obj);
13395 g_object_unref (obj);
13399 * clutter_actor_unset_flags:
13400 * @self: a #ClutterActor
13401 * @flags: the flags to unset
13403 * Unsets @flags on @self
13405 * This function will emit notifications for the changed properties
13410 clutter_actor_unset_flags (ClutterActor *self,
13411 ClutterActorFlags flags)
13413 ClutterActorFlags old_flags;
13415 gboolean was_reactive_set, reactive_set;
13416 gboolean was_realized_set, realized_set;
13417 gboolean was_mapped_set, mapped_set;
13418 gboolean was_visible_set, visible_set;
13420 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13422 obj = G_OBJECT (self);
13423 g_object_freeze_notify (obj);
13425 old_flags = self->flags;
13427 was_reactive_set = ((old_flags & CLUTTER_ACTOR_REACTIVE) != 0);
13428 was_realized_set = ((old_flags & CLUTTER_ACTOR_REALIZED) != 0);
13429 was_mapped_set = ((old_flags & CLUTTER_ACTOR_MAPPED) != 0);
13430 was_visible_set = ((old_flags & CLUTTER_ACTOR_VISIBLE) != 0);
13432 self->flags &= ~flags;
13434 if (self->flags == old_flags)
13437 reactive_set = ((self->flags & CLUTTER_ACTOR_REACTIVE) != 0);
13438 realized_set = ((self->flags & CLUTTER_ACTOR_REALIZED) != 0);
13439 mapped_set = ((self->flags & CLUTTER_ACTOR_MAPPED) != 0);
13440 visible_set = ((self->flags & CLUTTER_ACTOR_VISIBLE) != 0);
13442 if (reactive_set != was_reactive_set)
13443 g_object_notify_by_pspec (obj, obj_props[PROP_REACTIVE]);
13445 if (realized_set != was_realized_set)
13446 g_object_notify_by_pspec (obj, obj_props[PROP_REALIZED]);
13448 if (mapped_set != was_mapped_set)
13449 g_object_notify_by_pspec (obj, obj_props[PROP_MAPPED]);
13451 if (visible_set != was_visible_set)
13452 g_object_notify_by_pspec (obj, obj_props[PROP_VISIBLE]);
13454 g_object_thaw_notify (obj);
13458 * clutter_actor_get_transformation_matrix:
13459 * @self: a #ClutterActor
13460 * @matrix: (out caller-allocates): the return location for a #CoglMatrix
13462 * Retrieves the transformations applied to @self relative to its
13468 clutter_actor_get_transformation_matrix (ClutterActor *self,
13469 CoglMatrix *matrix)
13471 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13473 cogl_matrix_init_identity (matrix);
13475 _clutter_actor_apply_modelview_transform (self, matrix);
13479 _clutter_actor_set_in_clone_paint (ClutterActor *self,
13480 gboolean is_in_clone_paint)
13482 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13483 self->priv->in_clone_paint = is_in_clone_paint;
13487 * clutter_actor_is_in_clone_paint:
13488 * @self: a #ClutterActor
13490 * Checks whether @self is being currently painted by a #ClutterClone
13492 * This function is useful only inside the ::paint virtual function
13493 * implementations or within handlers for the #ClutterActor::paint
13496 * This function should not be used by applications
13498 * Return value: %TRUE if the #ClutterActor is currently being painted
13499 * by a #ClutterClone, and %FALSE otherwise
13504 clutter_actor_is_in_clone_paint (ClutterActor *self)
13506 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
13508 return self->priv->in_clone_paint;
13512 set_direction_recursive (ClutterActor *actor,
13513 gpointer user_data)
13515 ClutterTextDirection text_dir = GPOINTER_TO_INT (user_data);
13517 clutter_actor_set_text_direction (actor, text_dir);
13523 * clutter_actor_set_text_direction:
13524 * @self: a #ClutterActor
13525 * @text_dir: the text direction for @self
13527 * Sets the #ClutterTextDirection for an actor
13529 * The passed text direction must not be %CLUTTER_TEXT_DIRECTION_DEFAULT
13531 * If @self implements #ClutterContainer then this function will recurse
13532 * inside all the children of @self (including the internal ones).
13534 * Composite actors not implementing #ClutterContainer, or actors requiring
13535 * special handling when the text direction changes, should connect to
13536 * the #GObject::notify signal for the #ClutterActor:text-direction property
13541 clutter_actor_set_text_direction (ClutterActor *self,
13542 ClutterTextDirection text_dir)
13544 ClutterActorPrivate *priv;
13546 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13547 g_return_if_fail (text_dir != CLUTTER_TEXT_DIRECTION_DEFAULT);
13551 if (priv->text_direction != text_dir)
13553 priv->text_direction = text_dir;
13555 /* we need to emit the notify::text-direction first, so that
13556 * the sub-classes can catch that and do specific handling of
13557 * the text direction; see clutter_text_direction_changed_cb()
13558 * inside clutter-text.c
13560 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_TEXT_DIRECTION]);
13562 _clutter_actor_foreach_child (self, set_direction_recursive,
13563 GINT_TO_POINTER (text_dir));
13565 clutter_actor_queue_relayout (self);
13570 _clutter_actor_set_has_pointer (ClutterActor *self,
13571 gboolean has_pointer)
13573 ClutterActorPrivate *priv = self->priv;
13575 if (priv->has_pointer != has_pointer)
13577 priv->has_pointer = has_pointer;
13579 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_HAS_POINTER]);
13584 * clutter_actor_get_text_direction:
13585 * @self: a #ClutterActor
13587 * Retrieves the value set using clutter_actor_set_text_direction()
13589 * If no text direction has been previously set, the default text
13590 * direction, as returned by clutter_get_default_text_direction(), will
13591 * be returned instead
13593 * Return value: the #ClutterTextDirection for the actor
13597 ClutterTextDirection
13598 clutter_actor_get_text_direction (ClutterActor *self)
13600 ClutterActorPrivate *priv;
13602 g_return_val_if_fail (CLUTTER_IS_ACTOR (self),
13603 CLUTTER_TEXT_DIRECTION_LTR);
13607 /* if no direction has been set yet use the default */
13608 if (priv->text_direction == CLUTTER_TEXT_DIRECTION_DEFAULT)
13609 priv->text_direction = clutter_get_default_text_direction ();
13611 return priv->text_direction;
13615 * clutter_actor_push_internal:
13616 * @self: a #ClutterActor
13618 * Should be used by actors implementing the #ClutterContainer and with
13619 * internal children added through clutter_actor_set_parent(), for instance:
13623 * my_actor_init (MyActor *self)
13625 * self->priv = SELF_ACTOR_GET_PRIVATE (self);
13627 * clutter_actor_push_internal (CLUTTER_ACTOR (self));
13629 * /* calling clutter_actor_set_parent() now will result in
13630 * * the internal flag being set on a child of MyActor
13633 * /* internal child - a background texture */
13634 * self->priv->background_tex = clutter_texture_new ();
13635 * clutter_actor_set_parent (self->priv->background_tex,
13636 * CLUTTER_ACTOR (self));
13638 * /* internal child - a label */
13639 * self->priv->label = clutter_text_new ();
13640 * clutter_actor_set_parent (self->priv->label,
13641 * CLUTTER_ACTOR (self));
13643 * clutter_actor_pop_internal (CLUTTER_ACTOR (self));
13645 * /* calling clutter_actor_set_parent() now will not result in
13646 * * the internal flag being set on a child of MyActor
13651 * This function will be used by Clutter to toggle an "internal child"
13652 * flag whenever clutter_actor_set_parent() is called; internal children
13653 * are handled differently by Clutter, specifically when destroying their
13656 * Call clutter_actor_pop_internal() when you finished adding internal
13659 * Nested calls to clutter_actor_push_internal() are allowed, but each
13660 * one must by followed by a clutter_actor_pop_internal() call.
13664 * Deprecated: 1.10: All children of an actor are accessible through
13665 * the #ClutterActor API, and #ClutterActor implements the
13666 * #ClutterContainer interface, so this function is only useful
13667 * for legacy containers overriding the default implementation.
13670 clutter_actor_push_internal (ClutterActor *self)
13672 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13674 self->priv->internal_child += 1;
13678 * clutter_actor_pop_internal:
13679 * @self: a #ClutterActor
13681 * Disables the effects of clutter_actor_push_internal().
13685 * Deprecated: 1.10: All children of an actor are accessible through
13686 * the #ClutterActor API. This function is only useful for legacy
13687 * containers overriding the default implementation of the
13688 * #ClutterContainer interface.
13691 clutter_actor_pop_internal (ClutterActor *self)
13693 ClutterActorPrivate *priv;
13695 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13699 if (priv->internal_child == 0)
13701 g_warning ("Mismatched %s: you need to call "
13702 "clutter_actor_push_composite() at least once before "
13703 "calling this function", G_STRFUNC);
13707 priv->internal_child -= 1;
13711 * clutter_actor_has_pointer:
13712 * @self: a #ClutterActor
13714 * Checks whether an actor contains the pointer of a
13715 * #ClutterInputDevice
13717 * Return value: %TRUE if the actor contains the pointer, and
13723 clutter_actor_has_pointer (ClutterActor *self)
13725 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
13727 return self->priv->has_pointer;
13730 /* XXX: This is a workaround for not being able to break the ABI of
13731 * the QUEUE_REDRAW signal. It is an out-of-band argument. See
13732 * clutter_actor_queue_clipped_redraw() for details.
13734 ClutterPaintVolume *
13735 _clutter_actor_get_queue_redraw_clip (ClutterActor *self)
13737 return g_object_get_data (G_OBJECT (self),
13738 "-clutter-actor-queue-redraw-clip");
13742 _clutter_actor_set_queue_redraw_clip (ClutterActor *self,
13743 ClutterPaintVolume *clip)
13745 g_object_set_data (G_OBJECT (self),
13746 "-clutter-actor-queue-redraw-clip",
13751 * clutter_actor_has_allocation:
13752 * @self: a #ClutterActor
13754 * Checks if the actor has an up-to-date allocation assigned to
13755 * it. This means that the actor should have an allocation: it's
13756 * visible and has a parent. It also means that there is no
13757 * outstanding relayout request in progress for the actor or its
13758 * children (There might be other outstanding layout requests in
13759 * progress that will cause the actor to get a new allocation
13760 * when the stage is laid out, however).
13762 * If this function returns %FALSE, then the actor will normally
13763 * be allocated before it is next drawn on the screen.
13765 * Return value: %TRUE if the actor has an up-to-date allocation
13770 clutter_actor_has_allocation (ClutterActor *self)
13772 ClutterActorPrivate *priv;
13774 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
13778 return priv->parent != NULL &&
13779 CLUTTER_ACTOR_IS_VISIBLE (self) &&
13780 !priv->needs_allocation;
13784 * clutter_actor_add_action:
13785 * @self: a #ClutterActor
13786 * @action: a #ClutterAction
13788 * Adds @action to the list of actions applied to @self
13790 * A #ClutterAction can only belong to one actor at a time
13792 * The #ClutterActor will hold a reference on @action until either
13793 * clutter_actor_remove_action() or clutter_actor_clear_actions()
13799 clutter_actor_add_action (ClutterActor *self,
13800 ClutterAction *action)
13802 ClutterActorPrivate *priv;
13804 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13805 g_return_if_fail (CLUTTER_IS_ACTION (action));
13809 if (priv->actions == NULL)
13811 priv->actions = g_object_new (CLUTTER_TYPE_META_GROUP, NULL);
13812 priv->actions->actor = self;
13815 _clutter_meta_group_add_meta (priv->actions, CLUTTER_ACTOR_META (action));
13817 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_ACTIONS]);
13821 * clutter_actor_add_action_with_name:
13822 * @self: a #ClutterActor
13823 * @name: the name to set on the action
13824 * @action: a #ClutterAction
13826 * A convenience function for setting the name of a #ClutterAction
13827 * while adding it to the list of actions applied to @self
13829 * This function is the logical equivalent of:
13832 * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
13833 * clutter_actor_add_action (self, action);
13839 clutter_actor_add_action_with_name (ClutterActor *self,
13841 ClutterAction *action)
13843 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13844 g_return_if_fail (name != NULL);
13845 g_return_if_fail (CLUTTER_IS_ACTION (action));
13847 clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
13848 clutter_actor_add_action (self, action);
13852 * clutter_actor_remove_action:
13853 * @self: a #ClutterActor
13854 * @action: a #ClutterAction
13856 * Removes @action from the list of actions applied to @self
13858 * The reference held by @self on the #ClutterAction will be released
13863 clutter_actor_remove_action (ClutterActor *self,
13864 ClutterAction *action)
13866 ClutterActorPrivate *priv;
13868 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13869 g_return_if_fail (CLUTTER_IS_ACTION (action));
13873 if (priv->actions == NULL)
13876 _clutter_meta_group_remove_meta (priv->actions, CLUTTER_ACTOR_META (action));
13878 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_ACTIONS]);
13882 * clutter_actor_remove_action_by_name:
13883 * @self: a #ClutterActor
13884 * @name: the name of the action to remove
13886 * Removes the #ClutterAction with the given name from the list
13887 * of actions applied to @self
13892 clutter_actor_remove_action_by_name (ClutterActor *self,
13895 ClutterActorPrivate *priv;
13896 ClutterActorMeta *meta;
13898 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13899 g_return_if_fail (name != NULL);
13903 if (priv->actions == NULL)
13906 meta = _clutter_meta_group_get_meta (priv->actions, name);
13910 _clutter_meta_group_remove_meta (priv->actions, meta);
13912 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_ACTIONS]);
13916 * clutter_actor_get_actions:
13917 * @self: a #ClutterActor
13919 * Retrieves the list of actions applied to @self
13921 * Return value: (transfer container) (element-type Clutter.Action): a copy
13922 * of the list of #ClutterAction<!-- -->s. The contents of the list are
13923 * owned by the #ClutterActor. Use g_list_free() to free the resources
13924 * allocated by the returned #GList
13929 clutter_actor_get_actions (ClutterActor *self)
13931 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
13933 if (self->priv->actions == NULL)
13936 return _clutter_meta_group_get_metas_no_internal (self->priv->actions);
13940 * clutter_actor_get_action:
13941 * @self: a #ClutterActor
13942 * @name: the name of the action to retrieve
13944 * Retrieves the #ClutterAction with the given name in the list
13945 * of actions applied to @self
13947 * Return value: (transfer none): a #ClutterAction for the given
13948 * name, or %NULL. The returned #ClutterAction is owned by the
13949 * actor and it should not be unreferenced directly
13954 clutter_actor_get_action (ClutterActor *self,
13957 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
13958 g_return_val_if_fail (name != NULL, NULL);
13960 if (self->priv->actions == NULL)
13963 return CLUTTER_ACTION (_clutter_meta_group_get_meta (self->priv->actions, name));
13967 * clutter_actor_clear_actions:
13968 * @self: a #ClutterActor
13970 * Clears the list of actions applied to @self
13975 clutter_actor_clear_actions (ClutterActor *self)
13977 g_return_if_fail (CLUTTER_IS_ACTOR (self));
13979 if (self->priv->actions == NULL)
13982 _clutter_meta_group_clear_metas_no_internal (self->priv->actions);
13986 * clutter_actor_add_constraint:
13987 * @self: a #ClutterActor
13988 * @constraint: a #ClutterConstraint
13990 * Adds @constraint to the list of #ClutterConstraint<!-- -->s applied
13993 * The #ClutterActor will hold a reference on the @constraint until
13994 * either clutter_actor_remove_constraint() or
13995 * clutter_actor_clear_constraints() is called.
14000 clutter_actor_add_constraint (ClutterActor *self,
14001 ClutterConstraint *constraint)
14003 ClutterActorPrivate *priv;
14005 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14006 g_return_if_fail (CLUTTER_IS_CONSTRAINT (constraint));
14010 if (priv->constraints == NULL)
14012 priv->constraints = g_object_new (CLUTTER_TYPE_META_GROUP, NULL);
14013 priv->constraints->actor = self;
14016 _clutter_meta_group_add_meta (priv->constraints,
14017 CLUTTER_ACTOR_META (constraint));
14018 clutter_actor_queue_relayout (self);
14020 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_CONSTRAINTS]);
14024 * clutter_actor_add_constraint_with_name:
14025 * @self: a #ClutterActor
14026 * @name: the name to set on the constraint
14027 * @constraint: a #ClutterConstraint
14029 * A convenience function for setting the name of a #ClutterConstraint
14030 * while adding it to the list of constraints applied to @self
14032 * This function is the logical equivalent of:
14035 * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
14036 * clutter_actor_add_constraint (self, constraint);
14042 clutter_actor_add_constraint_with_name (ClutterActor *self,
14044 ClutterConstraint *constraint)
14046 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14047 g_return_if_fail (name != NULL);
14048 g_return_if_fail (CLUTTER_IS_CONSTRAINT (constraint));
14050 clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
14051 clutter_actor_add_constraint (self, constraint);
14055 * clutter_actor_remove_constraint:
14056 * @self: a #ClutterActor
14057 * @constraint: a #ClutterConstraint
14059 * Removes @constraint from the list of constraints applied to @self
14061 * The reference held by @self on the #ClutterConstraint will be released
14066 clutter_actor_remove_constraint (ClutterActor *self,
14067 ClutterConstraint *constraint)
14069 ClutterActorPrivate *priv;
14071 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14072 g_return_if_fail (CLUTTER_IS_CONSTRAINT (constraint));
14076 if (priv->constraints == NULL)
14079 _clutter_meta_group_remove_meta (priv->constraints,
14080 CLUTTER_ACTOR_META (constraint));
14081 clutter_actor_queue_relayout (self);
14083 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_CONSTRAINTS]);
14087 * clutter_actor_remove_constraint_by_name:
14088 * @self: a #ClutterActor
14089 * @name: the name of the constraint to remove
14091 * Removes the #ClutterConstraint with the given name from the list
14092 * of constraints applied to @self
14097 clutter_actor_remove_constraint_by_name (ClutterActor *self,
14100 ClutterActorPrivate *priv;
14101 ClutterActorMeta *meta;
14103 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14104 g_return_if_fail (name != NULL);
14108 if (priv->constraints == NULL)
14111 meta = _clutter_meta_group_get_meta (priv->constraints, name);
14115 _clutter_meta_group_remove_meta (priv->constraints, meta);
14116 clutter_actor_queue_relayout (self);
14120 * clutter_actor_get_constraints:
14121 * @self: a #ClutterActor
14123 * Retrieves the list of constraints applied to @self
14125 * Return value: (transfer container) (element-type Clutter.Constraint): a copy
14126 * of the list of #ClutterConstraint<!-- -->s. The contents of the list are
14127 * owned by the #ClutterActor. Use g_list_free() to free the resources
14128 * allocated by the returned #GList
14133 clutter_actor_get_constraints (ClutterActor *self)
14135 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14137 if (self->priv->constraints == NULL)
14140 return _clutter_meta_group_get_metas_no_internal (self->priv->constraints);
14144 * clutter_actor_get_constraint:
14145 * @self: a #ClutterActor
14146 * @name: the name of the constraint to retrieve
14148 * Retrieves the #ClutterConstraint with the given name in the list
14149 * of constraints applied to @self
14151 * Return value: (transfer none): a #ClutterConstraint for the given
14152 * name, or %NULL. The returned #ClutterConstraint is owned by the
14153 * actor and it should not be unreferenced directly
14157 ClutterConstraint *
14158 clutter_actor_get_constraint (ClutterActor *self,
14161 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14162 g_return_val_if_fail (name != NULL, NULL);
14164 if (self->priv->constraints == NULL)
14167 return CLUTTER_CONSTRAINT (_clutter_meta_group_get_meta (self->priv->constraints, name));
14171 * clutter_actor_clear_constraints:
14172 * @self: a #ClutterActor
14174 * Clears the list of constraints applied to @self
14179 clutter_actor_clear_constraints (ClutterActor *self)
14181 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14183 if (self->priv->constraints == NULL)
14186 _clutter_meta_group_clear_metas_no_internal (self->priv->constraints);
14188 clutter_actor_queue_relayout (self);
14192 * clutter_actor_set_clip_to_allocation:
14193 * @self: a #ClutterActor
14194 * @clip_set: %TRUE to apply a clip tracking the allocation
14196 * Sets whether @self should be clipped to the same size as its
14202 clutter_actor_set_clip_to_allocation (ClutterActor *self,
14205 ClutterActorPrivate *priv;
14207 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14209 clip_set = !!clip_set;
14213 if (priv->clip_to_allocation != clip_set)
14215 priv->clip_to_allocation = clip_set;
14217 clutter_actor_queue_redraw (self);
14219 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_CLIP_TO_ALLOCATION]);
14224 * clutter_actor_get_clip_to_allocation:
14225 * @self: a #ClutterActor
14227 * Retrieves the value set using clutter_actor_set_clip_to_allocation()
14229 * Return value: %TRUE if the #ClutterActor is clipped to its allocation
14234 clutter_actor_get_clip_to_allocation (ClutterActor *self)
14236 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
14238 return self->priv->clip_to_allocation;
14242 * clutter_actor_add_effect:
14243 * @self: a #ClutterActor
14244 * @effect: a #ClutterEffect
14246 * Adds @effect to the list of #ClutterEffect<!-- -->s applied to @self
14248 * The #ClutterActor will hold a reference on the @effect until either
14249 * clutter_actor_remove_effect() or clutter_actor_clear_effects() is
14255 clutter_actor_add_effect (ClutterActor *self,
14256 ClutterEffect *effect)
14258 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14259 g_return_if_fail (CLUTTER_IS_EFFECT (effect));
14261 _clutter_actor_add_effect_internal (self, effect);
14263 clutter_actor_queue_redraw (self);
14265 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_EFFECT]);
14269 * clutter_actor_add_effect_with_name:
14270 * @self: a #ClutterActor
14271 * @name: the name to set on the effect
14272 * @effect: a #ClutterEffect
14274 * A convenience function for setting the name of a #ClutterEffect
14275 * while adding it to the list of effectss applied to @self
14277 * This function is the logical equivalent of:
14280 * clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
14281 * clutter_actor_add_effect (self, effect);
14287 clutter_actor_add_effect_with_name (ClutterActor *self,
14289 ClutterEffect *effect)
14291 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14292 g_return_if_fail (name != NULL);
14293 g_return_if_fail (CLUTTER_IS_EFFECT (effect));
14295 clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
14296 clutter_actor_add_effect (self, effect);
14300 * clutter_actor_remove_effect:
14301 * @self: a #ClutterActor
14302 * @effect: a #ClutterEffect
14304 * Removes @effect from the list of effects applied to @self
14306 * The reference held by @self on the #ClutterEffect will be released
14311 clutter_actor_remove_effect (ClutterActor *self,
14312 ClutterEffect *effect)
14314 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14315 g_return_if_fail (CLUTTER_IS_EFFECT (effect));
14317 _clutter_actor_remove_effect_internal (self, effect);
14319 clutter_actor_queue_redraw (self);
14321 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_EFFECT]);
14325 * clutter_actor_remove_effect_by_name:
14326 * @self: a #ClutterActor
14327 * @name: the name of the effect to remove
14329 * Removes the #ClutterEffect with the given name from the list
14330 * of effects applied to @self
14335 clutter_actor_remove_effect_by_name (ClutterActor *self,
14338 ClutterActorPrivate *priv;
14339 ClutterActorMeta *meta;
14341 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14342 g_return_if_fail (name != NULL);
14346 if (priv->effects == NULL)
14349 meta = _clutter_meta_group_get_meta (priv->effects, name);
14353 clutter_actor_remove_effect (self, CLUTTER_EFFECT (meta));
14357 * clutter_actor_get_effects:
14358 * @self: a #ClutterActor
14360 * Retrieves the #ClutterEffect<!-- -->s applied on @self, if any
14362 * Return value: (transfer container) (element-type Clutter.Effect): a list
14363 * of #ClutterEffect<!-- -->s, or %NULL. The elements of the returned
14364 * list are owned by Clutter and they should not be freed. You should
14365 * free the returned list using g_list_free() when done
14370 clutter_actor_get_effects (ClutterActor *self)
14372 ClutterActorPrivate *priv;
14374 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14378 if (priv->effects == NULL)
14381 return _clutter_meta_group_get_metas_no_internal (priv->effects);
14385 * clutter_actor_get_effect:
14386 * @self: a #ClutterActor
14387 * @name: the name of the effect to retrieve
14389 * Retrieves the #ClutterEffect with the given name in the list
14390 * of effects applied to @self
14392 * Return value: (transfer none): a #ClutterEffect for the given
14393 * name, or %NULL. The returned #ClutterEffect is owned by the
14394 * actor and it should not be unreferenced directly
14399 clutter_actor_get_effect (ClutterActor *self,
14402 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14403 g_return_val_if_fail (name != NULL, NULL);
14405 if (self->priv->effects == NULL)
14408 return CLUTTER_EFFECT (_clutter_meta_group_get_meta (self->priv->effects, name));
14412 * clutter_actor_clear_effects:
14413 * @self: a #ClutterActor
14415 * Clears the list of effects applied to @self
14420 clutter_actor_clear_effects (ClutterActor *self)
14422 g_return_if_fail (CLUTTER_IS_ACTOR (self));
14424 if (self->priv->effects == NULL)
14427 _clutter_meta_group_clear_metas_no_internal (self->priv->effects);
14429 clutter_actor_queue_redraw (self);
14433 * clutter_actor_has_key_focus:
14434 * @self: a #ClutterActor
14436 * Checks whether @self is the #ClutterActor that has key focus
14438 * Return value: %TRUE if the actor has key focus, and %FALSE otherwise
14443 clutter_actor_has_key_focus (ClutterActor *self)
14445 ClutterActor *stage;
14447 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
14449 stage = _clutter_actor_get_stage_internal (self);
14453 return clutter_stage_get_key_focus (CLUTTER_STAGE (stage)) == self;
14457 _clutter_actor_get_paint_volume_real (ClutterActor *self,
14458 ClutterPaintVolume *pv)
14460 ClutterActorPrivate *priv = self->priv;
14462 /* Actors are only expected to report a valid paint volume
14463 * while they have a valid allocation. */
14464 if (G_UNLIKELY (priv->needs_allocation))
14466 CLUTTER_NOTE (CLIPPING, "Bail from get_paint_volume (%s): "
14467 "Actor needs allocation",
14468 _clutter_actor_get_debug_name (self));
14472 /* Check if there are any handlers connected to the paint
14473 * signal. If there are then all bets are off for what the paint
14474 * volume for this actor might possibly be!
14476 * XXX: It's expected that this is going to end up being quite a
14477 * costly check to have to do here, but we haven't come up with
14478 * another solution that can reliably catch paint signal handlers at
14479 * the right time to either avoid artefacts due to invalid stage
14480 * clipping or due to incorrect culling.
14482 * Previously we checked in clutter_actor_paint(), but at that time
14483 * we may already be using a stage clip that could be derived from
14484 * an invalid paint-volume. We used to try and handle that by
14485 * queuing a follow up, unclipped, redraw but still the previous
14486 * checking wasn't enough to catch invalid volumes involved in
14487 * culling (considering that containers may derive their volume from
14488 * children that haven't yet been painted)
14490 * Longer term, improved solutions could be:
14491 * - Disallow painting in the paint signal, only allow using it
14492 * for tracking when paints happen. We can add another API that
14493 * allows monkey patching the paint of arbitrary actors but in a
14494 * more controlled way and that also supports modifying the
14496 * - If we could be notified somehow when signal handlers are
14497 * connected we wouldn't have to poll for handlers like this.
14499 if (g_signal_has_handler_pending (self,
14500 actor_signals[PAINT],
14504 CLUTTER_NOTE (CLIPPING, "Bail from get_paint_volume (%s): "
14505 "Actor has \"paint\" signal handlers",
14506 _clutter_actor_get_debug_name (self));
14510 _clutter_paint_volume_init_static (pv, self);
14512 if (!CLUTTER_ACTOR_GET_CLASS (self)->get_paint_volume (self, pv))
14514 clutter_paint_volume_free (pv);
14515 CLUTTER_NOTE (CLIPPING, "Bail from get_paint_volume (%s): "
14516 "Actor failed to report a volume",
14517 _clutter_actor_get_debug_name (self));
14521 /* since effects can modify the paint volume, we allow them to actually
14522 * do this by making get_paint_volume() "context sensitive"
14524 if (priv->effects != NULL)
14526 if (priv->current_effect != NULL)
14528 const GList *effects, *l;
14530 /* if we are being called from within the paint sequence of
14531 * an actor, get the paint volume up to the current effect
14533 effects = _clutter_meta_group_peek_metas (priv->effects);
14535 l != NULL || (l != NULL && l->data != priv->current_effect);
14538 if (!_clutter_effect_get_paint_volume (l->data, pv))
14540 clutter_paint_volume_free (pv);
14541 CLUTTER_NOTE (CLIPPING, "Bail from get_paint_volume (%s): "
14542 "Effect (%s) failed to report a volume",
14543 _clutter_actor_get_debug_name (self),
14544 _clutter_actor_meta_get_debug_name (l->data));
14551 const GList *effects, *l;
14553 /* otherwise, get the cumulative volume */
14554 effects = _clutter_meta_group_peek_metas (priv->effects);
14555 for (l = effects; l != NULL; l = l->next)
14556 if (!_clutter_effect_get_paint_volume (l->data, pv))
14558 clutter_paint_volume_free (pv);
14559 CLUTTER_NOTE (CLIPPING, "Bail from get_paint_volume (%s): "
14560 "Effect (%s) failed to report a volume",
14561 _clutter_actor_get_debug_name (self),
14562 _clutter_actor_meta_get_debug_name (l->data));
14571 /* The public clutter_actor_get_paint_volume API returns a const
14572 * pointer since we return a pointer directly to the cached
14573 * PaintVolume associated with the actor and don't want the user to
14574 * inadvertently modify it, but for internal uses we sometimes need
14575 * access to the same PaintVolume but need to apply some book-keeping
14576 * modifications to it so we don't want a const pointer.
14578 static ClutterPaintVolume *
14579 _clutter_actor_get_paint_volume_mutable (ClutterActor *self)
14581 ClutterActorPrivate *priv;
14585 if (priv->paint_volume_valid)
14586 clutter_paint_volume_free (&priv->paint_volume);
14588 if (_clutter_actor_get_paint_volume_real (self, &priv->paint_volume))
14590 priv->paint_volume_valid = TRUE;
14591 return &priv->paint_volume;
14595 priv->paint_volume_valid = FALSE;
14601 * clutter_actor_get_paint_volume:
14602 * @self: a #ClutterActor
14604 * Retrieves the paint volume of the passed #ClutterActor, or %NULL
14605 * when a paint volume can't be determined.
14607 * The paint volume is defined as the 3D space occupied by an actor
14608 * when being painted.
14610 * This function will call the <function>get_paint_volume()</function>
14611 * virtual function of the #ClutterActor class. Sub-classes of #ClutterActor
14612 * should not usually care about overriding the default implementation,
14613 * unless they are, for instance: painting outside their allocation, or
14614 * actors with a depth factor (not in terms of #ClutterActor:depth but real
14617 * <note>2D actors overriding <function>get_paint_volume()</function>
14618 * ensure their volume has a depth of 0. (This will be true so long as
14619 * you don't call clutter_paint_volume_set_depth().)</note>
14621 * Return value: (transfer none): a pointer to a #ClutterPaintVolume,
14622 * or %NULL if no volume could be determined. The returned pointer
14623 * is not guaranteed to be valid across multiple frames; if you want
14624 * to keep it, you will need to copy it using clutter_paint_volume_copy().
14628 const ClutterPaintVolume *
14629 clutter_actor_get_paint_volume (ClutterActor *self)
14631 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14633 return _clutter_actor_get_paint_volume_mutable (self);
14637 * clutter_actor_get_transformed_paint_volume:
14638 * @self: a #ClutterActor
14639 * @relative_to_ancestor: A #ClutterActor that is an ancestor of @self
14640 * (or %NULL for the stage)
14642 * Retrieves the 3D paint volume of an actor like
14643 * clutter_actor_get_paint_volume() does (Please refer to the
14644 * documentation of clutter_actor_get_paint_volume() for more
14645 * details.) and it additionally transforms the paint volume into the
14646 * coordinate space of @relative_to_ancestor. (Or the stage if %NULL
14647 * is passed for @relative_to_ancestor)
14649 * This can be used by containers that base their paint volume on
14650 * the volume of their children. Such containers can query the
14651 * transformed paint volume of all of its children and union them
14652 * together using clutter_paint_volume_union().
14654 * Return value: (transfer none): a pointer to a #ClutterPaintVolume,
14655 * or %NULL if no volume could be determined. The returned pointer is
14656 * not guaranteed to be valid across multiple frames; if you wish to
14657 * keep it, you will have to copy it using clutter_paint_volume_copy().
14661 const ClutterPaintVolume *
14662 clutter_actor_get_transformed_paint_volume (ClutterActor *self,
14663 ClutterActor *relative_to_ancestor)
14665 const ClutterPaintVolume *volume;
14666 ClutterActor *stage;
14667 ClutterPaintVolume *transformed_volume;
14669 stage = _clutter_actor_get_stage_internal (self);
14670 if (G_UNLIKELY (stage == NULL))
14673 if (relative_to_ancestor == NULL)
14674 relative_to_ancestor = stage;
14676 volume = clutter_actor_get_paint_volume (self);
14677 if (volume == NULL)
14680 transformed_volume =
14681 _clutter_stage_paint_volume_stack_allocate (CLUTTER_STAGE (stage));
14683 _clutter_paint_volume_copy_static (volume, transformed_volume);
14685 _clutter_paint_volume_transform_relative (transformed_volume,
14686 relative_to_ancestor);
14688 return transformed_volume;
14692 * clutter_actor_get_paint_box:
14693 * @self: a #ClutterActor
14694 * @box: (out): return location for a #ClutterActorBox
14696 * Retrieves the paint volume of the passed #ClutterActor, and
14697 * transforms it into a 2D bounding box in stage coordinates.
14699 * This function is useful to determine the on screen area occupied by
14700 * the actor. The box is only an approximation and may often be
14701 * considerably larger due to the optimizations used to calculate the
14702 * box. The box is never smaller though, so it can reliably be used
14705 * There are times when a 2D paint box can't be determined, e.g.
14706 * because the actor isn't yet parented under a stage or because
14707 * the actor is unable to determine a paint volume.
14709 * Return value: %TRUE if a 2D paint box could be determined, else
14715 clutter_actor_get_paint_box (ClutterActor *self,
14716 ClutterActorBox *box)
14718 ClutterActor *stage;
14719 ClutterPaintVolume *pv;
14721 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), FALSE);
14722 g_return_val_if_fail (box != NULL, FALSE);
14724 stage = _clutter_actor_get_stage_internal (self);
14725 if (G_UNLIKELY (!stage))
14728 pv = _clutter_actor_get_paint_volume_mutable (self);
14729 if (G_UNLIKELY (!pv))
14732 _clutter_paint_volume_get_stage_paint_box (pv, CLUTTER_STAGE (stage), box);
14738 * clutter_actor_has_overlaps:
14739 * @self: A #ClutterActor
14741 * Asks the actor's implementation whether it may contain overlapping
14744 * For example; Clutter may use this to determine whether the painting
14745 * should be redirected to an offscreen buffer to correctly implement
14746 * the opacity property.
14748 * Custom actors can override the default response by implementing the
14749 * #ClutterActor <function>has_overlaps</function> virtual function. See
14750 * clutter_actor_set_offscreen_redirect() for more information.
14752 * Return value: %TRUE if the actor may have overlapping primitives, and
14758 clutter_actor_has_overlaps (ClutterActor *self)
14760 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), TRUE);
14762 return CLUTTER_ACTOR_GET_CLASS (self)->has_overlaps (self);
14766 * clutter_actor_has_effects:
14767 * @self: A #ClutterActor
14769 * Returns whether the actor has any effects applied.
14771 * Return value: %TRUE if the actor has any effects,
14777 clutter_actor_has_effects (ClutterActor *self)
14779 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), TRUE);
14781 if (self->priv->effects == NULL)
14784 return _clutter_meta_group_has_metas_no_internal (self->priv->effects);
14788 * clutter_actor_has_constraints:
14789 * @self: A #ClutterActor
14791 * Returns whether the actor has any constraints applied.
14793 * Return value: %TRUE if the actor has any constraints,
14799 clutter_actor_has_constraints (ClutterActor *self)
14801 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), TRUE);
14803 return self->priv->constraints != NULL;
14807 * clutter_actor_has_actions:
14808 * @self: A #ClutterActor
14810 * Returns whether the actor has any actions applied.
14812 * Return value: %TRUE if the actor has any actions,
14818 clutter_actor_has_actions (ClutterActor *self)
14820 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), TRUE);
14822 return self->priv->actions != NULL;
14826 * clutter_actor_get_n_children:
14827 * @self: a #ClutterActor
14829 * Retrieves the number of children of @self.
14831 * Return value: the number of children of an actor
14836 clutter_actor_get_n_children (ClutterActor *self)
14838 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0);
14840 return self->priv->n_children;
14844 * clutter_actor_get_child_at_index:
14845 * @self: a #ClutterActor
14846 * @index_: the position in the list of children
14848 * Retrieves the actor at the given @index_ inside the list of
14849 * children of @self.
14851 * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
14856 clutter_actor_get_child_at_index (ClutterActor *self,
14859 ClutterActor *iter;
14862 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
14863 g_return_val_if_fail (index_ <= self->priv->n_children, NULL);
14865 for (iter = self->priv->first_child, i = 0;
14866 iter != NULL && i < index_;
14867 iter = iter->priv->next_sibling, i += 1)
14874 * _clutter_actor_foreach_child:
14875 * @actor: The actor whos children you want to iterate
14876 * @callback: The function to call for each child
14877 * @user_data: Private data to pass to @callback
14879 * Calls a given @callback once for each child of the specified @actor and
14880 * passing the @user_data pointer each time.
14882 * Return value: returns %TRUE if all children were iterated, else
14883 * %FALSE if a callback broke out of iteration early.
14886 _clutter_actor_foreach_child (ClutterActor *self,
14887 ClutterForeachCallback callback,
14888 gpointer user_data)
14890 ClutterActorPrivate *priv = self->priv;
14891 ClutterActor *iter;
14894 for (cont = TRUE, iter = priv->first_child;
14895 cont && iter != NULL;
14896 iter = iter->priv->next_sibling)
14898 cont = callback (iter, user_data);
14905 /* For debugging purposes this gives us a simple way to print out
14906 * the scenegraph e.g in gdb using:
14908 * _clutter_actor_traverse (stage,
14910 * clutter_debug_print_actor_cb,
14915 static ClutterActorTraverseVisitFlags
14916 clutter_debug_print_actor_cb (ClutterActor *actor,
14920 g_print ("%*s%s:%p\n",
14922 _clutter_actor_get_debug_name (actor),
14925 return CLUTTER_ACTOR_TRAVERSE_VISIT_CONTINUE;
14930 _clutter_actor_traverse_breadth (ClutterActor *actor,
14931 ClutterTraverseCallback callback,
14932 gpointer user_data)
14934 GQueue *queue = g_queue_new ();
14935 ClutterActor dummy;
14936 int current_depth = 0;
14938 g_queue_push_tail (queue, actor);
14939 g_queue_push_tail (queue, &dummy); /* use to delimit depth changes */
14941 while ((actor = g_queue_pop_head (queue)))
14943 ClutterActorTraverseVisitFlags flags;
14945 if (actor == &dummy)
14948 g_queue_push_tail (queue, &dummy);
14952 flags = callback (actor, current_depth, user_data);
14953 if (flags & CLUTTER_ACTOR_TRAVERSE_VISIT_BREAK)
14955 else if (!(flags & CLUTTER_ACTOR_TRAVERSE_VISIT_SKIP_CHILDREN))
14957 ClutterActor *iter;
14959 for (iter = actor->priv->first_child;
14961 iter = iter->priv->next_sibling)
14963 g_queue_push_tail (queue, iter);
14968 g_queue_free (queue);
14971 static ClutterActorTraverseVisitFlags
14972 _clutter_actor_traverse_depth (ClutterActor *actor,
14973 ClutterTraverseCallback before_children_callback,
14974 ClutterTraverseCallback after_children_callback,
14976 gpointer user_data)
14978 ClutterActorTraverseVisitFlags flags;
14980 flags = before_children_callback (actor, current_depth, user_data);
14981 if (flags & CLUTTER_ACTOR_TRAVERSE_VISIT_BREAK)
14982 return CLUTTER_ACTOR_TRAVERSE_VISIT_BREAK;
14984 if (!(flags & CLUTTER_ACTOR_TRAVERSE_VISIT_SKIP_CHILDREN))
14986 ClutterActor *iter;
14988 for (iter = actor->priv->first_child;
14990 iter = iter->priv->next_sibling)
14992 flags = _clutter_actor_traverse_depth (iter,
14993 before_children_callback,
14994 after_children_callback,
14998 if (flags & CLUTTER_ACTOR_TRAVERSE_VISIT_BREAK)
14999 return CLUTTER_ACTOR_TRAVERSE_VISIT_BREAK;
15003 if (after_children_callback)
15004 return after_children_callback (actor, current_depth, user_data);
15006 return CLUTTER_ACTOR_TRAVERSE_VISIT_CONTINUE;
15009 /* _clutter_actor_traverse:
15010 * @actor: The actor to start traversing the graph from
15011 * @flags: These flags may affect how the traversal is done
15012 * @before_children_callback: A function to call before visiting the
15013 * children of the current actor.
15014 * @after_children_callback: A function to call after visiting the
15015 * children of the current actor. (Ignored if
15016 * %CLUTTER_ACTOR_TRAVERSE_BREADTH_FIRST is passed to @flags.)
15017 * @user_data: The private data to pass to the callbacks
15019 * Traverses the scenegraph starting at the specified @actor and
15020 * descending through all its children and its children's children.
15021 * For each actor traversed @before_children_callback and
15022 * @after_children_callback are called with the specified
15023 * @user_data, before and after visiting that actor's children.
15025 * The callbacks can return flags that affect the ongoing traversal
15026 * such as by skipping over an actors children or bailing out of
15027 * any further traversing.
15030 _clutter_actor_traverse (ClutterActor *actor,
15031 ClutterActorTraverseFlags flags,
15032 ClutterTraverseCallback before_children_callback,
15033 ClutterTraverseCallback after_children_callback,
15034 gpointer user_data)
15036 if (flags & CLUTTER_ACTOR_TRAVERSE_BREADTH_FIRST)
15037 _clutter_actor_traverse_breadth (actor,
15038 before_children_callback,
15040 else /* DEPTH_FIRST */
15041 _clutter_actor_traverse_depth (actor,
15042 before_children_callback,
15043 after_children_callback,
15044 0, /* start depth */
15049 on_layout_manager_changed (ClutterLayoutManager *manager,
15050 ClutterActor *self)
15052 clutter_actor_queue_relayout (self);
15056 * clutter_actor_set_layout_manager:
15057 * @self: a #ClutterActor
15058 * @manager: (allow-none): a #ClutterLayoutManager, or %NULL to unset it
15060 * Sets the #ClutterLayoutManager delegate object that will be used to
15061 * lay out the children of @self.
15063 * The #ClutterActor will take a reference on the passed @manager which
15064 * will be released either when the layout manager is removed, or when
15065 * the actor is destroyed.
15070 clutter_actor_set_layout_manager (ClutterActor *self,
15071 ClutterLayoutManager *manager)
15073 ClutterActorPrivate *priv;
15075 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15076 g_return_if_fail (manager == NULL || CLUTTER_IS_LAYOUT_MANAGER (manager));
15080 if (priv->layout_manager != NULL)
15082 g_signal_handlers_disconnect_by_func (priv->layout_manager,
15083 G_CALLBACK (on_layout_manager_changed),
15085 clutter_layout_manager_set_container (priv->layout_manager, NULL);
15086 g_object_unref (priv->layout_manager);
15089 priv->layout_manager = manager;
15091 if (priv->layout_manager != NULL)
15093 g_object_ref_sink (priv->layout_manager);
15094 clutter_layout_manager_set_container (priv->layout_manager,
15095 CLUTTER_CONTAINER (self));
15096 g_signal_connect (priv->layout_manager, "layout-changed",
15097 G_CALLBACK (on_layout_manager_changed),
15101 clutter_actor_queue_relayout (self);
15103 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_LAYOUT_MANAGER]);
15107 * clutter_actor_get_layout_manager:
15108 * @self: a #ClutterActor
15110 * Retrieves the #ClutterLayoutManager used by @self.
15112 * Return value: (transfer none): a pointer to the #ClutterLayoutManager,
15117 ClutterLayoutManager *
15118 clutter_actor_get_layout_manager (ClutterActor *self)
15120 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
15122 return self->priv->layout_manager;
15125 static const ClutterLayoutInfo default_layout_info = {
15128 { 0, 0, 0, 0 }, /* margin */
15129 CLUTTER_ACTOR_ALIGN_FILL, /* x-align */
15130 CLUTTER_ACTOR_ALIGN_FILL, /* y-align */
15131 0.f, 0.f, /* min_width, natural_width */
15132 0.f, 0.f, /* natual_width, natural_height */
15136 layout_info_free (gpointer data)
15138 if (G_LIKELY (data != NULL))
15139 g_slice_free (ClutterLayoutInfo, data);
15143 * _clutter_actor_get_layout_info:
15144 * @self: a #ClutterActor
15146 * Retrieves a pointer to the ClutterLayoutInfo structure.
15148 * If the actor does not have a ClutterLayoutInfo associated to it, one
15149 * will be created and initialized to the default values.
15151 * This function should be used for setters.
15153 * For getters, you should use _clutter_actor_get_layout_info_or_defaults()
15156 * Return value: (transfer none): a pointer to the ClutterLayoutInfo structure
15158 ClutterLayoutInfo *
15159 _clutter_actor_get_layout_info (ClutterActor *self)
15161 ClutterLayoutInfo *retval;
15163 retval = g_object_get_qdata (G_OBJECT (self), quark_actor_layout_info);
15164 if (retval == NULL)
15166 retval = g_slice_new (ClutterLayoutInfo);
15168 *retval = default_layout_info;
15170 g_object_set_qdata_full (G_OBJECT (self), quark_actor_layout_info,
15179 * _clutter_actor_get_layout_info_or_defaults:
15180 * @self: a #ClutterActor
15182 * Retrieves the ClutterLayoutInfo structure associated to an actor.
15184 * If the actor does not have a ClutterLayoutInfo structure associated to it,
15185 * then the default structure will be returned.
15187 * This function should only be used for getters.
15189 * Return value: a const pointer to the ClutterLayoutInfo structure
15191 const ClutterLayoutInfo *
15192 _clutter_actor_get_layout_info_or_defaults (ClutterActor *self)
15194 const ClutterLayoutInfo *info;
15196 info = g_object_get_qdata (G_OBJECT (self), quark_actor_layout_info);
15198 return &default_layout_info;
15204 * clutter_actor_set_x_align:
15205 * @self: a #ClutterActor
15206 * @x_align: the horizontal alignment policy
15208 * Sets the horizontal alignment policy of a #ClutterActor, in case the
15209 * actor received extra horizontal space.
15211 * See also the #ClutterActor:x-align property.
15216 clutter_actor_set_x_align (ClutterActor *self,
15217 ClutterActorAlign x_align)
15219 ClutterLayoutInfo *info;
15221 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15223 info = _clutter_actor_get_layout_info (self);
15225 if (info->x_align != x_align)
15227 info->x_align = x_align;
15229 clutter_actor_queue_relayout (self);
15231 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_X_ALIGN]);
15236 * clutter_actor_get_x_align:
15237 * @self: a #ClutterActor
15239 * Retrieves the horizontal alignment policy set using
15240 * clutter_actor_set_x_align().
15242 * Return value: the horizontal alignment policy.
15247 clutter_actor_get_x_align (ClutterActor *self)
15249 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), CLUTTER_ACTOR_ALIGN_FILL);
15251 return _clutter_actor_get_layout_info_or_defaults (self)->x_align;
15255 * clutter_actor_set_y_align:
15256 * @self: a #ClutterActor
15257 * @y_align: the vertical alignment policy
15259 * Sets the vertical alignment policy of a #ClutterActor, in case the
15260 * actor received extra vertical space.
15262 * See also the #ClutterActor:y-align property.
15267 clutter_actor_set_y_align (ClutterActor *self,
15268 ClutterActorAlign y_align)
15270 ClutterLayoutInfo *info;
15272 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15274 info = _clutter_actor_get_layout_info (self);
15276 if (info->y_align != y_align)
15278 info->y_align = y_align;
15280 clutter_actor_queue_relayout (self);
15282 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_Y_ALIGN]);
15287 * clutter_actor_get_y_align:
15288 * @self: a #ClutterActor
15290 * Retrieves the vertical alignment policy set using
15291 * clutter_actor_set_y_align().
15293 * Return value: the vertical alignment policy.
15298 clutter_actor_get_y_align (ClutterActor *self)
15300 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), CLUTTER_ACTOR_ALIGN_FILL);
15302 return _clutter_actor_get_layout_info_or_defaults (self)->y_align;
15307 * clutter_margin_new:
15309 * Creates a new #ClutterMargin.
15311 * Return value: (transfer full): a newly allocated #ClutterMargin. Use
15312 * clutter_margin_free() to free the resources associated with it when
15318 clutter_margin_new (void)
15320 return g_slice_new0 (ClutterMargin);
15324 * clutter_margin_copy:
15325 * @margin_: a #ClutterMargin
15327 * Creates a new #ClutterMargin and copies the contents of @margin_ into
15328 * the newly created structure.
15330 * Return value: (transfer full): a copy of the #ClutterMargin.
15335 clutter_margin_copy (const ClutterMargin *margin_)
15337 if (G_LIKELY (margin_ != NULL))
15338 return g_slice_dup (ClutterMargin, margin_);
15344 * clutter_margin_free:
15345 * @margin_: a #ClutterMargin
15347 * Frees the resources allocated by clutter_margin_new() and
15348 * clutter_margin_copy().
15353 clutter_margin_free (ClutterMargin *margin_)
15355 if (G_LIKELY (margin_ != NULL))
15356 g_slice_free (ClutterMargin, margin_);
15359 G_DEFINE_BOXED_TYPE (ClutterMargin, clutter_margin,
15360 clutter_margin_copy,
15361 clutter_margin_free)
15364 * clutter_actor_set_margin:
15365 * @self: a #ClutterActor
15366 * @margin: a #ClutterMargin
15368 * Sets all the components of the margin of a #ClutterActor.
15373 clutter_actor_set_margin (ClutterActor *self,
15374 const ClutterMargin *margin)
15376 ClutterLayoutInfo *info;
15380 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15381 g_return_if_fail (margin != NULL);
15383 obj = G_OBJECT (self);
15386 g_object_freeze_notify (obj);
15388 info = _clutter_actor_get_layout_info (self);
15390 if (info->margin.top != margin->top)
15392 info->margin.top = margin->top;
15393 g_object_notify_by_pspec (obj, obj_props[PROP_MARGIN_TOP]);
15397 if (info->margin.right != margin->right)
15399 info->margin.right = margin->right;
15400 g_object_notify_by_pspec (obj, obj_props[PROP_MARGIN_RIGHT]);
15404 if (info->margin.bottom != margin->bottom)
15406 info->margin.bottom = margin->bottom;
15407 g_object_notify_by_pspec (obj, obj_props[PROP_MARGIN_BOTTOM]);
15411 if (info->margin.left != margin->left)
15413 info->margin.left = margin->left;
15414 g_object_notify_by_pspec (obj, obj_props[PROP_MARGIN_LEFT]);
15419 clutter_actor_queue_relayout (self);
15421 g_object_thaw_notify (obj);
15425 * clutter_actor_get_margin:
15426 * @self: a #ClutterActor
15427 * @margin: (out caller-allocates): return location for a #ClutterMargin
15429 * Retrieves all the components of the margin of a #ClutterActor.
15434 clutter_actor_get_margin (ClutterActor *self,
15435 ClutterMargin *margin)
15437 const ClutterLayoutInfo *info;
15439 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15440 g_return_if_fail (margin != NULL);
15442 info = _clutter_actor_get_layout_info_or_defaults (self);
15444 *margin = info->margin;
15448 * clutter_actor_set_margin_top:
15449 * @self: a #ClutterActor
15450 * @margin: the top margin
15452 * Sets the margin from the top of a #ClutterActor.
15457 clutter_actor_set_margin_top (ClutterActor *self,
15460 ClutterLayoutInfo *info;
15462 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15463 g_return_if_fail (margin >= 0.f);
15465 info = _clutter_actor_get_layout_info (self);
15467 if (info->margin.top == margin)
15470 info->margin.top = margin;
15472 clutter_actor_queue_relayout (self);
15474 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MARGIN_TOP]);
15478 * clutter_actor_get_margin_top:
15479 * @self: a #ClutterActor
15481 * Retrieves the top margin of a #ClutterActor.
15483 * Return value: the top margin
15488 clutter_actor_get_margin_top (ClutterActor *self)
15490 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0.f);
15492 return _clutter_actor_get_layout_info_or_defaults (self)->margin.top;
15496 * clutter_actor_set_margin_bottom:
15497 * @self: a #ClutterActor
15498 * @margin: the bottom margin
15500 * Sets the margin from the bottom of a #ClutterActor.
15505 clutter_actor_set_margin_bottom (ClutterActor *self,
15508 ClutterLayoutInfo *info;
15510 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15511 g_return_if_fail (margin >= 0.f);
15513 info = _clutter_actor_get_layout_info (self);
15515 if (info->margin.bottom == margin)
15518 info->margin.bottom = margin;
15520 clutter_actor_queue_relayout (self);
15522 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MARGIN_BOTTOM]);
15526 * clutter_actor_get_margin_bottom:
15527 * @self: a #ClutterActor
15529 * Retrieves the bottom margin of a #ClutterActor.
15531 * Return value: the bottom margin
15536 clutter_actor_get_margin_bottom (ClutterActor *self)
15538 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0.f);
15540 return _clutter_actor_get_layout_info_or_defaults (self)->margin.bottom;
15544 * clutter_actor_set_margin_left:
15545 * @self: a #ClutterActor
15546 * @margin: the left margin
15548 * Sets the margin from the left of a #ClutterActor.
15553 clutter_actor_set_margin_left (ClutterActor *self,
15556 ClutterLayoutInfo *info;
15558 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15559 g_return_if_fail (margin >= 0.f);
15561 info = _clutter_actor_get_layout_info (self);
15563 if (info->margin.left == margin)
15566 info->margin.left = margin;
15568 clutter_actor_queue_relayout (self);
15570 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MARGIN_LEFT]);
15574 * clutter_actor_get_margin_left:
15575 * @self: a #ClutterActor
15577 * Retrieves the left margin of a #ClutterActor.
15579 * Return value: the left margin
15584 clutter_actor_get_margin_left (ClutterActor *self)
15586 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0.f);
15588 return _clutter_actor_get_layout_info_or_defaults (self)->margin.left;
15592 * clutter_actor_set_margin_right:
15593 * @self: a #ClutterActor
15594 * @margin: the right margin
15596 * Sets the margin from the right of a #ClutterActor.
15601 clutter_actor_set_margin_right (ClutterActor *self,
15604 ClutterLayoutInfo *info;
15606 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15607 g_return_if_fail (margin >= 0.f);
15609 info = _clutter_actor_get_layout_info (self);
15611 if (info->margin.right == margin)
15614 info->margin.right = margin;
15616 clutter_actor_queue_relayout (self);
15618 g_object_notify_by_pspec (G_OBJECT (self), obj_props[PROP_MARGIN_RIGHT]);
15622 * clutter_actor_get_margin_right:
15623 * @self: a #ClutterActor
15625 * Retrieves the right margin of a #ClutterActor.
15627 * Return value: the right margin
15632 clutter_actor_get_margin_right (ClutterActor *self)
15634 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), 0.f);
15636 return _clutter_actor_get_layout_info_or_defaults (self)->margin.right;
15640 * clutter_actor_set_background_color:
15641 * @self: a #ClutterActor
15642 * @color: (allow-none): a #ClutterColor, or %NULL to unset a previously
15645 * Sets the background color of a #ClutterActor.
15647 * The background color will be used to cover the whole allocation of the
15648 * actor. The default background color of an actor is transparent.
15650 * To check whether an actor has a background color, you can use the
15651 * #ClutterActor:background-color-set actor property.
15656 clutter_actor_set_background_color (ClutterActor *self,
15657 const ClutterColor *color)
15659 ClutterActorPrivate *priv;
15661 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15667 priv->bg_color_set = FALSE;
15668 g_object_notify_by_pspec (G_OBJECT (self),
15669 obj_props[PROP_BACKGROUND_COLOR_SET]);
15673 if (priv->bg_color_set && clutter_color_equal (color, &priv->bg_color))
15676 priv->bg_color = *color;
15677 priv->bg_color_set = TRUE;
15679 clutter_actor_queue_redraw (self);
15681 g_object_notify_by_pspec (G_OBJECT (self),
15682 obj_props[PROP_BACKGROUND_COLOR_SET]);
15683 g_object_notify_by_pspec (G_OBJECT (self),
15684 obj_props[PROP_BACKGROUND_COLOR]);
15688 * clutter_actor_get_background_color:
15689 * @self: a #ClutterActor
15690 * @color: (out caller-allocates): return location for a #ClutterColor
15692 * Retrieves the color set using clutter_actor_set_background_color().
15697 clutter_actor_get_background_color (ClutterActor *self,
15698 ClutterColor *color)
15700 g_return_if_fail (CLUTTER_IS_ACTOR (self));
15701 g_return_if_fail (color != NULL);
15703 *color = self->priv->bg_color;
15707 * clutter_actor_get_previous_sibling:
15708 * @self: a #ClutterActor
15710 * Retrieves the sibling of @self that comes before it in the list
15711 * of children of @self's parent.
15713 * The returned pointer is only valid until the scene graph changes; it
15714 * is not safe to modify the list of children of @self while iterating
15717 * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
15722 clutter_actor_get_previous_sibling (ClutterActor *self)
15724 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
15726 return self->priv->prev_sibling;
15730 * clutter_actor_get_next_sibling:
15731 * @self: a #ClutterActor
15733 * Retrieves the sibling of @self that comes after it in the list
15734 * of children of @self's parent.
15736 * The returned pointer is only valid until the scene graph changes; it
15737 * is not safe to modify the list of children of @self while iterating
15740 * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
15745 clutter_actor_get_next_sibling (ClutterActor *self)
15747 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
15749 return self->priv->next_sibling;
15753 * clutter_actor_get_first_child:
15754 * @self: a #ClutterActor
15756 * Retrieves the first child of @self.
15758 * The returned pointer is only valid until the scene graph changes; it
15759 * is not safe to modify the list of children of @self while iterating
15762 * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
15767 clutter_actor_get_first_child (ClutterActor *self)
15769 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
15771 return self->priv->first_child;
15775 * clutter_actor_get_last_child:
15776 * @self: a #ClutterActor
15778 * Retrieves the last child of @self.
15780 * The returned pointer is only valid until the scene graph changes; it
15781 * is not safe to modify the list of children of @self while iterating
15784 * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
15789 clutter_actor_get_last_child (ClutterActor *self)
15791 g_return_val_if_fail (CLUTTER_IS_ACTOR (self), NULL);
15793 return self->priv->last_child;
15796 /* easy way to have properly named fields instead of the dummy ones
15797 * we use in the public structure
15799 typedef struct _RealActorIter
15801 ClutterActor *root; /* dummy1 */
15802 ClutterActor *current; /* dummy2 */
15803 gpointer padding_1; /* dummy3 */
15804 gint age; /* dummy4 */
15805 gpointer padding_2; /* dummy5 */
15809 * clutter_actor_iter_init:
15810 * @iter: a #ClutterActorIter
15811 * @root: a #ClutterActor
15813 * Initializes a #ClutterActorIter, which can then be used to iterate
15814 * efficiently over a section of the scene graph, and associates it
15817 * Modifying the scene graph section that contains @root will invalidate
15821 * ClutterActorIter iter;
15822 * ClutterActor *child;
15824 * clutter_actor_iter_init (&iter, container);
15825 * while (clutter_actor_iter_next (&iter, &child))
15827 * /* do something with child */
15834 clutter_actor_iter_init (ClutterActorIter *iter,
15835 ClutterActor *root)
15837 RealActorIter *ri = (RealActorIter *) iter;
15839 g_return_if_fail (iter != NULL);
15840 g_return_if_fail (CLUTTER_IS_ACTOR (root));
15843 ri->current = NULL;
15844 ri->age = root->priv->age;
15848 * clutter_actor_iter_next:
15849 * @iter: a #ClutterActorIter
15850 * @child: (out): return location for a #ClutterActor
15852 * Advances the @iter and retrieves the next child of the root #ClutterActor
15853 * that was used to initialize the #ClutterActorIterator.
15855 * If the iterator can advance, this function returns %TRUE and sets the
15858 * If the iterator cannot advance, this function returns %FALSE, and
15859 * the contents of @child are undefined.
15861 * Return value: %TRUE if the iterator could advance, and %FALSE otherwise.
15866 clutter_actor_iter_next (ClutterActorIter *iter,
15867 ClutterActor **child)
15869 RealActorIter *ri = (RealActorIter *) iter;
15871 g_return_val_if_fail (iter != NULL, FALSE);
15872 g_return_val_if_fail (ri->root != NULL, FALSE);
15873 #ifndef G_DISABLE_ASSERT
15874 g_return_val_if_fail (ri->age == ri->root->priv->age, FALSE);
15877 if (ri->current == NULL)
15878 ri->current = ri->root->priv->first_child;
15880 ri->current = ri->current->priv->next_sibling;
15883 *child = ri->current;
15885 return ri->current != NULL;
15889 * clutter_actor_iter_prev:
15890 * @iter: a #ClutterActorIter
15891 * @child: (out): return location for a #ClutterActor
15893 * Advances the @iter and retrieves the previous child of the root
15894 * #ClutterActor that was used to initialize the #ClutterActorIterator.
15896 * If the iterator can advance, this function returns %TRUE and sets the
15899 * If the iterator cannot advance, this function returns %FALSE, and
15900 * the contents of @child are undefined.
15902 * Return value: %TRUE if the iterator could advance, and %FALSE otherwise.
15907 clutter_actor_iter_prev (ClutterActorIter *iter,
15908 ClutterActor **child)
15910 RealActorIter *ri = (RealActorIter *) iter;
15912 g_return_val_if_fail (iter != NULL, FALSE);
15913 g_return_val_if_fail (ri->root != NULL, FALSE);
15914 #ifndef G_DISABLE_ASSERT
15915 g_return_val_if_fail (ri->age == ri->root->priv->age, FALSE);
15918 if (ri->current == NULL)
15919 ri->current = ri->root->priv->last_child;
15921 ri->current = ri->current->priv->prev_sibling;
15924 *child = ri->current;
15926 return ri->current != NULL;
15930 * clutter_actor_iter_remove:
15931 * @iter: a #ClutterActorIter
15933 * Safely removes the #ClutterActor currently pointer to by the iterator
15936 * This function can only be called after clutter_actor_iter_next() or
15937 * clutter_actor_iter_prev() returned %TRUE, and cannot be called more
15938 * than once for the same actor.
15940 * This function will call clutter_actor_remove_child() internally.
15945 clutter_actor_iter_remove (ClutterActorIter *iter)
15947 RealActorIter *ri = (RealActorIter *) iter;
15950 g_return_if_fail (iter != NULL);
15951 g_return_if_fail (ri->root != NULL);
15952 #ifndef G_DISABLE_ASSERT
15953 g_return_if_fail (ri->age == ri->root->priv->age);
15955 g_return_if_fail (ri->current != NULL);
15961 ri->current = cur->priv->prev_sibling;
15963 clutter_actor_remove_child_internal (ri->root, cur,
15964 REMOVE_CHILD_DEFAULT_FLAGS);
15971 * clutter_actor_iter_destroy:
15972 * @iter: a #ClutterActorIter
15974 * Safely destroys the #ClutterActor currently pointer to by the iterator
15977 * This function can only be called after clutter_actor_iter_next() or
15978 * clutter_actor_iter_prev() returned %TRUE, and cannot be called more
15979 * than once for the same actor.
15981 * This function will call clutter_actor_destroy() internally.
15986 clutter_actor_iter_destroy (ClutterActorIter *iter)
15988 RealActorIter *ri = (RealActorIter *) iter;
15991 g_return_if_fail (iter != NULL);
15992 g_return_if_fail (ri->root != NULL);
15993 #ifndef G_DISABLE_ASSERT
15994 g_return_if_fail (ri->age == ri->root->priv->age);
15996 g_return_if_fail (ri->current != NULL);
16002 ri->current = cur->priv->prev_sibling;
16004 clutter_actor_destroy (cur);