Actor transformations

Each actor can be transformed using methods like clutter_actor_set_scale() or clutter_actor_set_rotation(). The order in which the transformations are applied is decided by Clutter and it is the following:

Modifying an actor's geometry

Each actor has a bounding box, called "allocation" which is either set by its parent or explicitly through the clutter_actor_set_position() and clutter_actor_set_size() methods. Each actor also has an implicit preferred size.

An actor’s preferred size can be defined by any subclass by overriding the ClutterActorClass.get_preferred_width() and the ClutterActorClass.get_preferred_height() virtual functions, or it can be explicitly set by using clutter_actor_set_width() and clutter_actor_set_height().

An actor’s position can be set explicitly by using clutter_actor_set_x() and clutter_actor_set_y(); the coordinates are relative to the origin of the actor’s parent.

Managing actor children

Each actor can have multiple children, by calling clutter_actor_add_child() to add a new child actor, and clutter_actor_remove_child() to remove an existing child. ClutterActor will hold a reference on each child actor, which will be released when the child is removed from its parent, or destroyed using clutter_actor_destroy().

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

ClutterActor *actor = clutter_actor_new ();

/* set the bounding box of the actor */
clutter_actor_set_position (actor, 0, 0);
clutter_actor_set_size (actor, 480, 640);

/* set the background color of the actor */
clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);

/* set the bounding box of the child, relative to the parent */
ClutterActor *child = clutter_actor_new ();
clutter_actor_set_position (child, 20, 20);
clutter_actor_set_size (child, 80, 240);

/* set the background color of the child */
clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);

/* add the child to the actor */
clutter_actor_add_child (actor, child);

Children can be inserted at a given index, or above and below another child actor. The order of insertion determines the order of the children when iterating over them. Iterating over children is performed by using clutter_actor_get_first_child(), clutter_actor_get_previous_sibling(), clutter_actor_get_next_sibling(), and clutter_actor_get_last_child(). It is also possible to retrieve a list of children by using clutter_actor_get_children(), as well as retrieving a specific child at a given index by using clutter_actor_get_child_at_index().

If you need to track additions of children to a ClutterActor, use the "actor-added" signal; similarly, to track removals of children from a ClutterActor, use the "actor-removed" signal.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

#include <stdlib.h>
#include <clutter/clutter.h>

#define SIZE    128

static gboolean
animate_color (ClutterActor *actor,
               ClutterEvent *event)
{
  static gboolean toggled = TRUE;
  const ClutterColor *end_color;

  if (toggled)
    end_color = CLUTTER_COLOR_Blue;
  else
    end_color = CLUTTER_COLOR_Red;

  clutter_actor_save_easing_state (actor);
  clutter_actor_set_easing_duration (actor, 500);
  clutter_actor_set_easing_mode (actor, CLUTTER_LINEAR);
  clutter_actor_set_background_color (actor, end_color);
  clutter_actor_restore_easing_state (actor);

  toggled = !toggled;

  return CLUTTER_EVENT_STOP;
}

static gboolean
on_crossing (ClutterActor *actor,
             ClutterEvent *event)
{
  gboolean is_enter = clutter_event_type (event) == CLUTTER_ENTER;
  float zpos;

  if (is_enter)
    zpos = -250.0;
  else
    zpos = 0.0;

  clutter_actor_save_easing_state (actor);
  clutter_actor_set_easing_duration (actor, 500);
  clutter_actor_set_easing_mode (actor, CLUTTER_EASE_OUT_BOUNCE);
  clutter_actor_set_z_position (actor, zpos);
  clutter_actor_restore_easing_state (actor);

  return CLUTTER_EVENT_STOP;
}

static void
on_transition_stopped (ClutterActor *actor,
                       const gchar  *transition_name,
                       gboolean      is_finished)
{
  clutter_actor_save_easing_state (actor);
  clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 0.0f);
  clutter_actor_restore_easing_state (actor);

  /* disconnect so we don't get multiple notifications */
  g_signal_handlers_disconnect_by_func (actor,
                                        on_transition_stopped,
                                        NULL);
}

static gboolean
animate_rotation (ClutterActor *actor,
                  ClutterEvent *event)
{
  clutter_actor_save_easing_state (actor);
  clutter_actor_set_easing_duration (actor, 1000);

  clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 360.0);

  clutter_actor_restore_easing_state (actor);

  /* get a notification when the rotation-angle-y transition ends */
  g_signal_connect (actor,
                    "transition-stopped::rotation-angle-y",
                    G_CALLBACK (on_transition_stopped),
                    NULL);

  return CLUTTER_EVENT_STOP;
}

