ClutterActor - Guile-Clutter

<clutter-actor> is a base abstract class for all visual elements on the stage. Every object that must appear on the main <clutter-stage> must also be a <clutter-actor>, either by using one of the classes provided by Clutter, or by implementing a new <clutter-actor> subclass.

Every actor is a 2D surface positioned and optionally transformed in 3D space. The actor is positioned relative to top left corner of it parent with the childs origin being its anchor point (also top left by default).

The actors 2D surface is contained inside its bounding box, described by the <clutter-actor-box> structure:

The actor box represents the untransformed area occupied by an actor. Each visible actor that has been put on a <clutter-stage> also has a transformed area, depending on the actual transformations applied to it by the developer (scale, rotation). Tranforms will also be applied to any child actors. Also applied to all actors by the <clutter-stage> is a perspective transformation. API is provided for both tranformed and untransformed actor geometry information.

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

Rectangular Clip is applied (this is not an operation on the matrix as such, but it is done as part of the transform set up).

An actor can either be explicitly sized and positioned, using the various size and position accessors, like clutter-actor-set-x or clutter-actor-set-width; or it can have a preferred width and height, which then allows a layout manager to implicitly size and position it by "allocating" an area for an actor. This allows for actors to be manipulate in both a fixed or static parent container (i.e. children of <clutter-group>) and a more automatic or dynamic layout based parent container.

When accessing the position and size of an actor, the simple accessors like clutter-actor-get-width and clutter-actor-get-x will return a value depending on whether the actor has been explicitly sized and positioned by the developer or implicitly by the layout manager.

Depending on whether you are querying an actor or implementing a layout manager, you should either use the simple accessors or use the size negotiation API.

Clutter actors are also able to receive input events and react to them. Events are handled in the following ways:

Events are handled by connecting signal handlers to the numerous event signal types.

Event handlers must return ‘#t’ if they handled the event and wish to block the event emission chain, or ‘#f’ if the emission chain must continue

Keyboard events are emitted if actor has focus, see clutter-stage-set-key-focus

Motion events (motion, enter, leave) are not emitted if clutter-set-motion-events-enabled is called with ‘#f’. See clutter-set-motion-events-enabled documentation for more information.

Once emitted, an event emission chain has two phases: capture and bubble. An emitted event starts in the capture phase (see ClutterActor::captured-event) 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 ‘#t’ (meaning "event handled").

For implementing a new custom actor class, please read the corresponding section of the API reference.

2.2 Usage

— Class: <clutter-actor-box>

Derives from <gboxed>.
This class defines no direct slots.

— Class: <clutter-geometry>

Derives from <gboxed>.
This class defines no direct slots.

— Class: <clutter-actor>

Derives from <clutter-scriptable>, <g-initially-unowned>.
This class defines the following slots:

name
Name of the actor
x
X coordinate of the actor
y
Y coordinate of the actor
width
Width of the actor
height
Height of the actor
fixed-x
Forced X position of the actor
fixed-y
Forced Y position of the actor
fixed-position-set
Whether to use fixed positioning for the actor
min-width
Forced minimum width request for the actor
min-width-set
Whether to use the min-width property
min-height
Forced minimum height request for the actor
min-height-set
Whether to use the min-height property
natural-width
Forced natural width request for the actor
natural-width-set
Whether to use the natural-width property
natural-height
Forced natural height request for the actor
natural-height-set
Whether to use the natural-height property
request-mode
The actor's request mode
allocation
The actor's allocation
depth
Depth of actor
clip
The clip region for the actor
has-clip
Whether the actor has a clip set or not
opacity
Opacity of actor
visible
Whether the actor is visible or not
reactive
Whether the actor is reactive to events or not
scale-x
Scale factor on the X axis
scale-y
Scale factor on the Y axis
rotation-angle-x
The rotation angle on the X axis
rotation-angle-y
The rotation angle on the Y axis
rotation-angle-z
The rotation angle on the Z axis
rotation-center-x
The rotation center on the X axis
rotation-center-y
The rotation center on the Y axis
rotation-center-z
The rotation center on the Z axis
anchor-x
X coordinate of the anchor point
anchor-y
Y coordinate of the anchor point
show-on-set-parent
Whether the actor is shown when parented

— Signal on <clutter-actor>: destroy

The ::destroy signal is emitted when an actor is destroyed, either by direct invocation of clutter-actor-destroy or when the <clutter-group> that contains the actor is destroyed.
Since 0.2

— Signal on <clutter-actor>: show

The ::show signal is emitted when an actor is visible and rendered on the stage.
Since 0.2

— Signal on <clutter-actor>: hide

The ::hide signal is emitted when an actor is no longer rendered on the stage.
Since 0.2

— Signal on <clutter-actor>: parent-set (arg0 <clutter-actor>)

This signal is emitted when the parent of the actor changes.
Since 0.2

— Signal on <clutter-actor>: event (arg0 <clutter-event>) <gboolean>

The ::event signal is emitted each time an event is received by the actor. This signal will be emitted on every actor, following the hierarchy chain, until it reaches the top-level container (the <clutter-stage>).
Since 0.6

— Signal on <clutter-actor>: button-press-event (arg0 <clutter-event>) <gboolean>

The ::button-press-event signal is emitted each time a mouse button is pressed on actor.
Since 0.6

— Signal on <clutter-actor>: button-release-event (arg0 <clutter-event>) <gboolean>

The ::button-release-event signal is emitted each time a mouse button is released on actor.
Since 0.6

— Signal on <clutter-actor>: scroll-event (arg0 <clutter-event>) <gboolean>

The ::scroll-event signal is emitted each time the mouse is scrolled on actor
Since 0.6

— Signal on <clutter-actor>: key-press-event (arg0 <clutter-event>) <gboolean>

The ::key-press-event signal is emitted each time a keyboard button is pressed while actor has key focus (see clutter-stage-set-key-focus).
Since 0.6

