clutter-actor

clutter-actor — The basic element of the scene graph

Functions

Description

The ClutterActor class is the basic element of the scene graph in Clutter, and it encapsulates the position, size, and transformations of a node in the graph.

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:

  1. translation by the origin of the “allocation” property

  2. translation by the actor's “z-position” property

  3. translation by the actor's “pivot-point” property

  4. scaling by the “scale-x” and “scale-y” factors

  5. rotation around the “rotation-angle-x” and “rotation-center-x”

  6. rotation around the “rotation-angle-y” and “rotation-center-y”

  7. rotation around the “rotation-angle-z” and “rotation-center-z”

  8. negative translation by the “anchor-x” and “anchor-y” point.

  9. negative translation by the actor's “pivot-point”

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.

See basic-actor.c.

Painting an actor

There are three ways to paint an actor:

  • set a delegate ClutterContent as the value for the “content” property of the actor

  • subclass ClutterActor and override the ClutterActorClass.paint_node() virtual function

  • subclass ClutterActor and override the ClutterActorClass.paint() virtual function.

A ClutterContent is a delegate object that takes over the painting operations of one, or more actors. The ClutterContent painting will be performed on top of the “background-color” of the actor, and before calling the actor's own implementation of 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);

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
23
24
25
26
27
28
29
30
31
32
33
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);
}

The #ClutterActorClass.paint() virtual function is invoked when the
#ClutterActor::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.

It is strongly discouraged to override the #ClutterActorClass.paint()
virtual function, as well as connecting to the #ClutterActor::paint
signal. These hooks into the paint sequence are considered legacy, and
will be removed when the Clutter API changes.

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 is emitted, alongside eventual event-specific signals like “button-press-event” or “motion-event”; 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. You have two models at your disposal:

  • an implicit animation model

  • an explicit animation model

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.

By default, in the 1.0 API series, the transition happens with a duration of zero milliseconds, and the implicit animation is an opt in feature to retain backwards compatibility.

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
5
6
7
8
9
10
11
// assume that the actor is currently positioned at (100, 100)

// store the current easing state and reset the new easing state to
// its default values
clutter_actor_save_easing_state (actor);

// change the actor's position
clutter_actor_set_position (actor, 500, 500);

// restore the previously saved easing state
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.

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.

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
12
13
14
15
clutter_actor_save_easing_state (actor);

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

clutter_actor_restore_easing_state (actor);

clutter_actor_save_easing_state (another_actor);

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

clutter_actor_restore_easing_state (another_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 receive a notification of the completion of an implicit transition by using the “transition-stopped” signal, decorated with the name of the property. In case you want to know when all the currently in flight transitions are complete, use the “transitions-completed” signal instead.

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.

The explicit animation model supported by Clutter requires that you create a ClutterTransition object, and optionally 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
// 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 to start it
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
"rotation" : [ { "<axis>" : [ <angle>, [ <center-point> ] ] } ]

where:

  • axis is the name of an enumeration value of type ClutterRotateAxis

  • angle is a floating point value representing the rotation angle on the given axis in degrees

  • center-point is an optional array, 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"

    • 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, effect, or constraint, as specified by the “name” property of ClutterActorMeta

  • the property-name fragment is the name of the action, effect, or constraint property to be animated.

The example below animates a ClutterBindConstraint applied to an actor using an explicit transition. The rect actor has a binding constraint on 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
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;
}

Functions

clutter_actor_set_geometry ()

void
clutter_actor_set_geometry (ClutterActor *self,
                            const ClutterGeometry *geometry);

clutter_actor_set_geometry has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_position() and clutter_actor_set_size() instead.

Sets the actor's fixed position and forces its minimum and natural size, in pixels. This means the untransformed actor will have the given geometry. This is the same as calling clutter_actor_set_position() and clutter_actor_set_size().

Parameters

self

A ClutterActor

 

geometry

A ClutterGeometry

 

clutter_actor_get_geometry ()

void
clutter_actor_get_geometry (ClutterActor *self,
                            ClutterGeometry *geometry);

clutter_actor_get_geometry has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_get_position() and clutter_actor_get_size(), or clutter_actor_get_allocation_geometry() instead.