int
main (int argc, char *argv[])
{
  ClutterActor *stage, *vase;
  ClutterActor *flowers[3];

  if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
    return EXIT_FAILURE;

  stage = clutter_stage_new ();
  g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
  clutter_stage_set_title (CLUTTER_STAGE (stage), "Three Flowers in a Vase");
  clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);

  /* there are three flowers in a vase */
  vase = clutter_actor_new ();
  clutter_actor_set_name (vase, "vase");
  clutter_actor_set_layout_manager (vase, clutter_box_layout_new ());
  clutter_actor_set_background_color (vase, CLUTTER_COLOR_LightSkyBlue);
  clutter_actor_add_constraint (vase, clutter_align_constraint_new (stage, CLUTTER_ALIGN_BOTH, 0.5));
  clutter_actor_add_child (stage, vase);

  flowers[0] = clutter_actor_new ();
  clutter_actor_set_name (flowers[0], "flower.1");
  clutter_actor_set_size (flowers[0], SIZE, SIZE);
  clutter_actor_set_margin_left (flowers[0], 12);
  clutter_actor_set_background_color (flowers[0], CLUTTER_COLOR_Red);
  clutter_actor_set_reactive (flowers[0], TRUE);
  clutter_actor_add_child (vase, flowers[0]);
  g_signal_connect (flowers[0], "button-press-event",
                    G_CALLBACK (animate_color),
                    NULL);

  flowers[1] = clutter_actor_new ();
  clutter_actor_set_name (flowers[1], "flower.2");
  clutter_actor_set_size (flowers[1], SIZE, SIZE);
  clutter_actor_set_margin_top (flowers[1], 12);
  clutter_actor_set_margin_left (flowers[1], 6);
  clutter_actor_set_margin_right (flowers[1], 6);
  clutter_actor_set_margin_bottom (flowers[1], 12);
  clutter_actor_set_background_color (flowers[1], CLUTTER_COLOR_Yellow);
  clutter_actor_set_reactive (flowers[1], TRUE);
  clutter_actor_add_child (vase, flowers[1]);
  g_signal_connect (flowers[1], "enter-event",
                    G_CALLBACK (on_crossing),
                    NULL);
  g_signal_connect (flowers[1], "leave-event",
                    G_CALLBACK (on_crossing),
                    NULL);

  /* the third one is green */
  flowers[2] = clutter_actor_new ();
  clutter_actor_set_name (flowers[2], "flower.3");
  clutter_actor_set_size (flowers[2], SIZE, SIZE);
  clutter_actor_set_margin_right (flowers[2], 12);
  clutter_actor_set_background_color (flowers[2], CLUTTER_COLOR_Green);
  clutter_actor_set_pivot_point (flowers[2], 0.5f, 0.0f);
  clutter_actor_set_reactive (flowers[2], TRUE);
  clutter_actor_add_child (vase, flowers[2]);
  g_signal_connect (flowers[2], "button-press-event",
                    G_CALLBACK (animate_rotation),
                    NULL);

  clutter_actor_show (stage);

  clutter_main ();

  return EXIT_SUCCESS;
}

Figure 1. Actors

Painting an actor

There are three ways to paint an actor:

Setting the Content property. A ClutterContent is a delegate object that takes over the painting operation of one, or more actors. The ClutterContent painting will be performed on top of the "background-color" of the actor, and before calling the ClutterActorClass.paint_node() virtual function.

1
2
3
4
5
6
7
8

ClutterActor *actor = clutter_actor_new ();

/* set the bounding box */
clutter_actor_set_position (actor, 50, 50);
clutter_actor_set_size (actor, 100, 100);

/* set the content; the image_content variable is set elsewhere */
clutter_actor_set_content (actor, image_content);

Overriding the paint_node virtual function. The ClutterActorClass.paint_node() virtual function is invoked whenever an actor needs to be painted. The implementation of the virtual function must only paint the contents of the actor itself, and not the contents of its children, if the actor has any.The ClutterPaintNode passed to the virtual function is the local root of the render tree; any node added to it will be rendered at the correct position, as defined by the actor's "allocation".

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

static void
my_actor_paint_node (ClutterActor     *actor,
                     ClutterPaintNode *root)
{
  ClutterPaintNode *node;
  ClutterActorBox box;

  /* where the content of the actor should be painted */
  clutter_actor_get_allocation_box (actor, &box);

  /* the cogl_texture variable is set elsewhere */
  node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
                                   CLUTTER_SCALING_FILTER_TRILINEAR,
                                   CLUTTER_SCALING_FILTER_LINEAR);

  /* paint the content of the node using the allocation */
  clutter_paint_node_add_rectangle (node, &box);

  /* add the node, and transfer ownership */
  clutter_paint_node_add_child (root, node);
  clutter_paint_node_unref (node);
}

Overriding the paint virtual function. The ClutterActorClass.paint() virtual function is invoked when the "paint" signal is emitted, and after the other signal handlers have been invoked. Overriding the paint virtual function gives total control to the paint sequence of the actor itself, including the children of the actor, if any.

Handling events on an actor

A ClutterActor can receive and handle input device events, for instance pointer events and key events, as long as its "reactive" property is set to TRUE.

Once an actor has been determined to be the source of an event, Clutter will traverse the scene graph from the top-level actor towards the event source, emitting the "captured-event" signal on each ancestor until it reaches the source; this phase is also called the capture phase. If the event propagation was not stopped, the graph is walked backwards, from the source actor to the top-level, and the "event" signal, along with other event signals if needed, is emitted; this phase is also called the bubble phase. At any point of the signal emission, signal handlers can stop the propagation through the scene graph by returning CLUTTER_EVENT_STOP; otherwise, they can continue the propagation by returning CLUTTER_EVENT_PROPAGATE.

Animation

Animation is a core concept of modern user interfaces; Clutter provides a complete and powerful animation framework that automatically tweens the actor's state without requiring direct, frame by frame manipulation from your application code.

Implicit animations. The implicit animation model of Clutter assumes that all the changes in an actor state should be gradual and asynchronous; Clutter will automatically transition an actor's property change between the current state and the desired one without manual intervention, if the property is defined to be animatable in its documentation.

Implicit animations depend on the current easing state; in order to use the default easing state for an actor you should call the clutter_actor_save_easing_state() function:

1
2
3
4

/* assume that the actor is currently positioned at (100, 100) */
clutter_actor_save_easing_state (actor);
clutter_actor_set_position (actor, 500, 500);
clutter_actor_restore_easing_state (actor);

The example above will trigger an implicit animation of the actor between its current position to a new position.It is possible to animate multiple properties of an actor at the same time, and you can animate multiple actors at the same time as well, for instance:

1
2
3
4
5
6
7
8
9
10
11

/* animate the actor's opacity and depth */
clutter_actor_save_easing_state (actor);
clutter_actor_set_opacity (actor, 0);
clutter_actor_set_depth (actor, -100);
clutter_actor_restore_easing_state (actor);