— Signal on <clutter-actor>: key-release-event (arg0 <clutter-event>) <gboolean>

The ::key-release-event signal is emitted each time a keyboard button is released while actor has key focus (see clutter-stage-set-key-focus).
Since 0.6

— Signal on <clutter-actor>: motion-event (arg0 <clutter-event>) <gboolean>

The ::motion-event signal is emitted each time the mouse pointer is moved over actor.
Since 0.6

— Signal on <clutter-actor>: focus-in

The ::focus-in signal is emitted when actor recieves key focus.
Since 0.6

— Signal on <clutter-actor>: focus-out

The ::focus-out signal is emitted when actor loses key focus.
Since 0.6

— Signal on <clutter-actor>: enter-event (arg0 <clutter-event>) <gboolean>

The ::enter-event signal is emitted when the pointer enters the actor
Since 0.6

— Signal on <clutter-actor>: leave-event (arg0 <clutter-event>) <gboolean>

The ::leave-event signal is emitted when the pointer leaves the actor.
Since 0.6

— Signal on <clutter-actor>: captured-event (arg0 <clutter-event>) <gboolean>

The ::captured-event signal is emitted when an event is captured by Clutter. This signal will be emitted starting from the top-level container (the <clutter-stage>) to the actor which received the event going down the hierarchy. This signal can be used to intercept every event before the specialized events (like ClutterActor::button-press-event or ::key-released-event) are emitted.
Since 0.6

— Signal on <clutter-actor>: paint

The ::paint signal is emitted each time an actor is being painted.
Subclasses of <clutter-actor> should override the class signal handler and paint themselves in that function.
It is possible to connect a handler to the ::paint signal in order to set up some custom aspect of a paint.
Since 0.8

— Signal on <clutter-actor>: realize

The ::realize signal is emitted each time an actor is being realized.
Since 0.8

— Signal on <clutter-actor>: unrealize

The ::unrealize signal is emitted each time an actor is being unrealized.
Since 0.8

— Class: <clutter-vertex>

Derives from <gboxed>.
This class defines no direct slots.

— Function: clutter-actor-show (self <clutter-actor>)
— Method: show

Flags an actor to be displayed. An actor that isn't shown will not be rendered on the stage.
Actors are visible by default.
If this function is called on an actor without a parent, the <"show-on-set-parent"> will be set to ‘#t’ as a side effect.

self
A <clutter-actor>

— Function: clutter-actor-show-all (self <clutter-actor>)
— Method: show-all

Calls clutter-actor-show on all children of an actor (if any).

self
a <clutter-actor>

Since 0.2

— Function: clutter-actor-hide (self <clutter-actor>)
— Method: hide

Flags an actor to be hidden. A hidden actor will not be rendered on the stage.
Actors are visible by default.
If this function is called on an actor without a parent, the <"show-on-set-parent"> property will be set to ‘#f’ as a side-effect.

self
A <clutter-actor>

— Function: clutter-actor-hide-all (self <clutter-actor>)
— Method: hide-all

Calls clutter-actor-hide on all child actors (if any).

self
a <clutter-actor>

Since 0.2

— Function: clutter-actor-realize (self <clutter-actor>)
— Method: realize

Creates any underlying graphics resources needed by the actor to be displayed.

self
A <clutter-actor>

— Function: clutter-actor-unrealize (self <clutter-actor>)
— Method: unrealize

Frees up any underlying graphics resources needed by the actor to be displayed.

self
A <clutter-actor>

— Function: clutter-actor-paint (self <clutter-actor>)
— Method: paint

Renders the actor to display.
This function should not be called directly by applications. Call clutter-actor-queue-redraw to queue paints, instead.

self
A <clutter-actor>

— Function: clutter-actor-queue-redraw (self <clutter-actor>)
— Method: queue-redraw

Queues up a redraw of an actor and any children. The redraw occurs once the main loop becomes idle (after the current batch of events has been processed, roughly).
Applications rarely need to call this, as redraws are handled automatically by modification functions.

self
A <clutter-actor>

— Function: clutter-actor-queue-relayout (self <clutter-actor>)
— Method: queue-relayout

Indicates that the actor's size request or other layout-affecting properties may have changed. This function is used inside <clutter-actor> subclass implementations, not by applications directly.
Queueing a new layout automatically queues a redraw as well.

self
A <clutter-actor>

Since 0.8

— Function: clutter-actor-destroy (self <clutter-actor>)
— Method: destroy

Destroys an actor. When an actor is destroyed, it will break any references it holds to other objects. If the actor is inside a container, the actor will be removed.
When you destroy a container, its children will be destroyed as well.
Note: you cannot destroy the <clutter-stage> returned by clutter-stage-get-default.

self
a <clutter-actor>

— Function: clutter-actor-event (self <clutter-actor>) (event <clutter-event>) (capture bool) (ret bool)
— Method: event

This function is used to emit an event on the main stage. You should rarely need to use this function, except for synthetising events.

actor
a <clutter-actor>
event
a <clutter-event>
capture
TRUE if event in in capture phase, FALSE otherwise.
ret
the return value from the signal emission: ‘#t’ if the actor handled the event, or ‘#f’ if the event was not handled

Since 0.6

— Function: clutter-actor-pick (self <clutter-actor>) (color <clutter-color>)
— Method: pick

Renders a silhouette of the actor using the supplied color. Used internally for mapping pointer events to actors.
This function should never be called directly by applications.
Subclasses overiding the ClutterActor::pick method should call clutter-actor-should-pick-paint to decide whether to render their silhouette. Containers should always recursively call pick for each child.
Since 0.4

self
A <clutter-actor>
color
A <clutter-color>

— Function: clutter-actor-should-pick-paint (self <clutter-actor>) (ret bool)
— Method: should-pick-paint

