
@c %start of fragment

@node ClutterActor
@chapter ClutterActor
The basic element of the scene graph

@section Overview
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.

@section Actor transformations
Each actor can be transformed using methods like
@code{clutter-actor-set-scale} or @code{clutter-actor-set-rotation}. The
order in which the transformations are applied is decided by Clutter and
it is the following:

@enumerate 
@item
@item
@item
@item
@item
@item
@item
@end enumerate

translation by the origin of the @code{<"allocation">};

translation by the actor's @code{<"depth">};

scaling by the @code{<"scale-x">} and @code{<"scale-y">} factors;

rotation around the @code{<"rotation-z-angle">} and
@code{<"rotation-z-center">};

rotation around the @code{<"rotation-y-angle">} and
@code{<"rotation-y-center">};

rotation around the @code{<"rotation-x-angle">} and
@code{<"rotation-x-center">};

negative translation by the @code{<"anchor-x">} and @code{<"anchor-y">}
point.

@section Modifying an actor's geometry
Each actor has a bounding box, called @code{<"allocation">} which is
either set by its parent or explicitly through the
@code{clutter-actor-set-position} and @code{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 @code{clutter-actor-class.get-preferred-width} and the
@code{clutter-actor-class.get-preferred-height} virtual functions, or it
can be explicitly set by using @code{clutter-actor-set-width} and
@code{clutter-actor-set-height}.

An actor’s position can be set explicitly by using
@code{clutter-actor-set-x} and @code{clutter-actor-set-y}; the
coordinates are relative to the origin of the actor’s parent.

@section Managing actor children
Each actor can have multiple children, by calling
@code{clutter-actor-add-child} to add a new child actor, and
@code{clutter-actor-remove-child} to remove an existing child.
@code{<clutter-actor>} will hold a reference on each child actor, which
will be released when the child is removed from its parent, or destroyed
using @code{clutter-actor-destroy}.

@example 

 ClutterActor *actor = clutter_actor_new ();

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

 /&#x002A; set the background color of the actor &#x002A;/
 clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);

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

 /&#x002A; set the background color of the child &#x002A;/
 clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);

 /&#x002A; add the child to the actor &#x002A;/
 clutter_actor_add_child (actor, child);
  
@end example

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
@code{clutter-actor-get-first-child},
@code{clutter-actor-get-previous-sibling},
@code{clutter-actor-get-next-sibling}, and
@code{clutter-actor-get-last-child}. It is also possible to retrieve a
list of children by using @code{clutter-actor-get-children}, as well as
retrieving a specific child at a given index by using
@code{clutter-actor-get-child-at-index}.

If you need to track additions of children to a @code{<clutter-actor>},
use the @code{<"actor-added">} signal; similarly, to track removals of
children from a ClutterActor, use the @code{<"actor-removed">} signal.