/* animate another actor's opacity */
clutter_actor_save_easing_state (another_actor);
clutter_actor_set_opacity (another_actor, 255);
clutter_actor_set_depth (another_actor, 100);
clutter_actor_restore_easing_state (another_actor);

Implicit animations use a default duration of 250 milliseconds, and a default easing mode of CLUTTER_EASE_OUT_CUBIC, unless you call clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration() after changing the easing state of the actor.Changing the easing state will affect all the following property transitions, but will not affect existing transitions.It is important to note that if you modify the state on an animatable property while a transition is in flight, the transition's final value will be updated, as well as its duration and progress mode by using the current easing state; for instance, in the following example:

1
2
3
4
5
6
7
8
9

clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 1000);
clutter_actor_set_x (actor, 200);
clutter_actor_restore_easing_state (actor);

clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 500);
clutter_actor_set_x (actor, 100);
clutter_actor_restore_easing_state (actor);

the first call to clutter_actor_set_x() will begin a transition of the "x" property from the current value to the value of 200 over a duration of one second; the second call to clutter_actor_set_x() will change the transition's final value to 100 and the duration to 500 milliseconds.It is possible to retrieve the ClutterTransition used by the animatable properties by using clutter_actor_get_transition() and using the property name as the transition name.

Explicit animations. The explicit animation model supported by Clutter requires that you create a ClutterTransition object, and set the initial and final values. The transition will not start unless you add it to the ClutterActor.

1
2
3
4
5
6
7
8
9
10

ClutterTransition *transition;

transition = clutter_property_transition_new ("opacity");
clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2);
clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
clutter_transition_set_from (transition, G_TYPE_UINT, 255);
clutter_transition_set_to (transition, G_TYPE_UINT, 0);

clutter_actor_add_transition (actor, "animate-opacity", transition);

The example above will animate the "opacity" property of an actor between fully opaque and fully transparent, and back, over a span of 3 seconds. The animation does not begin until it is added to the actor.The explicit animation API applies to all GObject properties, as well as the custom properties defined through the ClutterAnimatable interface, regardless of whether they are defined as implicitly animatable or not.The explicit animation API should also be used when using custom animatable properties for ClutterAction, ClutterConstraint, and ClutterEffect instances associated to an actor; see the section on custom animatable properties below for an example.Finally, explicit animations are useful for creating animations that run continuously, for instance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

/* this animation will pulse the actor's opacity continuously */
ClutterTransition *transition;
ClutterInterval *interval;

transition = clutter_property_transition_new ("opacity");

/* we want to animate the opacity between 0 and 255 */
clutter_transition_set_from (transition, G_TYPE_UINT, 0);
clutter_transition_set_to (transition, G_TYPE_UINT, 255);

/* over a one second duration, running an infinite amount of times */
clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);

/* we want to fade in and out, so we need to auto-reverse the transition */
clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);

/* and we want to use an easing function that eases both in and out */
clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                    CLUTTER_EASE_IN_OUT_CUBIC);

/* add the transition to the desired actor; this will
 * start the animation.
 */
clutter_actor_add_transition (actor, "opacityAnimation", transition);

Implementing an actor

Careful consideration should be given when deciding to implement a ClutterActor sub-class. It is generally recommended to implement a sub-class of ClutterActor only for actors that should be used as leaf nodes of a scene graph.

If your actor should be painted in a custom way, you should override the "paint" signal class handler. You can either opt to chain up to the parent class implementation or decide to fully override the default paint implementation; Clutter will set up the transformations and clip regions prior to emitting the "paint" signal.

By overriding the ClutterActorClass.get_preferred_width() and ClutterActorClass.get_preferred_height() virtual functions it is possible to change or provide the preferred size of an actor; similarly, by overriding the ClutterActorClass.allocate() virtual function it is possible to control the layout of the children of an actor. Make sure to always chain up to the parent implementation of the ClutterActorClass.allocate() virtual function.

In general, it is strongly encouraged to use delegation and composition instead of direct subclassing.

ClutterActor custom properties for ClutterScript

ClutterActor defines a custom "rotation" property which allows a short-hand description of the rotations to be applied to an actor.

The syntax of the "rotation" property is the following:

1
2
3

"rotation" : [
  { "<axis>" : [ <angle>, [ <center> ] ] }
]

where the axis is the name of an enumeration value of type ClutterRotateAxis and angle is a floating point value representing the rotation angle on the given axis, in degrees.

The center array is optional, and if present it must contain the center of rotation as described by two coordinates: Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for "z-axis".

ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand.

1
2
3
4
5
6
7
8

// 4 values
"margin" : [ <top>, <right>, <bottom> <left> ]
// 3 values
"margin" : [ <top>, <left/right>, <bottom> ]
// 2 values
"margin" : [ <top/bottom>, <left/right> ]
// 1 value
"margin" : [ <top/right/bottom/left> ]

ClutterActor will also parse every positional and dimensional property defined as a string through clutter_units_from_string(); you should read the documentation for the ClutterUnits parser format for the valid units and syntax.

Custom animatable properties

ClutterActor allows accessing properties of ClutterAction, ClutterEffect, and ClutterConstraint instances associated to an actor instance for animation purposes.

In order to access a specific ClutterAction or a ClutterConstraint property it is necessary to set the "name" property on the given action or constraint.

The property can be accessed using the following syntax:

1

@<section>.<meta-name>.<property-name>

The initial @ is mandatory.

The section fragment can be one between "actions", "constraints" and "effects".

The meta-name fragment is the name of the action or constraint, as specified by the "name" property.

The property-name fragment is the name of the action or constraint property to be animated.

The example below animates a ClutterBindConstraint applied to an actor using clutter_actor_animate(). The rect has a binding constraint for the origin actor, and in its initial state is overlapping the actor to which is bound to.