Gets the size and position of an actor relative to its parent actor. This is the same as calling clutter_actor_get_position() and clutter_actor_get_size(). It tries to "do what you mean" and get the requested size and position if the actor's allocation is invalid.

Parameters

self

A ClutterActor

 

geometry

A location to store actors ClutterGeometry.

[out caller-allocates]

clutter_actor_get_gid ()

guint32
clutter_actor_get_gid (ClutterActor *self);

clutter_actor_get_gid has been deprecated since version 1.8 and should not be used in newly-written code.

The id is not used any longer, and this function always returns 0.

Retrieves the unique id for self .

Parameters

self

A ClutterActor

 

Returns

Globally unique value for this object instance.

Since: 0.6


clutter_get_actor_by_gid ()

ClutterActor *
clutter_get_actor_by_gid (guint32 id_);

clutter_get_actor_by_gid has been deprecated since version 1.8 and should not be used in newly-written code.

The id is deprecated, and this function always returns NULL. Use the proper scene graph API in ClutterActor to find a child of the stage.

Retrieves the ClutterActor with id_ .

Parameters

id_

a ClutterActor unique id.

 

Returns

the actor with the passed id or NULL. The returned actor does not have its reference count increased.

[transfer none]

Since: 0.6


clutter_actor_reparent ()

void
clutter_actor_reparent (ClutterActor *self,
                        ClutterActor *new_parent);

clutter_actor_reparent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_remove_child() and clutter_actor_add_child() instead; remember to take a reference on the actor being removed before calling clutter_actor_remove_child() to avoid the reference count dropping to zero and the actor being destroyed.

Resets the parent actor of self .

This function is logically equivalent to calling clutter_actor_unparent() and clutter_actor_set_parent(), but more efficiently implemented, as it ensures the child is not finalized when unparented, and emits the “parent-set” signal only once.

In reality, calling this function is less useful than it sounds, as some application code may rely on changes in the intermediate state between removal and addition of the actor from its old parent to the new_parent . Thus, it is strongly encouraged to avoid using this function in application code.

Parameters

self

a ClutterActor

 

new_parent

the new ClutterActor parent

 

Since: 0.2


clutter_actor_set_parent ()

void
clutter_actor_set_parent (ClutterActor *self,
                          ClutterActor *parent);

clutter_actor_set_parent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_add_child() instead.

Sets the parent of self to parent .

This function will result in parent acquiring a reference on self , eventually by sinking its floating reference first. The reference will be released by clutter_actor_unparent().

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

Parameters

self

A ClutterActor

 

parent

A new ClutterActor parent

 

clutter_actor_unparent ()

void
clutter_actor_unparent (ClutterActor *self);

clutter_actor_unparent has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_remove_child() instead.

Removes the parent of self .

This will cause the parent of self to release the reference acquired when calling clutter_actor_set_parent(), so if you want to keep self you will have to acquire a reference of your own, through g_object_ref().

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_raise ()

void
clutter_actor_raise (ClutterActor *self,
                     ClutterActor *below);

clutter_actor_raise has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_above_sibling() instead.

Puts self above below .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface

This function calls clutter_container_raise_child() internally.

Parameters

self

A ClutterActor

 

below

A ClutterActor to raise above.

[allow-none]

clutter_actor_lower ()

void
clutter_actor_lower (ClutterActor *self,
                     ClutterActor *above);

clutter_actor_lower has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_below_sibling() instead.

Puts self below above .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface.

This function calls clutter_container_lower_child() internally.

Parameters

self

A ClutterActor

 

above

A ClutterActor to lower below.

[allow-none]

clutter_actor_raise_top ()

void
clutter_actor_raise_top (ClutterActor *self);

clutter_actor_raise_top has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_above_sibling() with a NULL sibling, instead.

Raises self to the top.

This function calls clutter_actor_raise() internally.

Parameters

self

A ClutterActor

 

clutter_actor_lower_bottom ()

void
clutter_actor_lower_bottom (ClutterActor *self);

clutter_actor_lower_bottom has been deprecated since version 1.10 and should not be used in newly-written code.

Use clutter_actor_set_child_below_sibling() with a NULL sibling, instead.

