Clutter::Actor(3pm)

NAME

Clutter::Actor - Base abstract class for all visual elements

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.

HIERARCHY

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

INTERFACES

Glib::Object::_Unregistered::ClutterScriptable

METHODS

$actor->allocate ($box, $flags): o $box (Clutter::ActorBox); o $flags (Clutter::AllocationFlags)
$actor->allocate_available_size ($x, $y, $available_width,: $available_height, $flags) o $x (double); o $y (double); o $available_width (double); o $available_height (double); o $flags (Clutter::AllocationFlags)
$actor->allocate_preferred_size ($flags): o $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: o $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): o $gravity (Clutter::Gravity)
(x, y) = $actor->get_anchor_point gravity = $actor->get_anchor_point_gravity $actor->set_anchor_point ($x, $y): o $x (double); o $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, ...): o $mode (scalar); o $duration (integer); o ... (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, ...): o $alpha (Clutter::Alpha); o ... (list) list of property name, value pairs
animation = $actor->animate_with_timeline ($mode, $timeline, $name, $value,: ...)
o $mode (scalar); o $timeline (Clutter::Timeline); o ... (list) list of property name, value pairs
vertex = $actor->apply_relative_transform_to_point ($ancestor, $vertex): o $ancestor (Clutter::Actor or undef); o $vertex (Clutter::Vertex)
vertex = $actor->apply_transform_to_point ($vertex): o $vertex (Clutter::Vertex)
(x_offset, y_offset, width, height) = $actor->get_clipu $actor->set_clip ($x_offset, $y_offset, $width, $height): o $x_offset (double); o $y_offset (double); o $width (double); o $height (double)
context = $actor->create_pango_context layout = $actor->create_pango_layout ($text): o $text (string or undef)
double = $actor->get_depth $actor->set_depth ($depth): o $depth (double)
$actor->destroy
boolean = $actor->get_fixed_position_set $actor->set_fixed_position_set ($is_set): o $is_set (boolean)
actorflags = $actor->flags: Retrieves the flags set on the actor
actorflags = $actor->get_flags $actor->set_flags ($flags): o $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): o $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): o $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): o $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): o $gravity (Clutter::Gravity)
$actor->move_by ($dx, $dy): o $dx (double); o $dy (double)
string = $actor->get_name
$actor->set_name ($id): o $id (string)
unsigned = $actor->get_opacity $actor->set_opacity ($opacity): o $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): o $parent (Clutter::Actor)
(x, y) = $actor->get_position $actor->set_position ($x, $y): o $x (double); o $y (double)
(min_height, natural_height) = $actor->get_preferred_height ($for_width): o $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): o $for_height (double)
$actor->queue_redraw
$actor->queue_relayout
$actor->raise ($below=undef): o $below (Clutter::Actor or undef)
$actor->raise_top
$actor->reactive ($boolean) boolean = $actor->get_reactive $actor->set_reactive ($reactive): o $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): o $new_parent (Clutter::Actor)
angle = $actor->get_rotation ($axis) (angle, x, y, z) = $actor->get_rotation ($axis): o $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): o $axis (Clutter::RotateAxis); o $angle (double); o $x (integer); o $y (integer); o $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): o $scale_x (double); o $scale_y (double); o $center_x (double); o $center_y (double)
(scale_x, scale_y) = $actor->get_scale $actor->set_scale ($scale_x, $scale_y): o $scale_x (double); o $scale_y (double)
$actor->set_scale_with_gravity ($scale_x, $scale_y, $gravity): o $scale_x (double); o $scale_y (double); o $gravity (Clutter::Gravity)
shader or undef = $actor->get_shader $actor->set_shader_param ($param, $value): o $param (string); o $value (scalar)
boolean = $actor->set_shader ($shader): o $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): o $width (double); o $height (double)
actor or undef = $actor->get_stage (actor_x, actor_y) = $actor->transform_stage_point ($x, $y): o $x (double); o $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): o $flags (Clutter::ActorFlags); Unsets the given flags on the actor
$actor->visible ($boolean) double = $actor->get_width $actor->set_width ($width): o $width (double)
double = $actor->get_x
$actor->set_x ($x): o $x (double)
double = $actor->get_y
$actor->set_y ($y): o $y (double)
$actor->set_z_rotation_from_gravity ($angle, $gravity): o $angle (double); o $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

SIGNALS

destroy (Clutter::Actor)
show (Clutter::Actor)
hide (Clutter::Actor)
parent-set (Clutter::Actor, Clutter::Actor)
queue-redraw (Clutter::Actor, Clutter::Actor)
boolean = event (Clutter::Actor, Clutter::Event)
boolean = button-press-event (Clutter::Actor, Clutter::Event) boolean = button-release-event (Clutter::Actor, Clutter::Event) boolean = scroll-event (Clutter::Actor, Clutter::Event) boolean = key-press-event (Clutter::Actor, Clutter::Event) boolean = key-release-event (Clutter::Actor, Clutter::Event) boolean = motion-event (Clutter::Actor, Clutter::Event) key-focus-in (Clutter::Actor)
key-focus-out (Clutter::Actor)
boolean = enter-event (Clutter::Actor, Clutter::Event) boolean = leave-event (Clutter::Actor, Clutter::Event) boolean = captured-event (Clutter::Actor, Clutter::Event) paint (Clutter::Actor)
realize (Clutter::Actor)
unrealize (Clutter::Actor)
pick (Clutter::Actor, Clutter::Color)
allocation-changed (Clutter::Actor, Clutter::ActorBox, Clutter::AllocationFlags)

ENUMS AND FLAGS

flags Clutter::ActorFlags: o 'mapped' / 'CLUTTER_ACTOR_MAPPED'; o 'realized' / 'CLUTTER_ACTOR_REALIZED'; o 'reactive' / 'CLUTTER_ACTOR_REACTIVE'; o 'visible' / 'CLUTTER_ACTOR_VISIBLE'
flags Clutter::AllocationFlags: o 'allocation-none' / 'CLUTTER_ALLOCATION_NONE'; o 'absolute-origin-changed' / 'CLUTTER_ABSOLUTE_ORIGIN_CHANGED'
enum Clutter::Gravity: o 'none' / 'CLUTTER_GRAVITY_NONE'; o 'north' / 'CLUTTER_GRAVITY_NORTH'; o 'north-east' / 'CLUTTER_GRAVITY_NORTH_EAST'; o 'east' / 'CLUTTER_GRAVITY_EAST'; o 'south-east' / 'CLUTTER_GRAVITY_SOUTH_EAST'; o 'south' / 'CLUTTER_GRAVITY_SOUTH'; o 'south-west' / 'CLUTTER_GRAVITY_SOUTH_WEST'; o 'west' / 'CLUTTER_GRAVITY_WEST'; o 'north-west' / 'CLUTTER_GRAVITY_NORTH_WEST'; o 'center' / 'CLUTTER_GRAVITY_CENTER'
enum Clutter::RotateAxis: o 'x-axis' / 'CLUTTER_X_AXIS'; o 'y-axis' / 'CLUTTER_Y_AXIS'; o 'z-axis' / 'CLUTTER_Z_AXIS'
enum ClutterRequestMode: o 'height-for-width' / 'CLUTTER_REQUEST_HEIGHT_FOR_WIDTH'; o '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

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

o the GNU Lesser General Public Library version 2.1; or

o the Artistic License, version 2.0.

docs.sk

comprehensive documentation repository

Most Viewed