Utility call for subclasses overiding the pick method.
This function should never be called directly by applications.

self
A <clutter-actor>
ret
‘#t’ if the actor should paint its silhouette, ‘#f’ otherwise

— Function: clutter-actor-allocate (self <clutter-actor>) (box <clutter-actor-box>) (absolute_origin_changed bool)
— Method: allocate

Called by the parent of an actor to assign the actor its size. Should never be called by applications (except when implementing a container or layout manager).
Actors can know from their allocation box whether they have moved with respect to their parent actor. The absolute_origin_changed parameter additionally indicates whether the parent has moved with respect to the stage, for example because a grandparent's origin has moved.

self
A <clutter-actor>
box
new allocation of the actor, in parent-relative coordinates
absolute-origin-changed
whether the position of the parent has changed in stage coordinates

Since 0.8

— Function: clutter-actor-get-allocation-coords (self <clutter-actor>) (x_1 int) (y_1 int) (x_2 int) (y_2 int)
— Method: get-allocation-coords

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint method; anywhere else, it may be out-of-date.
An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
The returned coordinates are in pixels.

self
A <clutter-actor>
x-1
x1 coordinate
y-1
y1 coordinate
x-2
x2 coordinate
y-2
y2 coordinate

Since 0.8

— Function: clutter-actor-get-allocation-box (self <clutter-actor>) (box <clutter-actor-box>)
— Method: get-allocation-box

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a paint method; anywhere else, it may be out-of-date.
An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.
Do not call any of the clutter_actor_get_allocation_*() family of functions inside the implementation of the get-preferred-width or get-preferred-height virtual functions.

self
A <clutter-actor>
box
the function fills this in with the actor's allocation

Since 0.8

— Function: clutter-actor-get-preferred-size (self <clutter-actor>) (min_width_p <clutter-unit>) (min_height_p <clutter-unit>) (natural_width_p <clutter-unit>) (natural_height_p <clutter-unit>)
— Method: get-preferred-size

Computes the preferred minimum and natural size of an actor, taking into account the actor's geometry management (either height-for-width or width-for-height).
The width and height used to compute the preferred height and preferred width are the actor's natural ones.
If you need to control the height for the preferred width, or the width for the preferred height, you should use clutter-actor-get-preferred-width and clutter-actor-get-preferred-height, and check the actor's preferred geometry management using the <"request-mode"> property.

self
a <clutter-actor>
min-width-p
return location for the minimum width, or ‘#f’
min-height-p
return location for the minimum height, or ‘#f’
natural-width-p
return location for the natural width, or ‘#f’
natural-height-p
return location for the natural height, or ‘#f’

Since 0.8

— Function: clutter-actor-get-preferred-width (self <clutter-actor>) (for_height <clutter-unit>) (min_width_p <clutter-unit>) (natural_width_p <clutter-unit>)
— Method: get-preferred-width

Computes the requested minimum and natural widths for an actor, optionally depending on the specified height, or if they are already computed, returns the cached values.
An actor may not get its request - depending on the layout manager that's in effect.
A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

self
A <clutter-actor>
for-height
available height when computing the preferred width, or a negative value to indicate that no height is defined
min-width-p
return location for minimum width, or ‘#f’
natural-width-p
return location for the natural width, or ‘#f’

Since 0.8

— Function: clutter-actor-get-preferred-height (self <clutter-actor>) (for_width <clutter-unit>) (min_height_p <clutter-unit>) (natural_height_p <clutter-unit>)
— Method: get-preferred-height

Computes the requested minimum and natural heights for an actor, or if they are already computed, returns the cached values.
An actor may not get its request - depending on the layout manager that's in effect.
A request should not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

self
A <clutter-actor>
for-width
available width to assume in computing desired height, or a negative value to indicate that no width is defined
min-height-p
return location for minimum height, or ‘#f’
natural-height-p
return location for natural height, or ‘#f’

Since 0.8

— Function: clutter-actor-set-geometry (self <clutter-actor>) (geometry <clutter-geometry>)
— Method: set-geometry

Sets the actor's fixed position and forces its minimum and natural size, in pixels. This means the untransformed actor will have the given geometry. This is the same as calling clutter-actor-set-position and clutter-actor-set-size.

self
A <clutter-actor>
geometry
A <clutter-geometry>

— Function: clutter-actor-get-geometry (self <clutter-actor>) (geometry <clutter-geometry>)
— Method: get-geometry

Gets the size and position of an actor relative to its parent actor. This is the same as calling clutter-actor-get-position and clutter-actor-get-size. It tries to "do what you mean" and get the requested size and position if the actor's allocation is invalid.

self
A <clutter-actor>
geometry
A location to store actors <clutter-geometry>

— Function: clutter-actor-set-size (self <clutter-actor>) (width int) (height int)
— Method: set-size

Sets the actor's size request in pixels. This overrides any "normal" size request the actor would have. For example a text actor might normally request the size of the text; this function would force a specific size instead.
If width and/or height are -1 the actor will use its "normal" size request instead of overriding it, i.e. you can "unset" the size with -1.
This function sets or unsets both the minimum and natural size.

self
A <clutter-actor>
width
New width of actor in pixels, or -1
height
New height of actor in pixels, or -1

— Function: clutter-actor-get-size (self <clutter-actor>) (width unsigned-int) (height unsigned-int)
— Method: get-size

This function tries to "do what you mean" and return the size an actor will have. If the actor has a valid allocation, the allocation will be returned; otherwise, the actors natural size request will be returned.
If you care whether you get the request vs. the allocation, you should probably call a different function like clutter-actor-get-allocation-coords or clutter-actor-get-preferred-width.

self
A <clutter-actor>
width
return location for the width, or ‘#f’.
height
return location for the height, or ‘#f’.

Since 0.2

— Function: clutter-actor-set-position (self <clutter-actor>) (x int) (y int)
— Method: set-position

Sets the actor's fixed position in pixels relative to any parent actor.
If a layout manager is in use, this position will override the layout manager and force a fixed position.

self
A <clutter-actor>
x
New left position of actor in pixels.
y
New top position of actor in pixels.

— Function: clutter-actor-get-position (self <clutter-actor>) (x int) (y int)
— Method: get-position

This function tries to "do what you mean" and tell you where the actor is, prior to any transformations. Retrieves the fixed position of an actor in pixels, if one has been set; otherwise, if the allocation is valid, returns the actor's allocated position; otherwise, returns 0,0.
The returned position is in pixels.

self
a <clutter-actor>
x
return location for the X coordinate, or ‘#f’
y
return location for the Y coordinate, or ‘#f’

Since 0.6

— Function: clutter-actor-set-width (self <clutter-actor>) (width unsigned-int)
— Method: set-width

Forces a width on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.

self
A <clutter-actor>
width
Requested new width for the actor, in pixels

Since 0.2

— Function: clutter-actor-get-width (self <clutter-actor>) (ret unsigned-int)
— Method: get-width

Retrieves the width of a <clutter-actor>.
If the actor has a valid allocation, this function will return the width of the allocated area given to the actor.
If the actor does not have a valid allocation, this function will return the actor's natural width, that is the preferred width of the actor.
If you care whether you get the preferred width or the width that has been assigned to the actor, you should probably call a different function like clutter-actor-get-allocation-coords to retrieve the allocated size or clutter-actor-get-preferred-width to retrieve the preferred width.
If an actor has a fixed width, for instance a width that has been assigned using clutter-actor-set-width, the width returned will be the same value.

self
A <clutter-actor>
ret
the width of the actor, in pixels

— Function: clutter-actor-set-height (self <clutter-actor>) (height unsigned-int)
— Method: set-height

Forces a height on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.

self
A <clutter-actor>
height
Requested new height for the actor, in pixels

Since 0.2

— Function: clutter-actor-get-height (self <clutter-actor>) (ret unsigned-int)
— Method: get-height

Retrieves the height of a <clutter-actor>.
If the actor has a valid allocation, this function will return the height of the allocated area given to the actor.
If the actor does not have a valid allocation, this function will return the actor's natural height, that is the preferred height of the actor.
If you care whether you get the preferred height or the height that has been assigned to the actor, you should probably call a different function like clutter-actor-get-allocation-coords to retrieve the allocated size or clutter-actor-get-preferred-height to retrieve the preferred height.
If an actor has a fixed height, for instance a height that has been assigned using clutter-actor-set-height, the height returned will be the same value.

self
A <clutter-actor>
ret
the height of the actor, in pixels

— Function: clutter-actor-set-x (self <clutter-actor>) (x int)
— Method: set-x

Sets the actor's X coordinate, relative to its parent, in pixels.
Overrides any layout manager and forces a fixed position for the actor.

self
a <clutter-actor>
x
the actor's position on the X axis

Since 0.6

— Function: clutter-actor-get-x (self <clutter-actor>) (ret int)
— Method: get-x

Retrieves the X coordinate of a <clutter-actor>.
This function tries to "do what you mean", by returning the correct value depending on the actor's state.
If the actor has a valid allocation, this function will return the X coordinate of the origin of the allocation box.
If the actor has any fixed coordinate set using clutter-actor-set-x, clutter-actor-set-position or clutter-actor-set-geometry, this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.

self
A <clutter-actor>
ret
the X coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)

— Function: clutter-actor-set-y (self <clutter-actor>) (y int)
— Method: set-y

Sets the actor's Y coordinate, relative to its parent, in pixels.#
Overrides any layout manager and forces a fixed position for the actor.

self
a <clutter-actor>
y
the actor's position on the Y axis

Since 0.6

— Function: clutter-actor-get-y (self <clutter-actor>) (ret int)
— Method: get-y

Retrieves the Y coordinate of a <clutter-actor>.
This function tries to "do what you mean", by returning the correct value depending on the actor's state.
If the actor has a valid allocation, this function will return the Y coordinate of the origin of the allocation box.
If the actor has any fixed coordinate set using clutter-actor-set-y, clutter-actor-set-position or clutter-actor-set-geometry, this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.

self
A <clutter-actor>
ret
the Y coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)

— Function: clutter-actor-move-by (self <clutter-actor>) (dx int) (dy int)
— Method: move-by

Moves an actor by the specified distance relative to its current position in pixels. This function modifies the fixed position of an actor and thus removes it from any layout management. Another way to move an actor is with an anchor point, see clutter-actor-set-anchor-point.

self
A <clutter-actor>
dx
Distance to move Actor on X axis.
dy
Distance to move Actor on Y axis.

Since 0.2

— Function: clutter-actor-set-rotation (self <clutter-actor>) (axis <clutter-rotate-axis>) (angle double) (x int) (y int) (z int)
— Method: set-rotation

Sets the rotation angle of self around the given axis.
The rotation center coordinates used depend on the value of axis:

‘CLUTTER_X_AXIS’ requires y and z
‘CLUTTER_Y_AXIS’ requires x and z
‘CLUTTER_Z_AXIS’ requires x and y
The rotation coordinates are relative to the anchor point of the actor, set using clutter-actor-set-anchor-point. If no anchor point is set, the upper left corner is assumed as the origin.

self
a <clutter-actor>
axis
the axis of rotation
angle
the angle of rotation
x
X coordinate of the rotation center
y
Y coordinate of the rotation center
z
Z coordinate of the rotation center

Since 0.6

— Function: clutter-actor-get-rotation (self <clutter-actor>) (axis <clutter-rotate-axis>) (ret double) (x int) (y int) (z int)
— Method: get-rotation

Retrieves the angle and center of rotation on the given axis, set using clutter-actor-set-angle.
The coordinates of the center returned by this function depend on the axis passed.

self
a <clutter-actor>
axis
the axis of rotation
x
return value for the X coordinate of the center of rotation
y
return value for the Y coordinate of the center of rotation
z
return value for the Z coordinate of the center of rotation
ret
the angle of rotation.

Since 0.6

— Function: clutter-actor-is-rotated (self <clutter-actor>) (ret bool)
— Method: is-rotated

Checks whether any rotation is applied to the actor.

self
a <clutter-actor>
ret
‘#t’ if the actor is rotated.

Since 0.6

— Function: clutter-actor-set-opacity (self <clutter-actor>) (opacity unsigned-int8)
— Method: set-opacity

Sets the actor's opacity, with zero being completely transparent and 255 (0xff) being fully opaque.

self
A <clutter-actor>
opacity
New opacity value for the actor.

— Function: clutter-actor-get-opacity (self <clutter-actor>) (ret unsigned-int8)
— Method: get-opacity

Retrieves the opacity value of an actor, as set by clutter-actor-set-opacity.
For retrieving the absolute opacity of the actor inside a paint virtual function, see clutter-actor-get-paint-opacity.

self
a <clutter-actor>
ret
the opacity of the actor

— Function: clutter-actor-set-name (self <clutter-actor>) (name mchars)
— Method: set-name

Sets the given name to self. The name can be used to identify a <clutter-actor>.

self
A <clutter-actor>
name
Textual tag to apply to actor

— Function: clutter-actor-get-name (self <clutter-actor>) (ret mchars)
— Method: get-name

Retrieves the name of self.

self
A <clutter-actor>
ret
the name of the actor, or ‘#f’. The returned string is owned by the actor and should not be modified or freed.

— Function: clutter-actor-get-gid (self <clutter-actor>) (ret unsigned-int32)
— Method: get-gid

Retrieves the unique id for self.

self
A <clutter-actor>
ret
Globally unique value for this object instance.

Since 0.6

— Function: clutter-actor-set-clip (self <clutter-actor>) (xoff int) (yoff int) (width int) (height int)
— Method: set-clip

Sets clip area in pixels for self. The clip area is always computed from the upper left corner of the actor, even if the anchor point is set otherwise.

self
A <clutter-actor>
xoff
X offset of the clip rectangle, in pixels
yoff
Y offset of the clip rectangle, in pixels
width
Width of the clip rectangle, in pixels
height
Height of the clip rectangle, in pixels

— Function: clutter-actor-remove-clip (self <clutter-actor>)
— Method: remove-clip

Removes clip area from self.

self
A <clutter-actor>

— Function: clutter-actor-has-clip (self <clutter-actor>) (ret bool)
— Method: has-clip

Determines whether the actor has a clip area set or not.

self
a <clutter-actor>
ret
‘#t’ if the actor has a clip area set.

Since 0.1.1

— Function: clutter-actor-get-clip (self <clutter-actor>) (xoff int) (yoff int) (width int) (height int)
— Method: get-clip

Gets the clip area for self, in pixels.

self
a <clutter-actor>
xoff
return location for the X offset of the clip rectangle, or ‘#f’
yoff
return location for the Y offset of the clip rectangle, or ‘#f’
width
return location for the width of the clip rectangle, or ‘#f’
height
return location for the height of the clip rectangle, or ‘#f’

Since 0.6

— Function: clutter-actor-set-parent (self <clutter-actor>) (parent <clutter-actor>)
— Method: set-parent

Sets the parent of self to parent. The opposite function is clutter-actor-unparent.
This function should not be used by applications, but by custom container actor subclasses.

self
A <clutter-actor>
parent
A new <clutter-actor> parent

— Function: clutter-actor-get-parent (self <clutter-actor>) (ret <clutter-actor>)
— Method: get-parent

Retrieves the parent of self.

self
A <clutter-actor>
ret
The <clutter-actor> parent, or ‘#f’ if no parent is set

— Function: clutter-actor-reparent (self <clutter-actor>) (new_parent <clutter-actor>)
— Method: reparent

This function resets the parent actor of self. It is logically equivalent to calling clutter-actor-unparent and clutter-actor-set-parent.

self
a <clutter-actor>
new-parent
the new <clutter-actor> parent

Since 0.2

— Function: clutter-actor-unparent (self <clutter-actor>)
— Method: unparent

Removes the parent of self.
This function should not be used in applications. It should be called by implementations of container actors, to dissociate a child from the container.

self
a <clutter-actor>

Since 0.1.1

— Function: clutter-actor-raise (self <clutter-actor>) (below <clutter-actor>)
— Method: raise

Puts self above below.
Both actors must have the same parent.
This function is the equivalent of clutter-container-raise-child.

self
A <clutter-actor>
below
A <clutter-actor> to raise above.

— Function: clutter-actor-lower (self <clutter-actor>) (above <clutter-actor>)
— Method: lower

Puts self below above.
Both actors must have the same parent.
This function is the equivalent of clutter-container-lower-child.

self
A <clutter-actor>
above
A <clutter-actor> to lower below

— Function: clutter-actor-raise-top (self <clutter-actor>)
— Method: raise-top

Raises self to the top.
This function calls clutter-actor-raise internally.

self
A <clutter-actor>

— Function: clutter-actor-lower-bottom (self <clutter-actor>)
— Method: lower-bottom

Lowers self to the bottom.
This function calls clutter-actor-lower internally.

self
A <clutter-actor>

— Function: clutter-actor-get-stage (self <clutter-actor>) (ret <clutter-actor>)
— Method: get-stage

Retrieves the <clutter-stage> where actor is contained.

actor
a <clutter-actor>
ret
the stage containing the actor, or ‘#f’

Since 0.8

— Function: clutter-actor-set-depth (self <clutter-actor>) (depth int)
— Method: set-depth

Sets the Z co-ordinate of self to depth. The Units of which are dependant on the perspective setup.