@example 
@c (http://www.w3.org/2001/XInclude:include (@ (parse "text") (href "../../../../tests/interactive/test-actor.c")) (c (% (all "(http://www.w3.org/2001/XInclude:fallback \"FIXME: MISSING XINCLUDE CONTENT\")"))))
@end example

@c (title "Actors")
@section Painting an actor
There are three ways to paint an actor:

@itemize 
@item
@item
@item
@end itemize

set a delegate @code{<clutter-content>} as the value for the
@code{<"content">} property of the actor;

subclass @code{<clutter-actor>} and override the
@code{clutter-actor-class.paint-node} virtual function;

subclass @code{<clutter-actor>} and override the
@code{clutter-actor-class.paint} virtual function.

@c (title "Setting the Content property")
A @code{<clutter-content>} is a delegate object that takes over the
painting operation of one, or more actors. The @code{<clutter-content>}
painting will be performed on top of the @code{<"background-color">} of
the actor, and before calling the @code{clutter-actor-class.paint-node}
virtual function.

@example 

ClutterActor *actor = clutter_actor_new ();

/&#x002A; set the bounding box &#x002A;/
clutter_actor_set_position (actor, 50, 50);
clutter_actor_set_size (actor, 100, 100);

/&#x002A; set the content; the image_content variable is set elsewhere &#x002A;/
clutter_actor_set_content (actor, image_content);
    
@end example

@c (title "Overriding the paint_node virtual function")
The @code{clutter-actor-class.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 @code{<clutter-paint-node>} 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 @code{<"allocation">}.

@example 

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

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

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

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

  /&#x002A; add the node, and transfer ownership &#x002A;/
  clutter_paint_node_add_child (root, node);
  clutter_paint_node_unref (node);
@}
    
@end example

@c (title "Overriding the paint virtual function")
The @code{clutter-actor-class.paint} virtual function is invoked when
the @code{<"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
@code{clutter-actor-class.paint} virtual function, as well as connecting
to the @code{<"paint">} signal. These hooks into the paint sequence are
considered legacy, and will be removed when the Clutter API changes.

@section Handling events on an actor
A @code{<clutter-actor>} can receive and handle input device events, for
instance pointer events and key events, as long as its
@code{<"reactive">} property is set to @samp{@code{#t}}.

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 @code{<"captured-event">} signal on each ancestor
until it reaches the source; this phase is also called @emph{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
@code{<"event">} signal, along with other event signals if needed, is
emitted; this phase is also called @emph{the bubble phase}. At any point
of the signal emission, signal handlers can stop the propagation through
the scene graph by returning @samp{CLUTTER_EVENT_STOP}; otherwise, they
can continue the propagation by returning
@samp{CLUTTER_EVENT_PROPAGATE}.

@section 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.

@c (title "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.

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. In order to enable implicit
animations, it is necessary to change the easing state of an actor by
using @code{clutter-actor-save-easing-state}:

@example 

/&#x002A; assume that the actor is currently positioned at (100, 100) &#x002A;/
clutter_actor_save_easing_state (actor);
clutter_actor_set_position (actor, 500, 500);
clutter_actor_restore_easing_state (actor);
    
@end example

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:

@example 

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

/&#x002A; animate another actor's opacity &#x002A;/
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);
    
@end example

Implicit animations use a default duration of 250 milliseconds, and a
default easing mode of @samp{CLUTTER_EASE_OUT_CUBIC}, unless you call
@code{clutter-actor-set-easing-mode} and
@code{clutter-actor-set-easing-duration} after changing the easing state
of the actor.

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:

@example 

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

clutter_actor_save_easing_state (actor);
clutter_actor_set_x (actor, 100);
clutter_actor_restore_easing_state (actor);
    
@end example

the first call to @code{clutter-actor-set-x} will begin a transition of
the @code{<"x">} property to the value of 200; the second call to
@code{clutter-actor-set-x} will change the transition's final value to
100.

It is possible to retrieve the @code{<clutter-transition>} used by the
animatable properties by using @code{clutter-actor-get-transition} and
using the property name as the transition name.

@c (title "Explicit animations")
The explicit animation model supported by Clutter requires that you
create a @code{<clutter-transition>} object, and set the initial and
final values. The transition will not start unless you add it to the
@code{<clutter-actor>}.

@example 

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_interval (transition, clutter_interval_new (G_TYPE_UINT, 255, 0));

clutter_actor_add_transition (actor, "animate-opacity", transition);
    
@end example

The example above will animate the @code{<"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 should also be used when using custom
animatable properties for @code{<clutter-action>},
@code{<clutter-constraint>}, and @code{<clutter-effect>} 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:

@example 

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

transition = clutter_property_transition_new ("opacity");

/&#x002A; we want to animate the opacity between 0 and 255 &#x002A;/
internal = clutter_interval_new (G_TYPE_UINT, 0, 255);
clutter_transition_set_interval (transition, interval);

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

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

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

/&#x002A; add the transition to the desired actor; this will
 &#x002A; start the animation.
 &#x002A;/
clutter_actor_add_transition (actor, "opacityAnimation", transition);
    
@end example

@section Implementing an actor
Careful consideration should be given when deciding to implement a
@code{<clutter-actor>} sub-class. It is generally recommended to
implement a sub-class of @code{<clutter-actor>} 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
@code{<"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 @code{<"paint">} signal.

By overriding the @code{clutter-actor-class.get-preferred-width} and
@code{clutter-actor-class.get-preferred-height} virtual functions it is
possible to change or provide the preferred size of an actor; similarly,
by overriding the @code{clutter-actor-class.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
@code{clutter-actor-class.allocate} virtual function.

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

@section ClutterActor custom properties for @code{<clutter-script>}
@code{<clutter-actor>} 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:

@example 

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

where the @emph{axis} is the name of an enumeration value of type
@code{<clutter-rotate-axis>} and @emph{angle} is a floating point value
representing the rotation angle on the given axis, in degrees.

The @emph{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".

@code{<clutter-actor>} will also parse every positional and dimensional
property defined as a string through @code{clutter-units-from-string};
you should read the documentation for the @code{<clutter-units>} parser
format for the valid units and syntax.

@section Custom animatable properties
@code{<clutter-actor>} allows accessing properties of
@code{<clutter-action>}, @code{<clutter-effect>}, and
@code{<clutter-constraint>} instances associated to an actor instance
for animation purposes.

In order to access a specific @code{<clutter-action>} or a
@code{<clutter-constraint>} property it is necessary to set the
@code{<"name">} property on the given action or constraint.

The property can be accessed using the following syntax:

@example 

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

The initial @emph{@@} is mandatory.

The @emph{section} fragment can be one between "actions", "constraints"
and "effects".

The @emph{meta-name} fragment is the name of the action or constraint,
as specified by the @code{<"name">} property.

The @emph{property-name} fragment is the name of the action or
constraint property to be animated.

The example below animates a @code{<clutter-bind-constraint>} applied to
an actor using @code{clutter-actor-animate}. The @emph{rect} has a
binding constraint for the @emph{origin} actor, and in its initial state
is overlapping the actor to which is bound to.

@example 

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);
  
@end example

On button press, the rectangle "slides" from behind the actor to which
is bound to, using the @code{<"offset">} property to achieve the effect:

@example 

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

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

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

  /&#x002A; create a new transition for the given property &#x002A;/
  transition = clutter_property_transition_new (prop);

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

  /&#x002A; create the interval with the initial and final values &#x002A;/
  interval = clutter_interval_new (G_TYPE_FLOAT, 0, new_offset);
  clutter_transition_set_interval (transition, interval);

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

  /&#x002A; we handled the event &#x002A;/
  return CLUTTER_EVENT_STOP;
@}
  
@end example

@section Usage
@include defuns-clutter-actor.xml.texi

@c %end of fragment