Lowers self to the bottom.

This function calls clutter_actor_lower() internally.

Parameters

self

A ClutterActor

 

clutter_actor_push_internal ()

void
clutter_actor_push_internal (ClutterActor *self);

clutter_actor_push_internal has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API, and ClutterActor implements the ClutterContainer interface, so this function is only useful for legacy containers overriding the default implementation.

Should be used by actors implementing the ClutterContainer and with internal children added through clutter_actor_set_parent(), 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
static void
my_actor_init (MyActor *self)
{
  self->priv = my_actor_get_instance_private (self);

  clutter_actor_push_internal (CLUTTER_ACTOR (self));

  // calling clutter_actor_set_parent() now will result in
  // the internal flag being set on a child of MyActor

  // internal child - a background texture
  self->priv->background_tex = clutter_texture_new ();
  clutter_actor_set_parent (self->priv->background_tex,
                            CLUTTER_ACTOR (self));

  // internal child - a label
  self->priv->label = clutter_text_new ();
  clutter_actor_set_parent (self->priv->label,
                            CLUTTER_ACTOR (self));

  clutter_actor_pop_internal (CLUTTER_ACTOR (self));

  // calling clutter_actor_set_parent() now will not result in
  // the internal flag being set on a child of MyActor
}

This function will be used by Clutter to toggle an "internal child" flag whenever clutter_actor_set_parent() is called; internal children are handled differently by Clutter, specifically when destroying their parent.

Call clutter_actor_pop_internal() when you finished adding internal children.

Nested calls to clutter_actor_push_internal() are allowed, but each one must by followed by a clutter_actor_pop_internal() call.

Parameters

self

a ClutterActor

 

Since: 1.2


clutter_actor_pop_internal ()

void
clutter_actor_pop_internal (ClutterActor *self);

clutter_actor_pop_internal has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API. This function is only useful for legacy containers overriding the default implementation of the ClutterContainer interface.

Disables the effects of clutter_actor_push_internal().

Parameters

self

a ClutterActor

 

Since: 1.2


clutter_actor_show_all ()

void
clutter_actor_show_all (ClutterActor *self);

clutter_actor_show_all has been deprecated since version 1.10 and should not be used in newly-written code.

Actors are visible by default

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

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_hide_all ()

void
clutter_actor_hide_all (ClutterActor *self);

clutter_actor_hide_all has been deprecated since version 1.10 and should not be used in newly-written code.

Using clutter_actor_hide() on the actor will prevent its children from being painted as well.

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

Parameters

self

a ClutterActor

 

Since: 0.2


clutter_actor_set_depth ()

void
clutter_actor_set_depth (ClutterActor *self,
                         gfloat depth);

clutter_actor_set_depth has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_z_position() instead.

Sets the Z coordinate of self to depth .

The unit used by depth is dependant on the perspective setup. See also clutter_stage_set_perspective().

Parameters

self

a ClutterActor

 

depth

Z co-ord

 

clutter_actor_get_depth ()

gfloat
clutter_actor_get_depth (ClutterActor *self);

clutter_actor_get_depth has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_z_position() instead.

Retrieves the depth of self .

Parameters

self

a ClutterActor

 

Returns

the depth of the actor


clutter_actor_set_rotation ()

void
clutter_actor_set_rotation (ClutterActor *self,
                            ClutterRotateAxis axis,
                            gdouble angle,
                            gfloat x,
                            gfloat y,
                            gfloat z);

clutter_actor_set_rotation has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_rotation_angle() and clutter_actor_set_pivot_point() instead.

Sets the rotation angle of self around the given axis.

The rotation center coordinates used depend on the value of axis :

  • CLUTTER_X_AXIS requires y and z

  • CLUTTER_Y_AXIS requires x and z

  • CLUTTER_Z_AXIS requires x and y

The rotation coordinates are relative to the anchor point of the actor, set using clutter_actor_set_anchor_point(). If no anchor point is set, the upper left corner is assumed as the origin.

Parameters

self

a ClutterActor

 

axis

the axis of rotation

 

angle

the angle of rotation

 

x

X coordinate of the rotation center

 

y

Y coordinate of the rotation center

 