self
a <clutter-actor>
depth
Z co-ord

— Function: clutter-actor-get-depth (self <clutter-actor>) (ret int)
— Method: get-depth

Retrieves the depth of self.

self
a <clutter-actor>
ret
the depth of the actor

— Function: clutter-actor-set-scale (self <clutter-actor>) (scale_x double) (scale_y double)
— Method: set-scale

Scales an actor with the given factors. The scaling is always relative to the anchor point.

self
A <clutter-actor>
scale-x
double factor to scale actor by horizontally.
scale-y
double factor to scale actor by vertically.

Since 0.2

— Function: clutter-actor-get-scale (self <clutter-actor>) (scale_x double) (scale_y double)
— Method: get-scale

Retrieves an actors scale in floating point.

self
A <clutter-actor>
scale-x
Location to store horizonal float scale factor, or ‘#f’.
scale-y
Location to store vertical float scale factor, or ‘#f’.

Since 0.2

— Function: clutter-actor-is-scaled (self <clutter-actor>) (ret bool)
— Method: is-scaled

Checks whether the actor is scaled in either dimension.

self
a <clutter-actor>
ret
‘#t’ if the actor is scaled.

Since 0.6

— Function: clutter-actor-transform-stage-point (self <clutter-actor>) (x <clutter-unit>) (y <clutter-unit>) (ret bool) (x_out <clutter-unit>) (y_out <clutter-unit>)
— Method: transform-stage-point

This function translates screen coordinates (x, y) to coordinates relative to the actor. For example, it can be used to translate screen events from global screen coordinates into actor-local coordinates.
The conversion can fail, notably if the transform stack results in the actor being projected on the screen as a mere line.
The conversion should not be expected to be pixel-perfect due to the nature of the operation. In general the error grows when the skewing of the actor rectangle on screen increases.
Note: This function is fairly computationally intensive.
Note: This function only works when the allocation is up-to-date, i.e. inside of paint

self
A <clutter-actor>
x
x screen coordinate of the point to unproject, in <clutter-unit>s
y
y screen coordinate of the point to unproject, in <clutter-unit>s
x-out
return location for the unprojected x coordinance, in <clutter-unit>s
y-out
return location for the unprojected y coordinance, in <clutter-unit>s
ret
‘#t’ if conversion was successful.

Since 0.6

— Function: clutter-actor-get-transformed-size (self <clutter-actor>) (width unsigned-int) (height unsigned-int)
— Method: get-transformed-size

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

self
A <clutter-actor>
width
return location for the width, or ‘#f’
height
return location for the height, or ‘#f’

Since 0.8

— Function: clutter-actor-get-paint-opacity (self <clutter-actor>) (ret unsigned-int8)
— Method: get-paint-opacity

Retrieves the absolute opacity of the actor, as it appears on the stage.
This function traverses the hierarchy chain and composites the opacity of the actor with that of its parents.
This function is intended for subclasses to use in the paint virtual function, to paint themselves with the correct opacity.

self
A <clutter-actor>
ret
The actor opacity value.

Since 0.8

— Function: clutter-actor-set-anchor-point (self <clutter-actor>) (anchor_x int) (anchor_y int)
— Method: set-anchor-point

Sets an anchor point for the actor. The anchor point is a point in the coordinate space of an actor to which the actor position within its parent is relative; the default is (0, 0), i.e. the top-left corner of the actor.

self
a <clutter-actor>
anchor-x
X coordinate of the anchor point
anchor-y
Y coordinate of the anchor point

Since 0.6

— Function: clutter-actor-get-anchor-point (self <clutter-actor>) (anchor_x int) (anchor_y int)
— Method: get-anchor-point

Gets the current anchor point of the actor in pixels.

self
a <clutter-actor>
anchor-x
return location for the X coordinate of the anchor point
anchor-y
return location for the y coordinate of the anchor point

Since 0.6

— Function: clutter-actor-move-anchor-point (self <clutter-actor>) (anchor_x int) (anchor_y int)
— Method: move-anchor-point

Sets an anchor point for the actor, and adjusts the actor postion so that the relative position of the actor toward its parent remains the same.

self
a <clutter-actor>
anchor-x
X coordinate of the anchor point
anchor-y
Y coordinate of the anchor point

Since 0.6

— Function: clutter-actor-set-reactive (self <clutter-actor>) (reactive bool)
— Method: set-reactive

Sets actor as reactive. Reactive actors will receive events.

actor
a <clutter-actor>
reactive
whether the actor should be reactive to events

Since 0.6

— Function: clutter-actor-get-reactive (self <clutter-actor>) (ret bool)
— Method: get-reactive

Checks whether actor is marked as reactive.

actor
a <clutter-actor>
ret
‘#t’ if the actor is reactive

Since 0.6

— Function: clutter-actor-set-shader (self <clutter-actor>) (shader <clutter-shader>) (ret bool)
— Method: set-shader

Sets the <clutter-shader> to be used when rendering self. If shader is ‘#f’ it will unset any currently set shader for the actor.

self
a <clutter-actor>
shader
a <clutter-shader> or ‘#f’ to unset the shader.
ret
‘#t’ if the shader was successfully applied

Since 0.6

— Function: clutter-actor-get-shader (self <clutter-actor>) (ret <clutter-shader>)
— Method: get-shader

Queries the currently set <clutter-shader> on self.

self
a <clutter-actor>
ret
The currently set <clutter-shader> or ‘#f’ if no shader is set.

Since 0.6

— Function: clutter-actor-set-shader-param (self <clutter-actor>) (param mchars) (value float)
— Method: set-shader-param

Sets the value for a named parameter of the shader applied to actor.

self
a <clutter-actor>
param
the name of the parameter
value
the value of the parameter

Since 0.6

— Function: clutter-actor-set-depthu (self <clutter-actor>) (depth <clutter-unit>)
— Method: set-depthu