1
2
3
4
5
6
7
8
9
10
11
12
13

constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
clutter_actor_add_constraint (rect, constraint);

constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_Y, 0.0);
clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y");
clutter_actor_add_constraint (rect, constraint);

clutter_actor_set_reactive (origin, TRUE);

g_signal_connect (origin, "button-press-event",
                  G_CALLBACK (on_button_press),
                  rect);

On button press, the rectangle "slides" from behind the actor to which is bound to, using the "offset" property to achieve the effect:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

gboolean
on_button_press (ClutterActor *origin,
                 ClutterEvent *event,
                 ClutterActor *rect)
{
  ClutterTransition *transition;

  /* the offset that we want to apply; this will make the actor
   * slide in from behind the origin and rest at the right of
   * the origin, plus a padding value.
   */
  float new_offset = clutter_actor_get_width (origin) + h_padding;

  /* the property we wish to animate; the "@constraints" section
   * tells Clutter to check inside the constraints associated
   * with the actor; the "bind-x" section is the name of the
   * constraint; and the "offset" is the name of the property
   * on the constraint.
   */
  const char *prop = "@constraints.bind-x.offset";

  /* create a new transition for the given property */
  transition = clutter_property_transition_new (prop);

  /* set the easing mode and duration */
  clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                      CLUTTER_EASE_OUT_CUBIC);
  clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);

  /* create the interval with the initial and final values */
  clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f);
  clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset);

  /* add the transition to the actor; this causes the animation
   * to start. the name "offsetAnimation" can be used to retrieve
   * the transition later.
   */
  clutter_actor_add_transition (rect, "offsetAnimation", transition);

  /* we handled the event */
  return CLUTTER_EVENT_STOP;
}

CLUTTER_ACTOR_SET_FLAGS()

#define CLUTTER_ACTOR_SET_FLAGS(a,f)    (((ClutterActor*)(a))->flags |= (f))

Sets the given flags on a ClutterActor

CLUTTER_ACTOR_UNSET_FLAGS()

#define CLUTTER_ACTOR_UNSET_FLAGS(a,f)  (((ClutterActor*)(a))->flags &= ~(f))

Unsets the given flags on a ClutterActor

CLUTTER_ACTOR_IS_MAPPED()

#define CLUTTER_ACTOR_IS_MAPPED(a)      ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_MAPPED) != FALSE)

Evaluates to TRUE if the CLUTTER_ACTOR_MAPPED flag is set.

The mapped state is set when the actor is visible and all its parents up to a top-level (e.g. a ClutterStage) are visible, realized, and mapped.

This check can be used to see if an actor is going to be painted, as only actors with the CLUTTER_ACTOR_MAPPED flag set are going to be painted.

The CLUTTER_ACTOR_MAPPED flag is managed by Clutter itself, and it should not be checked directly; instead, the recommended usage is to connect a handler on the "notify" signal for the "mapped" property of ClutterActor, and check the presence of the CLUTTER_ACTOR_MAPPED flag on state changes.

It is also important to note that Clutter may delay the changes of the CLUTTER_ACTOR_MAPPED flag on top-levels due to backend-specific limitations, or during the reparenting of an actor, to optimize unnecessary (and potentially expensive) state changes.

Since 0.2

CLUTTER_ACTOR_IS_REALIZED()

#define CLUTTER_ACTOR_IS_REALIZED(a)    ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_REALIZED) != FALSE)

Evaluates to TRUE if the CLUTTER_ACTOR_REALIZED flag is set.

