Linux Certif

Toute la documentation sur la certification Linux LPI

Clutter::Actor.3pm

NAME

Clutter::Actor

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

(x, y) = $actor->get_abs_position

(x, y) = $actor->get_abs_position

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

(width, height) = $actor->get_abs_size

(width, height) = $actor->get_abs_size

Gets the absolute size of an actor taking into account any scaling factors

$actor->set_anchor_point_from_gravity ($gravity)

$actor->set_anchor_point_from_gravity ($gravity)

•

$gravity (Clutter::Gravity)

(x, y) = $actor->get_anchor_point

(x, y) = $actor->get_anchor_point

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

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

•

$x (integer)

•

$y (integer)

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.

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

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 = $actor->apply_transform_to_point ($vertex)

•

$vertex (Clutter::Vertex)

(xoff, yoff, width, height) = $actor->get_clip

(xoff, yoff, width, height) = $actor->get_clip

$actor->set_clip ($xoff, $yoff, $width, $height)

$actor->set_clip ($xoff, $yoff, $width, $height)

•

$xoff (integer)

•

$yoff (integer)

•

$width (integer)

•

$height (integer)

(x1, y1, x2, y2) = $actor->get_coords

(x1, y1, x2, y2) = $actor->get_coords

integer = $actor->get_depth

integer = $actor->get_depth

$actor->set_depth ($depth)

$actor->set_depth ($depth)

•

$depth (integer)

$actor->destroy

$actor->destroy

actorflags = $actor->flags

actorflags = $actor->flags

Retrieves the flags set on the actor

actorflags = $actor->get_flags

actorflags = $actor->get_flags

$actor->set_flags ($flags)

$actor->set_flags ($flags)

•

$flags (Clutter::ActorFlags)

Sets the given flags on the actor

geometry = $actor->get_geometry

geometry = $actor->get_geometry

A simple, pixel-based wrapped around query_coords()

$actor->set_geometry ($geom)

$actor->set_geometry ($geom)

•

$geom (Clutter::Geometry)

A simple, pixel-based wrapper around request_coords()

unsigned = $actor->get_gid

unsigned = $actor->get_gid

boolean = $actor->has_clip

boolean = $actor->has_clip

integer = $actor->get_height

integer = $actor->get_height

$actor->set_height ($height)

$actor->set_height ($height)

•

$height (integer)

$actor->hide

$actor->hide

$actor->hide_all

$actor->hide_all

boolean = $actor->is_rotated

boolean = $actor->is_rotated

boolean = $actor->is_scaled

boolean = $actor->is_scaled

$actor->lower ($above)

$actor->lower ($above)

•

$above (Clutter::Actor)

$actor->lower_bottom

$actor->lower_bottom

$actor->mapped ($boolean)

$actor->mapped ($boolean)

boolean = $actor->mapped

boolean = $actor->mapped

Checks if the actor is mapped

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

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

•

$dx (integer)

•

$dy (integer)

string = $actor->get_name

string = $actor->get_name

$actor->set_name ($id)

$actor->set_name ($id)

•

$id (string)

unsigned = $actor->get_opacity

unsigned = $actor->get_opacity

$actor->set_opacity ($opacity)

$actor->set_opacity ($opacity)

•

$opacity (unsigned)

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

$actor->paint

$actor->paint

actor or undef = $actor->get_parent

actor or undef = $actor->get_parent

$actor->set_parent ($parent)

$actor->set_parent ($parent)

•

$parent (Clutter::Actor)

$actor->pick ($color)

$actor->pick ($color)

•

$color (Clutter::Color)

list = $actor->get_position

list = $actor->get_position

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

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

•

$x (integer)

•

$y (integer)

actorbox = $actor->query_coords

actorbox = $actor->query_coords

Requests the untrasformend bounding box of the actor

$actor->queue_redraw

$actor->queue_redraw

$actor->raise ($below)

$actor->raise ($below)

•

$below (Clutter::Actor)

$actor->raise_top

$actor->raise_top

$actor->reactive ($boolean)

$actor->reactive ($boolean)

boolean = $actor->get_reactive

boolean = $actor->get_reactive

$actor->set_reactive ($reactive)

$actor->set_reactive ($reactive)

•

$reactive (boolean)

Sets whether the actor should react to events

$actor->realize

$actor->realize

$actor->realized ($boolean)

$actor->realized ($boolean)

boolean = $actor->realized

boolean = $actor->realized

Checks if the actor is realized

vertices = $actor->get_relative_vertices ($ancestor)

vertices = $actor->get_relative_vertices ($ancestor)

•

$ancestor (Clutter::Actor or undef)

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

$actor->remove_clip

$actor->remove_clip

$actor->reparent ($new_parent)

$actor->reparent ($new_parent)

•

$new_parent (Clutter::Actor)

$actor->request_coords ($box)

$actor->request_coords ($box)

•