Sets the Z co-ordinate of self to depth in <clutter-unit>s, the units of which are dependant on the perspective setup.

self
a <clutter-actor>
depth
Z co-ordinate, in <clutter-unit>s

— Function: clutter-actor-get-depthu (self <clutter-actor>) (ret <clutter-unit>)
— Method: get-depthu

Retrieves the depth of self.

self
a <clutter-actor>
ret
the depth of the actor, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-set-heightu (self <clutter-actor>) (height <clutter-unit>)
— Method: set-heightu

Forces a height on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.

self
A <clutter-actor>
height
Requested new height for the actor, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-heightu (self <clutter-actor>) (ret <clutter-unit>)
— Method: get-heightu

Retrieves the height of a <clutter-actor>, in <clutter-unit>s.
If the actor has a valid allocation, this function will return the height of the allocated area given to the actor.
If the actor does not have a valid allocation, this function will return the actor's natural height, that is the preferred height of the actor.
If you care whether you get the preferred height or the height that has been assigned to the actor, you should probably call a different function like clutter-actor-get-allocation-coords to retrieve the allocated size or clutter-actor-get-preferred-height to retrieve the preferred height.
If an actor has a fixed height, for instance a height that has been assigned using clutter-actor-set-height, the height returned will be the same value.

self
A <clutter-actor>
ret
the height of the actor, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-set-widthu (self <clutter-actor>) (width <clutter-unit>)
— Method: set-widthu

Forces a width on an actor, causing the actor's preferred width and height (if any) to be ignored.
This function sets both the minimum and natural size of the actor.

self
A <clutter-actor>
width
Requested new width for the actor, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-widthu (self <clutter-actor>) (ret <clutter-unit>)
— Method: get-widthu

Retrieves the width of a <clutter-actor>, in <clutter-unit>s.
If the actor has a valid allocation, this function will return the width of the allocated area given to the actor.
If the actor does not have a valid allocation, this function will return the actor's natural width, that is the preferred width of the actor.
If you care whether you get the preferred width or the width that has been assigned to the actor, you should probably call a different function like clutter-actor-get-allocation-coords to retrieve the allocated size or clutter-actor-get-preferred-width to retrieve the preferred width.
If an actor has a fixed width, for instance a width that has been assigned using clutter-actor-set-width, the width returned will be the same value.

self
A <clutter-actor>
ret
the width of the actor, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-set-xu (self <clutter-actor>) (x <clutter-unit>)
— Method: set-xu

Sets the actor's X coordinate, relative to its parent.
Overrides any layout manager and forces a fixed position for the actor.

self
a <clutter-actor>
x
the actor's position on the X axis, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-xu (self <clutter-actor>) (ret <clutter-unit>)
— Method: get-xu

Retrieves the X coordinate of a <clutter-actor>, in <clutter-unit>s.
This function tries to "do what you mean", by returning the correct value depending on the actor's state.
If the actor has a valid allocation, this function will return the X coordinate of the origin of the allocation box.
If the actor has any fixed coordinate set using clutter-actor-set-x, clutter-actor-set-position or clutter-actor-set-geometry, this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.

self
A <clutter-actor>
ret
the X coordinate, in <clutter-unit>s, ignoring any transformation (i.e. scaling, rotation)

Since 0.6

— Function: clutter-actor-set-yu (self <clutter-actor>) (y <clutter-unit>)
— Method: set-yu

Sets the actor's Y coordinate, relative to its parent.
Overrides any layout manager and forces a fixed position for the actor.

self
a <clutter-actor>
y
the actor's position on the Y axis, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-yu (self <clutter-actor>) (ret <clutter-unit>)
— Method: get-yu

Retrieves the Y coordinate of a <clutter-actor>, in <clutter-unit>s.
This function tries to "do what you mean", by returning the correct value depending on the actor's state.
If the actor has a valid allocation, this function will return the Y coordinate of the origin of the allocation box.
If the actor has any fixed coordinate set using clutter-actor-set-y, clutter-actor-set-position or clutter-actor-set-geometry, this function will return that coordinate.
If both the allocation and a fixed position are missing, this function will return 0.

self
A <clutter-actor>
ret
the Y coordinate, in <clutter-unit>s, ignoring any transformation (i.e. scaling, rotation)

Since 0.6

— Function: clutter-actor-set-positionu (self <clutter-actor>) (x <clutter-unit>) (y <clutter-unit>)
— Method: set-positionu

Sets the actor's position in <clutter-unit>s relative to any parent actor.
If a layout manager is in use, this position will override the layout manager and force a fixed position.

self
A <clutter-actor>
x
New left position of actor in <clutter-unit>s
y
New top position of actor in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-positionu (self <clutter-actor>) (x <clutter-unit>) (y <clutter-unit>)
— Method: get-positionu

This function tries to "do what you mean" and tell you where the actor is, prior to any transformations. Retrieves the fixed position of an actor in pixels, if one has been set; otherwise, if the allocation is valid, returns the actor's allocated position; otherwise, returns 0,0.
The returned position is in <clutter-unit>s.

self
a <clutter-actor>
x
return location for the X coordinate, or ‘#f’
y
return location for the Y coordinate, or ‘#f’

Since 0.6

— Function: clutter-actor-set-sizeu (self <clutter-actor>) (width <clutter-unit>) (height <clutter-unit>)
— Method: set-sizeu

Overrides the actor's size request in <clutter-unit>s. If width and/or height are -1 the actor will use its normal size request (the override is removed).
This function sets or unsets both the minimum and natural size.

self
A <clutter-actor>
width
New width of actor in <clutter-unit>s, or -1
height
New height of actor in <clutter-unit>s, or -1

Since 0.6

— Function: clutter-actor-get-sizeu (self <clutter-actor>) (width <clutter-unit>) (height <clutter-unit>)
— Method: get-sizeu

