Emmanuele Bassi > Clutter-0.820 > xs/ClutterActor.xs


Annotate this POD


New  3
Open  2
View/Report Bugs
Source   Latest Release: Clutter-1.002

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 pointer 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 $origin_changed (boolean)

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, $origin_changed);

See perlobj.

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

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 (Clutter::Unit)

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 .

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) = @_;

            $self->get_x() + $self->get_width(),
            $self->get_y() + $self->get_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

Retrieves the coordinates of the allocation (top left corner, bottom right corner), in pixels.

Unit-based version of Clutter::Actor::get_position().

Unit-based version of Clutter::Actor::get_size().

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
syntax highlighting: