HIERARCHY

  Glib::Object
  +----Glib::InitiallyUnowned
       +----Clutter::Actor

INTERFACES

  Glib::Object::_Unregistered::ClutterScriptable

METHODS

$actor->allocate ($box, $flags)

• $box (Clutter::ActorBox)
• $flags (Clutter::AllocationFlags)

$actor->allocate_available_size ($x, $y, $available_width, $available_height, $flags)

• $x (double)
• $y (double)
• $available_width (double)
• $available_height (double)
• $flags (Clutter::AllocationFlags)

$actor->allocate_preferred_size ($flags)

• $flags (Clutter::AllocationFlags)

actorbox = $actor->get_allocation_box

Retrieves the allocation box as a Clutter::ActorBox

geometry = $actor->get_allocation_geometry

vertices = $actor->get_allocation_vertices

• $ancestor (Clutter::Actor or undef)

Returns an array of four Clutter::Vertex objects containing the transformed coordinates of the vertices of actor

$actor->set_anchor_point_from_gravity ($gravity)

• $gravity (Clutter::Gravity)

(x, y) = $actor->get_anchor_point

gravity = $actor->get_anchor_point_gravity

$actor->set_anchor_point ($x, $y)

• $x (double)
• $y (double)

Sets the anchor point of the actor. The anchor is a point in the coordinates space of the actor (with origin set at the top left corner of the bounding box). The anchor point is taken into account when applying any transformation to an actor.

animation = $actor->animate ($mode, $duration, $name, $value, ...)

• $mode (scalar)
• $duration (integer)
• ... (list) list of property name, value pairs

Animates the given list of properties of actor between the current value for each property and a new final value. The animation has a definite duration and a speed given by the mode.

For example, this:

    $rectangle->animate(
        '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,
        );
    });

animation = $actor->animate_with_alpha ($alpha, $name, $value, ...)

• $alpha (Clutter::Alpha)
• ... (list) list of property name, value pairs

animation = $actor->animate_with_timeline ($mode, $timeline, $name, $value, ...)

• $mode (scalar)
• $timeline (Clutter::Timeline)
• ... (list) list of property name, value pairs

vertex = $actor->apply_relative_transform_to_point ($ancestor, $vertex)

• $ancestor (Clutter::Actor or undef)
• $vertex (Clutter::Vertex)

vertex = $actor->apply_transform_to_point ($vertex)

• $vertex (Clutter::Vertex)

(x_offset, y_offset, width, height) = $actor->get_clipu

$actor->set_clip ($x_offset, $y_offset, $width, $height)

• $x_offset (double)
• $y_offset (double)
• $width (double)
• $height (double)

context = $actor->create_pango_context

layout = $actor->create_pango_layout ($text)

• $text (string or undef)

double = $actor->get_depth

$actor->set_depth ($depth)

• $depth (double)

$actor->destroy

boolean = $actor->get_fixed_position_set

$actor->set_fixed_position_set ($is_set)

• $is_set (boolean)

actorflags = $actor->flags

Retrieves the flags set on the actor

actorflags = $actor->get_flags

$actor->set_flags ($flags)

• $flags (Clutter::ActorFlags)

Sets the given flags on the actor

geometry = $actor->get_geometry

A simple wrapper around Clutter::Actor::set_position() and Clutter::Actor::set_size()

$actor->set_geometry ($geom)

• $geom (Clutter::Geometry)

A simple wrapper around Clutter::Actor::get_position() and Clutter::Actor::get_size()

unsigned = $actor->get_gid

boolean = $actor->has_clip

double = $actor->get_height

$actor->set_height ($height)

• $height (double)

$actor->hide

$actor->hide_all

boolean = $actor->is_in_clone_paint

boolean = $actor->is_rotated

boolean = $actor->is_scaled

$actor->lower ($above=undef)

• $above (Clutter::Actor or undef)

$actor->lower_bottom

$actor->map

$actor->mapped ($boolean)

boolean = $actor->mapped

Checks if the actor is mapped

$actor->move_anchor_point_from_gravity ($gravity)

• $gravity (Clutter::Gravity)

$actor->move_by ($dx, $dy)

• $dx (double)
• $dy (double)

string = $actor->get_name

$actor->set_name ($id)

• $id (string)

unsigned = $actor->get_opacity

$actor->set_opacity ($opacity)

• $opacity (unsigned)

Sets the actor's opacity, with 0 being fully transparent and 255 being fully opaque

$actor->paint

unsigned = $actor->get_paint_opacity

boolean = $actor->get_paint_visibility

context = $actor->get_pango_context

actor or undef = $actor->get_parent

$actor->set_parent ($parent)

• $parent (Clutter::Actor)

(x, y) = $actor->get_position

$actor->set_position ($x, $y)

• $x (double)
• $y (double)