This function tries to "do what you mean" and return the size an actor will have. If the actor has a valid allocation, the allocation will be returned; otherwise, the actors natural size request will be returned.
If you care whether you get the request vs. the allocation, you should probably call a different function like clutter-actor-get-allocation-coords or clutter-actor-get-preferred-width.

self
A <clutter-actor>
width
return location for the width, or ‘#f’
height
return location for the height, or ‘#f’

Since 0.6

— Function: clutter-actor-set-anchor-pointu (self <clutter-actor>) (anchor_x <clutter-unit>) (anchor_y <clutter-unit>)
— Method: set-anchor-pointu

Sets an anchor point for self. The anchor point is a point in the coordinate space of an actor to which the actor position within its parent is relative; the default is (0, 0), i.e. the top-left corner of the actor.

self
a <clutter-actor>
anchor-x
X coordinate of the anchor point, in <clutter-unit>s
anchor-y
Y coordinate of the anchor point, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-anchor-pointu (self <clutter-actor>) (anchor_x <clutter-unit>) (anchor_y <clutter-unit>)
— Method: get-anchor-pointu

Gets the current anchor point of the actor in <clutter-unit>s.

self
a <clutter-actor>
anchor-x
return location for the X coordinace of the anchor point
anchor-y
return location for the X coordinace of the anchor point

Since 0.6

— Function: clutter-actor-move-anchor-pointu (self <clutter-actor>) (anchor_x <clutter-unit>) (anchor_y <clutter-unit>)
— Method: move-anchor-pointu

Sets an anchor point for the actor, and adjusts the actor postion so that the relative position of the actor toward its parent remains the same.

self
a <clutter-actor>
anchor-x
X coordinate of the anchor point
anchor-y
Y coordinate of the anchor point

Since 0.6

— Function: clutter-actor-set-clipu (self <clutter-actor>) (xoff <clutter-unit>) (yoff <clutter-unit>) (width <clutter-unit>) (height <clutter-unit>)
— Method: set-clipu

Unit-based variant of clutter-actor-set-clip
Sets clip area for self. The clip area is always computed from the upper left corner of the actor, even if the anchor point is set otherwise.

self
A <clutter-actor>
xoff
X offset of the clip rectangle, in <clutter-unit>s
yoff
Y offset of the clip rectangle, in <clutter-unit>s
width
Width of the clip rectangle, in <clutter-unit>s
height
Height of the clip rectangle, in <clutter-unit>s

Since 0.6

— Function: clutter-actor-get-clipu (self <clutter-actor>) (xoff <clutter-unit>) (yoff <clutter-unit>) (width <clutter-unit>) (height <clutter-unit>)
— Method: get-clipu

Unit-based variant of clutter-actor-get-clip.
Gets the clip area for self, in <clutter-unit>s.

self
a <clutter-actor>
xoff
return location for the X offset of the clip rectangle, or ‘#f’
yoff
return location for the Y offset of the clip rectangle, or ‘#f’
width
return location for the width of the clip rectangle, or ‘#f’
height
return location for the height of the clip rectangle, or ‘#f’

Since 0.6

— Function: clutter-actor-set-rotationu (self <clutter-actor>) (axis <clutter-rotate-axis>) (angle double) (x <clutter-unit>) (y <clutter-unit>) (z <clutter-unit>)
— Method: set-rotationu

Sets the rotation angle of self around the given axis.
This function is the units based variant of clutter-actor-set-rotation.

self
a <clutter-actor>
axis
the axis of rotation
angle
the angle of rotation
x
X coordinate of the rotation center, in <clutter-unit>s
y
Y coordinate of the rotation center, in <clutter-unit>s
z
Z coordinate of the rotation center, in <clutter-unit>s

Since 0.8

— Function: clutter-actor-get-rotationu (self <clutter-actor>) (axis <clutter-rotate-axis>) (ret double) (x <clutter-unit>) (y <clutter-unit>) (z <clutter-unit>)
— Method: get-rotationu

Retrieves the angle and center of rotation on the given axis, set using clutter-actor-set-rotation.
This function is the units based variant of clutter-actor-get-rotation.

self
a <clutter-actor>
axis
the axis of rotation
x
return value for the X coordinate of the center of rotation, in <clutter-unit>s
y
return value for the Y coordinate of the center of rotation, in <clutter-unit>s
z
return value for the Z coordinate of the center of rotation, in <clutter-unit>s
ret
the angle of rotation

Since 0.8

— Function: clutter-actor-move-byu (self <clutter-actor>) (dx <clutter-unit>) (dy <clutter-unit>)
— Method: move-byu

Moves an actor by the specified distance relative to its current position.
The move is accomplished by setting a fixed position, overriding any layout manager, see clutter-actor-set-positionu.

self
A <clutter-actor>
dx
Distance to move Actor on X axis, in <clutter-unit>s.
dy
Distance to move Actor on Y axis, in <clutter-unit>s.

Since 0.6

— Function: clutter-actor-get-transformed-sizeu (self <clutter-actor>) (width <clutter-unit>) (height <clutter-unit>)
— Method: get-transformed-sizeu

Gets the absolute size of an actor in <clutter-units>s, taking into account the scaling factors.
When the actor (or one of its ancestors) is rotated around the X or Y axis, it no longer appears as on the stage as a rectangle, but as a generic quadrangle; in that case this function returns the size of the smallest rectangle that encapsulates the entire quad. Please note that in this case no assumptions can be made about the relative position of this envelope to the absolute position of the actor, as returned by clutter-actor-get-transformed-position; if you need this information, you need to use clutter-actor-get-abs-allocation-vertices to get the coords of the actual quadrangle.

self
A <clutter-actor>
width
return location for the width, or ‘#f’
height
return location for the height, or ‘#f’

Since 0.8

2 ClutterActor

2.1 Overview

2.2 Usage