$box (Clutter::ActorBox)

Sets the untransformed bounding box of the actor
Note: The actor might not comply with the request

angle = $actor->get_rotation ($axis)

angle = $actor->get_rotation ($axis)

(angle, x, y, z) = $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, $y, $z)

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

•

$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

(scale_x, scale_y) = $actor->get_scale

(scale_x, scale_y) = $actor->get_scale

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

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

•

$scale_x (double)

•

$scale_y (double)

shader or undef = $actor->get_shader

shader or undef = $actor->get_shader

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

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

•

$param (string)

•

$value (double)

boolean = $actor->set_shader ($shader)

boolean = $actor->set_shader ($shader)

•

$shader (Clutter::Shader or undef)

boolean = $actor->should_pick_paint

boolean = $actor->should_pick_paint

$actor->show

$actor->show

$actor->show_all

$actor->show_all

(width, height) = $actor->get_size

(width, height) = $actor->get_size

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

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

•

$width (integer)

•

$height (integer)

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

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

•

$x (integer)

•

$y (integer)

$actor->unparent

$actor->unparent

$actor->unrealize

$actor->unrealize

$actor->unset_flags ($flags)

$actor->unset_flags ($flags)

•

$flags (Clutter::ActorFlags)

Unsets the given flags on the actor

vertices = $actor->get_vertices

vertices = $actor->get_vertices

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

$actor->visible ($boolean)

$actor->visible ($boolean)

integer = $actor->get_width

integer = $actor->get_width

$actor->set_width ($width)

$actor->set_width ($width)

•

$width (integer)

integer = $actor->get_x

integer = $actor->get_x

$actor->set_x ($x)

$actor->set_x ($x)

•

$x (integer)

integer = $actor->get_y

integer = $actor->get_y

$actor->set_y ($y)

$actor->set_y ($y)

•

$y (integer)

PROPERTIES

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

The clip region for the actor

'depth' (integer : readable / writable / private)

Depth of actor

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

Whether the actor has a clip set or not

'height' (integer : readable / writable / private)

Height of actor in pixels

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

Name of the actor

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

Opacity of actor

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

Whether the actor is reactive to events or not

'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

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

Scale factor on the X axis

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

Scale factor on the Y axis

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

Whether the actor is visible or not

'width' (integer : readable / writable / private)

Width of actor in pixels

'x' (integer : readable / writable / private)

X co-ord of actor

'y' (integer : readable / writable / private)

Y co-ord of actor

SIGNALS

destroy (Clutter::Actor)

show (Clutter::Actor)

hide (Clutter::Actor)

parent-set (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)

focus-in (Clutter::Actor)

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)

ENUMS AND FLAGS

flags Clutter::ActorFlags

•

'mapped' / 'CLUTTER_ACTOR_MAPPED'

•

'realized' / 'CLUTTER_ACTOR_REALIZED'

•

'reactive' / 'CLUTTER_ACTOR_REACTIVE'

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'

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

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:

REQUEST_COORDS ($actor, $box)

o $actor (Clutter::Actor)

o $box (Clutter::ActorBox)

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 " REQUEST_COORDS " method must chain up to the parent's class method, using the usual " SUPER " mechanism provided by Perl, for instance:

   $actor->SUPER::REQUEST_COORDS($box);
 
 

See perlobj.

(x1, y1, x2, y2) = QUERY_COORDS ($actor, $box)

o $actor (Clutter::Actor)

o $box (Clutter::ActorBox)

This is called each time the actor is queried for its coordinates and size. The returned array must contains the upper left and lower right coordinates of the box surrounding the actor, in coordinates relative to the actor's parent.
Note: Actors can mostly ignore the box parameter: it will contain the current coordinates of the actor's bounding box, which can be taken into account when recomputing the new box.

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)

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.

HIDE_ALL ($actor)

o $actor (Clutter::Actor)

See "SHOW_ALL" above.

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) = @_;
 
     glColor4ub($pick_color->red,
                $pick_color->green,
                $pick_color->blue,
                $pick_color->alpha);
     glRecti($self->get_x(),
             $self->get_y(),
             $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) = @_;
 
     glPushMatrix();
 
     glColor4ub($pick_color->red,
                $pick_color->green,
                $pick_color->blue,
                $pick_color->alpha);
     glRecti($self->get_x(),
             $self->get_y(),
             $self->get_x() + $self->get_width(),
             $self->get_y() + $self->get_height());
 
     foreach my $child in ($self->get_children()) {
         $child->paint(); # this will result in the PICK method of
                          # the child being called
     }
 
     glPopMatrix();
   }
 
 

SEE ALSO

Clutter, Glib::Object, Glib::InitiallyUnowned

COPYRIGHT

Copyright (C) 2006 OpenedHand Ltd.

This module is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public Library version 2.1, or under the terms of the Artistic License. See Clutter for the full copyright notice.