z

Z coordinate of the rotation center

 

Since: 0.8


clutter_actor_set_z_rotation_from_gravity ()

void
clutter_actor_set_z_rotation_from_gravity
                               (ClutterActor *self,
                                gdouble angle,
                                ClutterGravity gravity);

clutter_actor_set_z_rotation_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_rotation_angle() and clutter_actor_set_pivot_point() instead.

Sets the rotation angle of self around the Z axis using the center point specified as a compass point. For example to rotate such that the center of the actor remains static you can use CLUTTER_GRAVITY_CENTER. If the actor changes size the center point will move accordingly.

Parameters

self

a ClutterActor

 

angle

the angle of rotation

 

gravity

the center point of the rotation

 

Since: 1.0


clutter_actor_get_rotation ()

gdouble
clutter_actor_get_rotation (ClutterActor *self,
                            ClutterRotateAxis axis,
                            gfloat *x,
                            gfloat *y,
                            gfloat *z);

clutter_actor_get_rotation has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_rotation_angle() and clutter_actor_get_pivot_point() instead.

Retrieves the angle and center of rotation on the given axis, set using clutter_actor_set_rotation().

Parameters

self

a ClutterActor

 

axis

the axis of rotation

 

x

return value for the X coordinate of the center of rotation.

[out]

y

return value for the Y coordinate of the center of rotation.

[out]

z

return value for the Z coordinate of the center of rotation.

[out]

Returns

the angle of rotation

Since: 0.8


clutter_actor_get_z_rotation_gravity ()

ClutterGravity
clutter_actor_get_z_rotation_gravity (ClutterActor *self);

clutter_actor_get_z_rotation_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use the “pivot-point” instead of a ClutterGravity

Retrieves the center for the rotation around the Z axis as a compass direction. If the center was specified in pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

A ClutterActor

 

Returns

the Z rotation center

Since: 1.0


clutter_actor_set_scale_full ()

void
clutter_actor_set_scale_full (ClutterActor *self,
                              gdouble scale_x,
                              gdouble scale_y,
                              gfloat center_x,
                              gfloat center_y);

clutter_actor_set_scale_full has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_pivot_point() to control the scale center

Scales an actor with the given factors around the given center point. The center point is specified in pixels relative to the anchor point (usually the top left corner of the actor).

The “scale-x” and “scale-y” properties are animatable.

Parameters

self

A ClutterActor

 

scale_x

double factor to scale actor by horizontally.

 

scale_y

double factor to scale actor by vertically.

 

center_x

X coordinate of the center of the scaling

 

center_y

Y coordinate of the center of the scaling

 

Since: 1.0


clutter_actor_set_scale_with_gravity ()

void
clutter_actor_set_scale_with_gravity (ClutterActor *self,
                                      gdouble scale_x,
                                      gdouble scale_y,
                                      ClutterGravity gravity);

clutter_actor_set_scale_with_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_set_pivot_point() to set the scale center using normalized coordinates instead.

Scales an actor with the given factors around the given center point. The center point is specified as one of the compass directions in ClutterGravity. For example, setting it to north will cause the top of the actor to remain unchanged and the rest of the actor to expand left, right and downwards.

The “scale-x” and “scale-y” properties are animatable.

Parameters

self

A ClutterActor

 

scale_x

double factor to scale actor by horizontally.

 

scale_y

double factor to scale actor by vertically.

 

gravity

the location of the scale center expressed as a compass direction.

 

Since: 1.0


clutter_actor_get_scale_center ()

void
clutter_actor_get_scale_center (ClutterActor *self,
                                gfloat *center_x,
                                gfloat *center_y);

clutter_actor_get_scale_center has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_pivot_point() instead.

Retrieves the scale center coordinate in pixels relative to the top left corner of the actor. If the scale center was specified using a ClutterGravity this will calculate the pixel offset using the current size of the actor.

Parameters

self

A ClutterActor

 

center_x

Location to store the X position of the scale center, or NULL.

[out][allow-none]

center_y

Location to store the Y position of the scale center, or NULL.

[out][allow-none]

Since: 1.0


clutter_actor_get_scale_gravity ()