The realized state has an actor-dependant interpretation. If an actor wants to delay allocating resources until it is attached to a stage, it may use the realize state to do so. However it is perfectly acceptable for an actor to allocate Cogl resources before being realized because there is only one drawing context used by Clutter so any resources will work on any stage. If an actor is mapped it must also be realized, but an actor can be realized and unmapped (this is so hiding an actor temporarily doesn't do an expensive unrealize/realize).

To be realized an actor must be inside a stage, and all its parents must be realized.

Since 0.2

CLUTTER_ACTOR_IS_VISIBLE()

#define CLUTTER_ACTOR_IS_VISIBLE(a)     ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_VISIBLE) != FALSE)

Evaluates to TRUE if the actor has been shown, FALSE if it's hidden. Equivalent to the ClutterActor::visible object property.

Note that an actor is only painted onscreen if it's mapped, which means it's visible, and all its parents are visible, and one of the parents is a toplevel stage; see also CLUTTER_ACTOR_IS_MAPPED.

Since 0.2

CLUTTER_ACTOR_IS_REACTIVE()

#define CLUTTER_ACTOR_IS_REACTIVE(a)    ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_REACTIVE) != FALSE)

Evaluates to TRUE if the CLUTTER_ACTOR_REACTIVE flag is set.

Only reactive actors will receive event-related signals.

Since 0.6

enum ClutterActorFlags

typedef enum {
 /*< prefix=CLUTTER_ACTOR >*/
  CLUTTER_ACTOR_MAPPED    = 1 << 1,
  CLUTTER_ACTOR_REALIZED  = 1 << 2,
  CLUTTER_ACTOR_REACTIVE  = 1 << 3,
  CLUTTER_ACTOR_VISIBLE   = 1 << 4,
  CLUTTER_ACTOR_NO_LAYOUT = 1 << 5
} ClutterActorFlags;

Flags used to signal the state of an actor.

enum ClutterRequestMode

typedef enum {
 /*< prefix=CLUTTER_REQUEST >*/
  CLUTTER_REQUEST_HEIGHT_FOR_WIDTH,
  CLUTTER_REQUEST_WIDTH_FOR_HEIGHT
} ClutterRequestMode;

Specifies the type of requests for a ClutterActor.

Since 0.8

CLUTTER_CALLBACK()

#define CLUTTER_CALLBACK(f)        ((ClutterCallback) (f))

Convenience macro to cast a function to ClutterCallback

ClutterCallback ()

void                (*ClutterCallback)                  (ClutterActor *actor,
                                                         gpointer data);

Generic callback

ClutterActor

typedef struct {
  guint32 flags;
} ClutterActor;

Base class for actors.

struct ClutterActorClass

struct ClutterActorClass {
  void (* show)                 (ClutterActor          *self);
  void (* show_all)             (ClutterActor          *self);
  void (* hide)                 (ClutterActor          *self);
  void (* hide_all)             (ClutterActor          *self);
  void (* realize)              (ClutterActor          *self);
  void (* unrealize)            (ClutterActor          *self);
  void (* map)                  (ClutterActor          *self);
  void (* unmap)                (ClutterActor          *self);
  void (* paint)                (ClutterActor          *self);
  void (* parent_set)           (ClutterActor          *actor,
                                 ClutterActor          *old_parent);

  void (* destroy)              (ClutterActor          *self);
  void (* pick)                 (ClutterActor          *actor,
                                 const ClutterColor    *color);

  void (* queue_redraw)         (ClutterActor          *actor,
                                 ClutterActor          *leaf_that_queued);

  /* size negotiation */
  void (* get_preferred_width)  (ClutterActor           *self,
                                 gfloat                  for_height,
                                 gfloat                 *min_width_p,
                                 gfloat                 *natural_width_p);
  void (* get_preferred_height) (ClutterActor           *self,
                                 gfloat                  for_width,
                                 gfloat                 *min_height_p,
                                 gfloat                 *natural_height_p);
  void (* allocate)             (ClutterActor           *self,
                                 const ClutterActorBox  *box,
                                 ClutterAllocationFlags  flags);

  /* transformations */
  void (* apply_transform)      (ClutterActor           *actor,
                                 ClutterMatrix          *matrix);

  /* event signals */
  gboolean (* event)                (ClutterActor         *actor,
                                     ClutterEvent         *event);
  gboolean (* button_press_event)   (ClutterActor         *actor,
                                     ClutterButtonEvent   *event);
  gboolean (* button_release_event) (ClutterActor         *actor,
                                     ClutterButtonEvent   *event);
  gboolean (* scroll_event)         (ClutterActor         *actor,
                                     ClutterScrollEvent   *event);
  gboolean (* key_press_event)      (ClutterActor         *actor,
                                     ClutterKeyEvent      *event);
  gboolean (* key_release_event)    (ClutterActor         *actor,
                                     ClutterKeyEvent      *event);
  gboolean (* motion_event)         (ClutterActor         *actor,
                                     ClutterMotionEvent   *event);
  gboolean (* enter_event)          (ClutterActor         *actor,
                                     ClutterCrossingEvent *event);
  gboolean (* leave_event)          (ClutterActor         *actor,
                                     ClutterCrossingEvent *event);
  gboolean (* captured_event)       (ClutterActor         *actor,
                                     ClutterEvent         *event);
  void     (* key_focus_in)         (ClutterActor         *actor);
  void     (* key_focus_out)        (ClutterActor         *actor);

  void     (* queue_relayout)       (ClutterActor         *self);

  /* accessibility support */
  AtkObject * (* get_accessible)    (ClutterActor         *self);

  gboolean (* get_paint_volume)     (ClutterActor         *actor,
                                     ClutterPaintVolume   *volume);

  gboolean (* has_overlaps)         (ClutterActor         *self);

  void     (* paint_node)           (ClutterActor         *self,
                                     ClutterPaintNode     *root);

  gboolean (* touch_event)          (ClutterActor         *self,
                                     ClutterTouchEvent    *event);
};

Base class for actors.

clutter_actor_new ()

ClutterActor *      clutter_actor_new                   (void);

Creates a new ClutterActor.

A newly created actor has a floating reference, which will be sunk when it is added to another actor.

Since 1.10

clutter_actor_set_flags ()

void                clutter_actor_set_flags             (ClutterActor *self,
                                                         ClutterActorFlags flags);

Sets flags on self

This function will emit notifications for the changed properties

Since 1.0

clutter_actor_unset_flags ()

void                clutter_actor_unset_flags           (ClutterActor *self,
                                                         ClutterActorFlags flags);

Unsets flags on self

This function will emit notifications for the changed properties

Since 1.0

clutter_actor_get_flags ()

ClutterActorFlags   clutter_actor_get_flags             (ClutterActor *self);

Retrieves the flags set on self

Since 1.0

clutter_actor_set_name ()

void                clutter_actor_set_name              (ClutterActor *self,
                                                         const gchar *name);

Sets the given name to self. The name can be used to identify a ClutterActor.

clutter_actor_get_name ()

const gchar *       clutter_actor_get_name              (ClutterActor *self);

Retrieves the name of self.

clutter_actor_get_gid ()

guint32             clutter_actor_get_gid               (ClutterActor *self);

Retrieves the unique id for self.

Since 0.6

clutter_actor_show ()

void                clutter_actor_show                  (ClutterActor *self);

Flags an actor to be displayed. An actor that isn't shown will not be rendered on the stage.

Actors are visible by default.

If this function is called on an actor without a parent, the "show-on-set-parent" will be set to TRUE as a side effect.

clutter_actor_show_all ()

void                clutter_actor_show_all              (ClutterActor *self);

Calls clutter_actor_show() on all children of an actor (if any).

Since 0.2

clutter_actor_hide ()

void                clutter_actor_hide                  (ClutterActor *self);

Flags an actor to be hidden. A hidden actor will not be rendered on the stage.

Actors are visible by default.

If this function is called on an actor without a parent, the "show-on-set-parent" property will be set to FALSE as a side-effect.

clutter_actor_hide_all ()

void                clutter_actor_hide_all              (ClutterActor *self);

Calls clutter_actor_hide() on all child actors (if any).

Since 0.2

clutter_actor_realize ()

void                clutter_actor_realize               (ClutterActor *self);

Realization informs the actor that it is attached to a stage. It can use this to allocate resources if it wanted to delay allocation until it would be rendered. However it is perfectly acceptable for an actor to create resources before being realized because Clutter only ever has a single rendering context so that actor is free to be moved from one stage to another.

This function does nothing if the actor is already realized.

Because a realized actor must have realized parent actors, calling clutter_actor_realize() will also realize all parents of the actor.

This function does not realize child actors, except in the special case that realizing the stage, when the stage is visible, will suddenly map (and thus realize) the children of the stage.

clutter_actor_unrealize ()

void                clutter_actor_unrealize             (ClutterActor *self);

Unrealization informs the actor that it may be being destroyed or moved to another stage. The actor may want to destroy any underlying graphics resources at this point. However it is perfectly acceptable for it to retain the resources until the actor is destroyed because Clutter only ever uses a single rendering context and all of the graphics resources are valid on any stage.

Because mapped actors must be realized, actors may not be unrealized if they are mapped. This function hides the actor to be sure it isn't mapped, an application-visible side effect that you may not be expecting.

This function should not be called by application code.

This function should not really be in the public API, because there isn't a good reason to call it. ClutterActor will already unrealize things for you when it's important to do so.

If you were using clutter_actor_unrealize() in a dispose implementation, then don't, just chain up to ClutterActor's dispose.

If you were using clutter_actor_unrealize() to implement unrealizing children of your container, then don't, ClutterActor will already take care of that.

clutter_actor_paint ()

void                clutter_actor_paint                 (ClutterActor *self);

Renders the actor to display.

This function should not be called directly by applications. Call clutter_actor_queue_redraw() to queue paints, instead.

This function is context-aware, and will either cause a regular paint or a pick paint.

This function will emit the "paint" signal or the "pick" signal, depending on the context.

This function does not paint the actor if the actor is set to 0, unless it is performing a pick paint.

clutter_actor_continue_paint ()

void                clutter_actor_continue_paint        (ClutterActor *self);

Run the next stage of the paint sequence. This function should only be called within the implementation of the ‘run’ virtual of a ClutterEffect. It will cause the run method of the next effect to be applied, or it will paint the actual actor if the current effect is the last effect in the chain.

Since 1.8

clutter_actor_queue_redraw ()

void                clutter_actor_queue_redraw          (ClutterActor *self);

Queues up a redraw of an actor and any children. The redraw occurs once the main loop becomes idle (after the current batch of events has been processed, roughly).

Applications rarely need to call this, as redraws are handled automatically by modification functions.

This function will not do anything if self is not visible, or if the actor is inside an invisible part of the scenegraph.

Also be aware that painting is a NOP for actors with an opacity of 0

When you are implementing a custom actor you must queue a redraw whenever some private state changes that will affect painting or picking of your actor.

clutter_actor_queue_redraw_with_clip ()

void                clutter_actor_queue_redraw_with_clip
                                                        (ClutterActor *self,
                                                         const cairo_rectangle_int_t *clip);

Queues a redraw on self limited to a specific, actor-relative rectangular area.

If clip is NULL this function is equivalent to clutter_actor_queue_redraw().

Since 1.10

clutter_actor_queue_relayout ()

void                clutter_actor_queue_relayout        (ClutterActor *self);

Indicates that the actor's size request or other layout-affecting properties may have changed. This function is used inside ClutterActor subclass implementations, not by applications directly.

Queueing a new layout automatically queues a redraw as well.

Since 0.8

clutter_actor_destroy ()

void                clutter_actor_destroy               (ClutterActor *self);

Destroys an actor. When an actor is destroyed, it will break any references it holds to other objects. If the actor is inside a container, the actor will be removed.

When you destroy a container, its children will be destroyed as well.

Note: you cannot destroy the ClutterStage returned by clutter_stage_get_default().

clutter_actor_event ()

gboolean            clutter_actor_event                 (ClutterActor *actor,
                                                         const ClutterEvent *event,
                                                         gboolean capture);

This function is used to emit an event on the main stage. You should rarely need to use this function, except for synthetising events.

Since 0.6

clutter_actor_should_pick_paint ()

gboolean            clutter_actor_should_pick_paint     (ClutterActor *self);

Should be called inside the implementation of the "pick" virtual function in order to check whether the actor should paint itself in pick mode or not.

This function should never be called directly by applications.

clutter_actor_map ()

void                clutter_actor_map                   (ClutterActor *self);

Sets the CLUTTER_ACTOR_MAPPED flag on the actor and possibly maps and realizes its children if they are visible. Does nothing if the actor is not visible.

Calling this function is strongly disencouraged: the default implementation of ClutterActorClass.map() will map all the children of an actor when mapping its parent.

When overriding map, it is mandatory to chain up to the parent implementation.

Since 1.0

clutter_actor_unmap ()

void                clutter_actor_unmap                 (ClutterActor *self);

Unsets the CLUTTER_ACTOR_MAPPED flag on the actor and possibly unmaps its children if they were mapped.

Calling this function is not encouraged: the default ClutterActor implementation of ClutterActorClass.unmap() will also unmap any eventual children by default when their parent is unmapped.

When overriding ClutterActorClass.unmap(), it is mandatory to chain up to the parent implementation.

Since 1.0

clutter_actor_has_overlaps ()

gboolean            clutter_actor_has_overlaps          (ClutterActor *self);

Asks the actor's implementation whether it may contain overlapping primitives.

For example; Clutter may use this to determine whether the painting should be redirected to an offscreen buffer to correctly implement the opacity property.

Custom actors can override the default response by implementing the ClutterActor has_overlaps virtual function. See clutter_actor_set_offscreen_redirect() for more information.

Since 1.8

clutter_actor_has_mapped_clones ()

gboolean            clutter_actor_has_mapped_clones     (ClutterActor *self);

Since 1.16

enum ClutterAllocationFlags

typedef enum {
  CLUTTER_ALLOCATION_NONE         = 0,
  CLUTTER_ABSOLUTE_ORIGIN_CHANGED = 1 << 1,
  CLUTTER_DELEGATE_LAYOUT         = 1 << 2
} ClutterAllocationFlags;

Flags passed to the ClutterActorClass.allocate() virtual function and to the clutter_actor_allocate() function.

Since 1.0

clutter_actor_allocate ()

void                clutter_actor_allocate              (ClutterActor *self,
                                                         const ClutterActorBox *box,
                                                         ClutterAllocationFlags flags);

Assigns the size of a ClutterActor from the given box.

This function should only be called on the children of an actor when overriding the ClutterActorClass.allocate() virtual function.

This function will adjust the stored allocation to take into account the alignment flags set in the "x-align" and "y-align" properties, as well as the margin values set in the "margin-top", "margin-right", "margin-bottom", and "margin-left" properties.

This function will respect the easing state of the ClutterActor and interpolate between the current allocation and the new one if the easing state duration is a positive value.

Actors can know from their allocation box whether they have moved with respect to their parent actor. The flags parameter describes additional information about the allocation, for instance whether the parent has moved with respect to the stage, for example because a grandparent's origin has moved.

Since 0.8

clutter_actor_allocate_preferred_size ()

void                clutter_actor_allocate_preferred_size
                                                        (ClutterActor *self,
                                                         ClutterAllocationFlags flags);

Allocates the natural size of self.

This function is a utility call for ClutterActor implementations that allocates the actor's preferred natural size. It can be used by fixed layout managers (like ClutterGroup or so called 'composite actors') inside the ClutterActor::allocate implementation to give each child exactly how much space it requires, regardless of the size of the parent.

This function is not meant to be used by applications. It is also not meant to be used outside the implementation of the ClutterActorClass.allocate virtual function.

Since 0.8

clutter_actor_allocate_available_size ()

void                clutter_actor_allocate_available_size
                                                        (ClutterActor *self,
                                                         gfloat x,
                                                         gfloat y,
                                                         gfloat available_width,
                                                         gfloat available_height,
                                                         ClutterAllocationFlags flags);

Allocates self taking into account the ClutterActor's preferred size, but limiting it to the maximum available width and height provided.

This function will do the right thing when dealing with the actor's request mode.

The implementation of this function is equivalent to:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
  {
    clutter_actor_get_preferred_width (self, available_height,
                                       &min_width,
                                       &natural_width);
    width = CLAMP (natural_width, min_width, available_width);

    clutter_actor_get_preferred_height (self, width,
                                        &min_height,
                                        &natural_height);
    height = CLAMP (natural_height, min_height, available_height);
  }
else
  {
    clutter_actor_get_preferred_height (self, available_width,
                                        &min_height,
                                        &natural_height);
    height = CLAMP (natural_height, min_height, available_height);

    clutter_actor_get_preferred_width (self, height,
                                       &min_width,
                                       &natural_width);
    width = CLAMP (natural_width, min_width, available_width);
  }

box.x1 = x; box.y1 = y;
box.x2 = box.x1 + available_width;
box.y2 = box.y1 + available_height;
clutter_actor_allocate (self, &box, flags);

This function can be used by fluid layout managers to allocate an actor's preferred size without making it bigger than the area available for the container.

Since 1.0

clutter_actor_allocate_align_fill ()

void                clutter_actor_allocate_align_fill   (ClutterActor *self,
                                                         const ClutterActorBox *box,
                                                         gdouble x_align,
                                                         gdouble y_align,
                                                         gboolean x_fill,
                                                         gboolean y_fill,
                                                         ClutterAllocationFlags flags);

Allocates self by taking into consideration the available allocation area; an alignment factor on either axis; and whether the actor should fill the allocation on either axis.

The box should contain the available allocation width and height; if the x1 and y1 members of ClutterActorBox are not set to 0, the allocation will be offset by their value.

This function takes into consideration the geometry request specified by the "request-mode" property, and the text direction.

This function is useful for fluid layout managers using legacy alignment flags. Newly written layout managers should use the "x-align" and "y-align" properties, instead, and just call clutter_actor_allocate() inside their ClutterActorClass.allocate() implementation.

Since 1.4

clutter_actor_set_allocation ()

void                clutter_actor_set_allocation        (ClutterActor *self,
                                                         const ClutterActorBox *box,
                                                         ClutterAllocationFlags flags);

Stores the allocation of self as defined by box.

This function can only be called from within the implementation of the ClutterActorClass.allocate() virtual function.

The allocation should have been adjusted to take into account constraints, alignment, and margin properties. If you are implementing a ClutterActor subclass that provides its own layout management policy for its children instead of using a ClutterLayoutManager delegate, you should not call this function on the children of self; instead, you should call clutter_actor_allocate(), which will adjust the allocation box for you.

This function should only be used by subclasses of ClutterActor that wish to store their allocation but cannot chain up to the parent's implementation; the default implementation of the ClutterActorClass.allocate() virtual function will call this function.

It is important to note that, while chaining up was the recommended behaviour for ClutterActor subclasses prior to the introduction of this function, it is recommended to call clutter_actor_set_allocation() instead.

If the ClutterActor is using a ClutterLayoutManager delegate object to handle the allocation of its children, this function will call the clutter_layout_manager_allocate() function only if the CLUTTER_DELEGATE_LAYOUT flag is set on flags, otherwise it is expected that the subclass will call clutter_layout_manager_allocate() by itself. For instance, the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

static void
my_actor_allocate (ClutterActor *actor,
                   const ClutterActorBox *allocation,
                   ClutterAllocationFlags flags)
{
  ClutterActorBox new_alloc;
  ClutterAllocationFlags new_flags;

  adjust_allocation (allocation, &new_alloc);

  new_flags = flags | CLUTTER_DELEGATE_LAYOUT;

  /* this will use the layout manager set on the actor */
  clutter_actor_set_allocation (actor, &new_alloc, new_flags);
}

is equivalent to this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

static void
my_actor_allocate (ClutterActor *actor,
                   const ClutterActorBox *allocation,
                   ClutterAllocationFlags flags)
{
  ClutterLayoutManager *layout;
  ClutterActorBox new_alloc;

  adjust_allocation (allocation, &new_alloc);

  clutter_actor_set_allocation (actor, &new_alloc, flags);

  layout = clutter_actor_get_layout_manager (actor);
  clutter_layout_manager_allocate (layout,
                                   CLUTTER_CONTAINER (actor),
                                   &new_alloc,
                                   flags);
}

Since 1.10

clutter_actor_get_allocation_box ()

void                clutter_actor_get_allocation_box    (ClutterActor *self,
                                                         ClutterActorBox *box);

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.

An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Since 0.8

clutter_actor_get_allocation_geometry ()

void                clutter_actor_get_allocation_geometry
                                                        (ClutterActor *self,
                                                         ClutterGeometry *geom);

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint() method; anywhere else, it may be out-of-date.

An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

The returned rectangle is in pixels.

Since 0.8

clutter_actor_get_allocation_vertices ()

void                clutter_actor_get_allocation_vertices
                                                        (ClutterActor *self,
                                                         ClutterActor *ancestor,
                                                         ClutterVertex verts[]);

Calculates the transformed coordinates of the four corners of the actor in the plane of ancestor. The returned vertices relate to the ClutterActorBox coordinates as follows:

If ancestor is NULL the ancestor will be the ClutterStage. In this case, the coordinates returned will be the coordinates on the stage before the projection is applied. This is different from the behaviour of clutter_actor_get_abs_allocation_vertices().

Since 0.6

clutter_actor_get_preferred_size ()

void                clutter_actor_get_preferred_size    (ClutterActor *self,
                                                         gfloat *min_width_p,
                                                         gfloat *min_height_p,
                                                         gfloat *natural_width_p,
                                                         gfloat *natural_height_p);

Computes the preferred minimum and natural size of an actor, taking into account the actor's geometry management (either height-for-width or width-for-height).

The width and height used to compute the preferred height and preferred width are the actor's natural ones.

If you need to control the height for the preferred width, or the width for the preferred height, you should use clutter_actor_get_preferred_width() and clutter_actor_get_preferred_height(), and check the actor's preferred geometry management using the "request-mode" property.

Since 0.8

clutter_actor_get_preferred_width ()

void                clutter_actor_get_preferred_width   (ClutterActor *self,
                                                         gfloat for_height,
                                                         gfloat *min_width_p,
                                                         gfloat *natural_width_p);

Computes the requested minimum and natural widths for an actor, optionally depending on the specified height, or if they are already computed, returns the cached values.

An actor may not get its request - depending on the layout manager that's in effect.

A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Since 0.8

clutter_actor_get_preferred_height ()

void                clutter_actor_get_preferred_height  (ClutterActor *self,
                                                         gfloat for_width,
                                                         gfloat *min_height_p,
                                                         gfloat *natural_height_p);

Computes the requested minimum and natural heights for an actor, or if they are already computed, returns the cached values.

An actor may not get its request - depending on the layout manager that's in effect.

A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

Since 0.8

clutter_actor_set_fixed_position_set ()

void                clutter_actor_set_fixed_position_set
                                                        (ClutterActor *self,
                                                         gboolean is_set);

Sets whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

Since 0.8

clutter_actor_get_fixed_position_set ()

gboolean            clutter_actor_get_fixed_position_set
                                                        (ClutterActor *self);

Checks whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

Since 0.8

clutter_actor_set_request_mode ()

void                clutter_actor_set_request_mode      (ClutterActor *self,
                                                         ClutterRequestMode mode);

Sets the geometry request mode of self.

The mode determines the order for invoking clutter_actor_get_preferred_width() and clutter_actor_get_preferred_height()

Since 1.2

clutter_actor_get_request_mode ()

ClutterRequestMode  clutter_actor_get_request_mode      (ClutterActor *self);

Retrieves the geometry request mode of self

Since 1.2

clutter_actor_has_allocation ()

gboolean            clutter_actor_has_allocation        (ClutterActor *self);

Checks if the actor has an up-to-date allocation assigned to it. This means that the actor should have an allocation: it's visible and has a parent. It also means that there is no outstanding relayout request in progress for the actor or its children (There might be other outstanding layout requests in progress that will cause the actor to get a new allocation when the stage is laid out, however).

If this function returns FALSE, then the actor will normally be allocated before it is next drawn on the screen.

Since 1.4

enum ClutterActorAlign

typedef enum {
  CLUTTER_ACTOR_ALIGN_FILL,
  CLUTTER_ACTOR_ALIGN_START,
  CLUTTER_ACTOR_ALIGN_CENTER,
  CLUTTER_ACTOR_ALIGN_END
} ClutterActorAlign;

Controls how a ClutterActor should align itself inside the extra space assigned to it during the allocation.

Alignment only matters if the allocated space given to an actor is bigger than its natural size; for example, when the "x-expand" or the "y-expand" properties of ClutterActor are set to TRUE.