(min_height, natural_height) = $actor->get_preferred_height ($for_width)

• $for_width (double)

(min_width, min_height, natural_width, natural_height) = $actor->get_preferred_size

(min_width, natural_width) = $actor->get_preferred_width ($for_height)

• $for_height (double)

$actor->queue_redraw

$actor->queue_relayout

$actor->raise ($below=undef)

• $below (Clutter::Actor or undef)

$actor->raise_top

$actor->reactive ($boolean)

boolean = $actor->get_reactive

$actor->set_reactive ($reactive)

• $reactive (boolean)

Sets whether the actor should react to events

$actor->realize

$actor->realized ($boolean)

boolean = $actor->realized

Checks if the actor is realized

$actor->remove_clip

$actor->reparent ($new_parent)

• $new_parent (Clutter::Actor)

angle = $actor->get_rotation ($axis)

(angle, x, y, z) = $actor->get_rotation ($axis)

• $axis (Clutter::RotateAxis)

Retrieves the angle and center of rotation on the given axis.

$actor->set_rotation ($axis, $angle, $x=0, $y=0, $z=0)

• $axis (Clutter::RotateAxis)
• $angle (double)
• $x (integer)
• $y (integer)
• $z (integer)

Sets the rotation angle of actor around the given axis.

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

(center_x, center_y) = $actor->get_scale_center

$actor->set_scale_full ($scale_x, $scale_y, $center_x, $center_y)

• $scale_x (double)
• $scale_y (double)
• $center_x (double)
• $center_y (double)

(scale_x, scale_y) = $actor->get_scale

$actor->set_scale ($scale_x, $scale_y)

• $scale_x (double)
• $scale_y (double)

$actor->set_scale_with_gravity ($scale_x, $scale_y, $gravity)

• $scale_x (double)
• $scale_y (double)
• $gravity (Clutter::Gravity)

shader or undef = $actor->get_shader

$actor->set_shader_param ($param, $value)

• $param (string)
• $value (scalar)

boolean = $actor->set_shader ($shader)

• $shader (Clutter::Shader or undef)

boolean = $actor->should_pick_paint

$actor->show

$actor->show_all

(width, height) = $actor->get_size

$actor->set_size ($width, $height)

• $width (double)
• $height (double)

actor or undef = $actor->get_stage

(actor_x, actor_y) = $actor->transform_stage_point ($x, $y)

• $x (double)
• $y (double)

matrix = $actor->get_transformation_matrix

(x, y) = $actor->get_transformed_position

Gets the absolute position of an actor in pixels relative to the stage

(width, height) = $actor->get_transformed_size

Gets the absolute size of an actor in pixels taking into account any transformation

$actor->unmap

$actor->unparent

$actor->unrealize

$actor->unset_flags ($flags)

• $flags (Clutter::ActorFlags)

Unsets the given flags on the actor

$actor->visible ($boolean)

double = $actor->get_width

$actor->set_width ($width)

• $width (double)

double = $actor->get_x

$actor->set_x ($x)

• $x (double)

double = $actor->get_y

$actor->set_y ($y)

• $y (double)

$actor->set_z_rotation_from_gravity ($angle, $gravity)

• $angle (double)
• $gravity (Clutter::Gravity)

gravity = $actor->get_z_rotation_gravity

PROPERTIES

'allocation' (Clutter::ActorBox : readable / private)

The actor's allocation

'anchor-gravity' (Clutter::Gravity : readable / writable / private)

The anchor point as a ClutterGravity

'anchor-x' (Glib::Float : readable / writable / private)

X coordinate of the anchor point

'anchor-y' (Glib::Float : readable / writable / private)

Y coordinate of the anchor point

'clip' (Clutter::Geometry : readable / writable / private)

The clip region for the actor

'clip-to-allocation' (boolean : readable / writable / private)

Sets the clip region to track the actor's allocation

'depth' (Glib::Float : readable / writable / private)

Position on the Z axis

'fixed-position-set' (boolean : readable / writable / private)

Whether to use fixed positioning for the actor

'fixed-x' (Glib::Float : readable / writable / private)

Forced X position of the actor

'fixed-y' (Glib::Float : readable / writable / private)

Forced Y position of the actor

'has-clip' (boolean : readable / private)

Whether the actor has a clip set

'height' (Glib::Float : readable / writable / private)

Height of the actor

'mapped' (boolean : readable / private)

Whether the actor will be painted

'min-height' (Glib::Float : readable / writable / private)

Forced minimum height request for the actor

'min-height-set' (boolean : readable / writable / private)

Whether to use the min-height property

'min-width' (Glib::Float : readable / writable / private)

Forced minimum width request for the actor

'min-width-set' (boolean : readable / writable / private)

Whether to use the min-width property

'name' (string : readable / writable / private)

