View on
MetaCPAN is shutting down
For details read Perl NOC. After June 25th this page will redirect to
Emmanuele Bassi > Clutter-1.002 > xs/ClutterActor.xs


Annotate this POD


New  4
Open  2
View/Report Bugs

Clutter::Actor is the base class for actors. An actor in Clutter is a single entity on the Clutter::Stage; it has style and positional attributes, which can be directly accessed and modified, or can be controlled using a subclass of Clutter::Behaviour.


The OpenGL modelview matrix for the actor is constructed from the actor settings by the following order of operations:

1. Translation by actor (x, y) coordinates
2. Scaling by scale_x and scale_y
3. Negative translation by the anchor point (x, y) coordinates
4. Rotation around z axis
5. Rotation around y axis
6. Rotation around x axis
7. Translation by actor depth (z coordinate)
8. Clip stencil is applied

Note: clipping not an operation on the matrix as such, but done as part of the transformation set up


Actors emit events only if set reactive
The stage is always reactive by default
Events are handled by connecting signal handlers to the event signals

Event signals usually have the -event postfix.

Event handlers must return TRUE if they handled the event

When an event handler returns TRUE it will interrupt the event emission chain. Event handlers must return FALSE if the emission should continue instead.

If an actor is grabbing events it will be the only receiver

Note: Key focus can be seen a "soft grab"; an actor with key focus will receive key events even if it's not grabbing them.

Keyboard events are emitted if an actor has key focus

Note: By default, the stage has key focus.

Motion events (motion, enter, leave) are not emitted if not enabled

Note: Motion events are enabled by default. The motion event is only emitted by the Clutter::Stage if the motion events delivery is disabled.

The event emission has two phases: capture and bubble

An emitted event starts in the capture phase, beginning at the stage and traversing every child actor until the event source actor is reached. The emission then enters the bubble phase, traversing back up the chain via parents until it reaches the stage. Any event handler can abort this chain by returning TRUE (meaning "event handled")

Pointer events will 'pass through' non reactive actors

E.g., if two actors are overlaying, the non reactive actor will be ignored.


Clutter intentionally provides only few default actors. You are encouraged to derive a new actor from any of these, or directly from the Clutter::Actor class itself.

The new actor must be a GObject, so you must follow the normal procedure for creating a new Glib::Obect (i.e., either Glib::Object::Subclass or Glib::Type::register_object).

If you want to control the size allocation and request for the newly created actor class, you should provide a new implementation of the following methods:

ALLOCATE ($actor, $box, $origin_changed)
o $actor (Clutter::Actor)
o $box (Clutter::ActorBox)
o $flags (Clutter::AllocationFlags)

This is called each time the user requests the actor to update its coordinates and size. The box contains the upper left and lower right coordinates of the box surrounding the actor. Every class overriding the ALLOCATE method must chain up to the parent's class method, using the usual SUPER mechanism provided by Perl, for instance:

  $actor->SUPER::ALLOCATE($box, $flags);

See perlobj.

(minimum_width, natural_width) = GET_PREFERRED_WIDTH ($actor, $for_height)
o $actor (Clutter::Actor)
o $for_height (pixels)

This is called each time the actor is queried for its preferred width.

The returned array must contains the minimum width and the natural width of the actor for the given height passed in for_height.

(minimum_height, natural_height) = GET_PREFERRED_HEIGHT ($actor, $for_width)
o $actor (Clutter::Actor)
o $for_width (pixels)

This is called each time the actor is queried for its preferred height.

The returned array must contains the minimum height and the natural height of the actor for the given width passed in for_width.

Other overridable methods when deriving a Clutter::Actor are:

PAINT ($actor)
o $actor (Clutter::Actor)

This is called each time the actor needs to be painted. You can call native GL calls using Perl bindings for the OpenGL API. If you are implementing a containter actor, or if you are operating transformations on the actor while painting, you should push the GL matrix first with glPushMatrix , paint and the pop it back with glPopMatrix ; this will allow your children to follow the same transformations.

SHOW_ALL ($actor)
HIDE_ALL ($actor)
o $actor (Clutter::Actor)

By default, calling show_all and hide_all on a Clutter::Group will not recurse though its children. A recursive behaviour can be implemented by overriding this method. This method is also useful for composite actors, where some non-exposed children should be visible only if certain conditions arise.

REALIZE ($actor)
UNREALIZE ($actor)
o $actor (Clutter::Actor)

Actors might have to allocate resources before being shown for the first time, for instance GL-specific data. The REALIZE virtual function will be called by the show method. Inside this function you should set the realized flag, or chain up to the parent class REALIZE method.

The UNREALIZE virtual function will be called when destroying the actor, and allows the release of the resources allocated inside REALIZE .