ClutterGravity
clutter_actor_get_scale_gravity (ClutterActor *self);

clutter_actor_get_scale_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_pivot_point() instead.

Retrieves the scale center as a compass direction. If the scale center was specified in pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

A ClutterActor

 

Returns

the scale gravity

Since: 1.0


clutter_actor_set_anchor_point ()

void
clutter_actor_set_anchor_point (ClutterActor *self,
                                gfloat anchor_x,
                                gfloat anchor_y);

clutter_actor_set_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

Sets an anchor point for self . The anchor point is a point in the coordinate space of an actor to which the actor position within its parent is relative; the default is (0, 0), i.e. the top-left corner of the actor.

Parameters

self

a ClutterActor

 

anchor_x

X coordinate of the anchor point

 

anchor_y

Y coordinate of the anchor point

 

Since: 0.6


clutter_actor_move_anchor_point ()

void
clutter_actor_move_anchor_point (ClutterActor *self,
                                 gfloat anchor_x,
                                 gfloat anchor_y);

clutter_actor_move_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead.

Sets an anchor point for the actor, and adjusts the actor postion so that the relative position of the actor toward its parent remains the same.

Parameters

self

a ClutterActor

 

anchor_x

X coordinate of the anchor point

 

anchor_y

Y coordinate of the anchor point

 

Since: 0.6


clutter_actor_get_anchor_point ()

void
clutter_actor_get_anchor_point (ClutterActor *self,
                                gfloat *anchor_x,
                                gfloat *anchor_y);

clutter_actor_get_anchor_point has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Gets the current anchor point of the actor in pixels.

Parameters

self

a ClutterActor

 

anchor_x

return location for the X coordinate of the anchor point.

[out]

anchor_y

return location for the Y coordinate of the anchor point.

[out]

Since: 0.6


clutter_actor_get_anchor_point_gravity ()

ClutterGravity
clutter_actor_get_anchor_point_gravity
                               (ClutterActor *self);

clutter_actor_get_anchor_point_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

Retrieves the anchor position expressed as a ClutterGravity. If the anchor point was specified using pixels or units this will return CLUTTER_GRAVITY_NONE.

Parameters

self

a ClutterActor

 

Returns

the ClutterGravity used by the anchor point

Since: 1.0


clutter_actor_set_anchor_point_from_gravity ()

void
clutter_actor_set_anchor_point_from_gravity
                               (ClutterActor *self,
                                ClutterGravity gravity);

clutter_actor_set_anchor_point_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead. E.g. For CLUTTER_GRAVITY_CENTER set pivot_point to (0.5,0.5) and the translation to (width/2,height/2).

Sets an anchor point on the actor, based on the given gravity (this is a convenience function wrapping clutter_actor_set_anchor_point()).

Since version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, the anchor point will move to the bottom right.

Parameters

self

a ClutterActor

 

gravity

ClutterGravity.

 

Since: 0.6


clutter_actor_move_anchor_point_from_gravity ()

void
clutter_actor_move_anchor_point_from_gravity
                               (ClutterActor *self,
                                ClutterGravity gravity);

clutter_actor_move_anchor_point_from_gravity has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and clutter_actor_set_translation() instead.

Sets an anchor point on the actor based on the given gravity, adjusting the actor postion so that its relative position within its parent remains unchanged.

Since version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, the anchor point will move to the bottom right.

Parameters

self

a ClutterActor

 

gravity

ClutterGravity.

 

Since: 0.6


clutter_actor_get_transformation_matrix ()

void
clutter_actor_get_transformation_matrix
                               (ClutterActor *self,
                                ClutterMatrix *matrix);

clutter_actor_get_transformation_matrix has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_transform() instead

Retrieves the transformations applied to self relative to its parent.

Parameters

self

a ClutterActor

 

matrix

the return location for a ClutterMatrix.

[out caller-allocates]

Since: 1.0


clutter_actor_get_allocation_geometry ()

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

clutter_actor_get_allocation_geometry has been deprecated since version 1.12 and should not be used in newly-written code.

Use clutter_actor_get_allocation_box() instead.

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.

Parameters

self

A ClutterActor

 

geom

allocation geometry in pixels.

[out]

Since: 0.8