Name of the actor

'natural-height' (Glib::Float : readable / writable / private)

Forced natural height request for the actor

'natural-height-set' (boolean : readable / writable / private)

Whether to use the natural-height property

'natural-width' (Glib::Float : readable / writable / private)

Forced natural width request for the actor

'natural-width-set' (boolean : readable / writable / private)

Whether to use the natural-width property

'opacity' (Glib::UChar : readable / writable / private)

Opacity of actor

'reactive' (boolean : readable / writable / private)

Whether the actor is reactive to events

'realized' (boolean : readable / private)

Whether the actor has been realized

'request-mode' (ClutterRequestMode : readable / writable / private)

The actor's request mode

'rotation-angle-x' (double : readable / writable / private)

The rotation angle on the X axis

'rotation-angle-y' (double : readable / writable / private)

The rotation angle on the Y axis

'rotation-angle-z' (double : readable / writable / private)

The rotation angle on the Z axis

'rotation-center-x' (Clutter::Vertex : readable / writable / private)

The rotation center on the X axis

'rotation-center-y' (Clutter::Vertex : readable / writable / private)

The rotation center on the Y axis

'rotation-center-z' (Clutter::Vertex : readable / writable / private)

The rotation center on the Z axis

'rotation-center-z-gravity' (Clutter::Gravity : readable / writable / private)

Center point for rotation around the Z axis

'scale-center-x' (Glib::Float : readable / writable / private)

Horizontal scale center

'scale-center-y' (Glib::Float : readable / writable / private)

Vertical scale center

'scale-gravity' (Clutter::Gravity : readable / writable / private)

The center of scaling

'scale-x' (double : readable / writable / private)

Scale factor on the X axis

'scale-y' (double : readable / writable / private)

Scale factor on the Y axis

'show-on-set-parent' (boolean : readable / writable / private)

Whether the actor is shown when parented

'visible' (boolean : readable / writable / private)

Whether the actor is visible or not

'width' (Glib::Float : readable / writable / private)

Width of the actor

'x' (Glib::Float : readable / writable / private)

X coordinate of the actor

'y' (Glib::Float : readable / writable / private)

Y coordinate of the actor

ENUMS AND FLAGS

flags Clutter::ActorFlags

• 'mapped' / 'CLUTTER_ACTOR_MAPPED'
• 'realized' / 'CLUTTER_ACTOR_REALIZED'
• 'reactive' / 'CLUTTER_ACTOR_REACTIVE'
• 'visible' / 'CLUTTER_ACTOR_VISIBLE'

flags Clutter::AllocationFlags

• 'allocation-none' / 'CLUTTER_ALLOCATION_NONE'
• 'absolute-origin-changed' / 'CLUTTER_ABSOLUTE_ORIGIN_CHANGED'

enum Clutter::Gravity

• 'none' / 'CLUTTER_GRAVITY_NONE'
• 'north' / 'CLUTTER_GRAVITY_NORTH'
• 'north-east' / 'CLUTTER_GRAVITY_NORTH_EAST'
• 'east' / 'CLUTTER_GRAVITY_EAST'
• 'south-east' / 'CLUTTER_GRAVITY_SOUTH_EAST'
• 'south' / 'CLUTTER_GRAVITY_SOUTH'
• 'south-west' / 'CLUTTER_GRAVITY_SOUTH_WEST'
• 'west' / 'CLUTTER_GRAVITY_WEST'
• 'north-west' / 'CLUTTER_GRAVITY_NORTH_WEST'
• 'center' / 'CLUTTER_GRAVITY_CENTER'

enum Clutter::RotateAxis

• 'x-axis' / 'CLUTTER_X_AXIS'
• 'y-axis' / 'CLUTTER_Y_AXIS'
• 'z-axis' / 'CLUTTER_Z_AXIS'

enum ClutterRequestMode

• 'height-for-width' / 'CLUTTER_REQUEST_HEIGHT_FOR_WIDTH'
• 'width-for-height' / 'CLUTTER_REQUEST_WIDTH_FOR_HEIGHT'

TRANSFORMATIONS ORDER

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

EVENT HANDLING

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.

DERIVING NEW ACTORS

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:

  sub APPLY_TRANSFORM {
      my ($self, $matrix) = @_;
      $self->SUPER::APPLY_TRANSFORM ($matrix);
      $matrix->translate($self->{x_offset} * -1,
                         $self->{y_offset} * -1,
                         0.0);
  }

COPYRIGHT

Copyright (C) 2006, 2007, 2008 OpenedHand Ltd

Copyright (C) 2009 Intel Corporation

This module is free software; you can redistribute it and/or modify it under the terms of either:

• the GNU Lesser General Public Library version 2.1; or
• the Artistic License, version 2.0.

See Clutter for the full copyright notice.