MAP ($actor)
UNMAP ($actor)
o $actor (Clutter::Actor)

Composite actors should map and unmap their children inside these two virtual functions, respectively.

Every class overriding the MAP and UNMAP virtual functions must chain up to the parent's implementation.

PICK ($actor, $pick_color)
o $actor (Clutter::Actor)
o $pick_color (Clutter::Color)

The PICK virtual function will be called when drawing the scene with a mask of the actors in order to detect actor at a given pair of coordinates relative to the stage (see the get_actor_at_pos method of Clutter::Stage).

The actor should paint its bounding box with the passed pick_color, and its eventual children should be painted as well by invoking the paint method. The default implementation of the PICK method is the equivalent of:

  sub PICK {
      my ($self, $pick_color) = @_;

      return unless $self->should_pick_paint();

      my $allocation = $self->get_allocation_box();

      Clutter::Cogl->set_source_color([ $pick_color->values() ]);
      Clutter::Cogl->rectangle(0, 0, $box->width(), $box->height());

Which will render the actor as a rectangle the size of its bounding box (Note: there is no need to override the PICK virtual function in this case).

An actor with internal children, or implementing the Clutter::Container interface should, instead, use:

  sub PICK {
      my ($self, $pick_color) = @_;

      # chain up to allow picking the container
      $self->SUPER::PICK ($pick_color);

      foreach my $child in ($self->get_children()) {
          $child->paint(); # this will result in the PICK method of
                           # the child being called
APPLY_TRANSFORM ($actor, $matrix)
o $actor (Clutter::Actor)
o $matrix (Clutter::Cogl::Matrix)

The APPLY_TRANSFORM virtual function allows applying additional transformations on top of the ones handled by the Clutter::Actor API, like Clutter::Actor::set_rotation() or Clutter::Actor::set_scale(). These additional transformations will be used when paiting the actor and when transforming coordinates.

The actor receives a Clutter::Cogl::Matrix that can be transformed using the relative API.

When overriding the APPLY_TRANSFORM an actor must always chain up to the parent class implementation.

For instance, this implementation of the virtual function will apply an implicit traslation of the actor; the offsets can be controlled by objects like Gtk2::Adjustment:

      my ($self, $matrix) = @_;

      $self->SUPER::APPLY_TRANSFORM ($matrix);

      $matrix->translate($self->{x_offset} * -1,
                         $self->{y_offset} * -1,

The rotation center coordinates depend on the value of axis:

'x-axis' requires y and z
'y-axis' requires x and z
'z-axis' requires x and y

For example, this:

        'linear', 250,
        width  => 100,
        height => 100,

will make width and height properties of the Clutter::Actor rectangle grow linearly between the current value and 100 pixels, in 250 milliseconds.

The animation mode is a logical id, either from the Clutter::AnimationMode enumeration of from Clutter::Alpha::register_func().

All the properties specified will be animated between the current value and the final value. If a property should be set at the beginning of the animation but not updated during the animation, it should be prefixed by the "fixed::" string, for instance:

    $actor->animate (
        'ease-in-sine', 100,
        rotation_angle_z => 360,
        "fixed::rotation-center-z" => Clutter::Vertex->new(100, 100, 0),

Will animate the rotation_angle_z property between the current value and 360 degrees, and set the rotation_center_z property to the fixed value of the passed Clutter::Vertex.

This function will implicitly create a Clutter::Animation object which will be assigned to the actor and will be returned to the developer to control the animation or to know when the animation has been completed.

Calling this function on an actor that is already being animated will cause the current animation to change with the new final values, the new easing mode and the new duration - that is, this code:

    $actor->animate ('linear', 250, width => 100, height => 100);
    $actor->animate ('ease-in-cubic', 500,
        x => 100,
        y => 100,
        width => 200,

is the equivalent of:

    $actor->animate('ease-in-cubic', 500,
        x => 100,
        y => 100,
        width => 200,
        height => 100,

Note: Unless the animation is looping, the Clutter::Animation created by Clutter::Actor::animate() will become invalid as soon as it is complete.

Since the created Clutter::Animation instance attached to actor is guaranteed to be valid throughout the Clutter::Animation::completed signal emission chain, you will not be able to create a new animation using Clutter::Actor::animate() on the same actor from within the Clutter::Animation::completed signal handler unless you use Glib::Object::signal_connect_after() to connect the callback function, for instance:

    my $animation = $actor->animate ('ease-in-cubic', 250,
        x => 100,
        y => 100,

    $animation->signal_connect_after("completed" => sub {
        $actor->animate('ease-in-cubic', 250,
            x => 500,
            y => 500,
syntax highlighting: