Next: , Previous: ClutterActorMeta, Up: Top

4 ClutterActor

The basic element of the scene graph

4.1 Overview

The ClutterActor class is the basic element of the scene graph in Clutter, and it encapsulates the position, size, and transformations of a node in the graph.

4.2 Actor transformations

Each actor can be transformed using methods like clutter-actor-set-scale or clutter-actor-set-rotation. The order in which the transformations are applied is decided by Clutter and it is the following:

translation by the origin of the <"allocation">;

translation by the actor's <"depth">;

scaling by the <"scale-x"> and <"scale-y"> factors;

rotation around the <"rotation-z-angle"> and <"rotation-z-center">;

rotation around the <"rotation-y-angle"> and <"rotation-y-center">;

rotation around the <"rotation-x-angle"> and <"rotation-x-center">;

negative translation by the <"anchor-x"> and <"anchor-y"> point.

4.3 Modifying an actor's geometry

Each actor has a bounding box, called <"allocation"> which is either set by its parent or explicitly through the clutter-actor-set-position and clutter-actor-set-size methods. Each actor also has an implicit preferred size.

An actor’s preferred size can be defined by any subclass by overriding the clutter-actor-class.get-preferred-width and the clutter-actor-class.get-preferred-height virtual functions, or it can be explicitly set by using clutter-actor-set-width and clutter-actor-set-height.

An actor’s position can be set explicitly by using clutter-actor-set-x and clutter-actor-set-y; the coordinates are relative to the origin of the actor’s parent.

4.4 Managing actor children

Each actor can have multiple children, by calling clutter-actor-add-child to add a new child actor, and clutter-actor-remove-child to remove an existing child. <clutter-actor> will hold a reference on each child actor, which will be released when the child is removed from its parent, or destroyed using clutter-actor-destroy. 

     
      ClutterActor *actor = clutter_actor_new ();
     
      /&#x002A; set the bounding box of the actor &#x002A;/
      clutter_actor_set_position (actor, 0, 0);
      clutter_actor_set_size (actor, 480, 640);
     
      /&#x002A; set the background color of the actor &#x002A;/
      clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);
     
      /&#x002A; set the bounding box of the child, relative to the parent &#x002A;/
      ClutterActor *child = clutter_actor_new ();
      clutter_actor_set_position (child, 20, 20);
      clutter_actor_set_size (child, 80, 240);
     
      /&#x002A; set the background color of the child &#x002A;/
      clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);
     
      /&#x002A; add the child to the actor &#x002A;/
      clutter_actor_add_child (actor, child);

Children can be inserted at a given index, or above and below another child actor. The order of insertion determines the order of the children when iterating over them. Iterating over children is performed by using clutter-actor-get-first-child, clutter-actor-get-previous-sibling, clutter-actor-get-next-sibling, and clutter-actor-get-last-child. It is also possible to retrieve a list of children by using clutter-actor-get-children, as well as retrieving a specific child at a given index by using clutter-actor-get-child-at-index.

If you need to track additions of children to a <clutter-actor>, use the <"actor-added"> signal; similarly, to track removals of children from a ClutterActor, use the <"actor-removed"> signal.

4.5 Painting an actor

There are three ways to paint an actor:

set a delegate <clutter-content> as the value for the <"content"> property of the actor;

subclass <clutter-actor> and override the clutter-actor-class.paint-node virtual function;

subclass <clutter-actor> and override the clutter-actor-class.paint virtual function.

A <clutter-content> is a delegate object that takes over the painting operation of one, or more actors. The <clutter-content> painting will be performed on top of the <"background-color"> of the actor, and before calling the clutter-actor-class.paint-node virtual function. 

     
     ClutterActor *actor = clutter_actor_new ();
     
     /&#x002A; set the bounding box &#x002A;/
     clutter_actor_set_position (actor, 50, 50);
     clutter_actor_set_size (actor, 100, 100);
     
     /&#x002A; set the content; the image_content variable is set elsewhere &#x002A;/
     clutter_actor_set_content (actor, image_content);

The clutter-actor-class.paint-node virtual function is invoked whenever an actor needs to be painted. The implementation of the virtual function must only paint the contents of the actor itself, and not the contents of its children, if the actor has any.

The <clutter-paint-node> passed to the virtual function is the local root of the render tree; any node added to it will be rendered at the correct position, as defined by the actor's <"allocation">. 

     
     static void
     my_actor_paint_node (ClutterActor     *actor,
                          ClutterPaintNode *root)
     {
       ClutterPaintNode *node;
       ClutterActorBox box;
     
       /&#x002A; where the content of the actor should be painted &#x002A;/
       clutter_actor_get_allocation_box (actor, &box);
     
       /&#x002A; the cogl_texture variable is set elsewhere &#x002A;/
       node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
                                        CLUTTER_SCALING_FILTER_TRILINEAR,
                                        CLUTTER_SCALING_FILTER_LINEAR);
     
       /&#x002A; paint the content of the node using the allocation &#x002A;/
       clutter_paint_node_add_rectangle (node, &box);
     
       /&#x002A; add the node, and transfer ownership &#x002A;/
       clutter_paint_node_add_child (root, node);
       clutter_paint_node_unref (node);
     }

The clutter-actor-class.paint virtual function is invoked when the <"paint"> signal is emitted, and after the other signal handlers have been invoked. Overriding the paint virtual function gives total control to the paint sequence of the actor itself, including the children of the actor, if any.

It is strongly discouraged to override the clutter-actor-class.paint virtual function, as well as connecting to the <"paint"> signal. These hooks into the paint sequence are considered legacy, and will be removed when the Clutter API changes.

4.6 Handling events on an actor

A <clutter-actor> can receive and handle input device events, for instance pointer events and key events, as long as its <"reactive"> property is set to ‘#t’.

Once an actor has been determined to be the source of an event, Clutter will traverse the scene graph from the top-level actor towards the event source, emitting the <"captured-event"> signal on each ancestor until it reaches the source; this phase is also called the capture phase. If the event propagation was not stopped, the graph is walked backwards, from the source actor to the top-level, and the <"event"> signal, along with other event signals if needed, is emitted; this phase is also called the bubble phase. At any point of the signal emission, signal handlers can stop the propagation through the scene graph by returning ‘CLUTTER_EVENT_STOP’; otherwise, they can continue the propagation by returning ‘CLUTTER_EVENT_PROPAGATE’.

4.7 Animation

Animation is a core concept of modern user interfaces; Clutter provides a complete and powerful animation framework that automatically tweens the actor's state without requiring direct, frame by frame manipulation from your application code.

The implicit animation model of Clutter assumes that all the changes in an actor state should be gradual and asynchronous; Clutter will automatically transition an actor's property change between the current state and the desired one without manual intervention.

By default, in the 1.0 API series, the transition happens with a duration of zero milliseconds, and the implicit animation is an opt in feature to retain backwards compatibility. In order to enable implicit animations, it is necessary to change the easing state of an actor by using clutter-actor-save-easing-state: 

     
     /&#x002A; assume that the actor is currently positioned at (100, 100) &#x002A;/
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_position (actor, 500, 500);
     clutter_actor_restore_easing_state (actor);

The example above will trigger an implicit animation of the actor between its current position to a new position.

It is possible to animate multiple properties of an actor at the same time, and you can animate multiple actors at the same time as well, for instance: 

     
     /&#x002A; animate the actor's opacity and depth &#x002A;/
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_opacity (actor, 0);
     clutter_actor_set_depth (actor, -100);
     clutter_actor_restore_easing_state (actor);
     
     /&#x002A; animate another actor's opacity &#x002A;/
     clutter_actor_save_easing_state (another_actor);
     clutter_actor_set_opacity (another_actor, 255);
     clutter_actor_set_depth (another_actor, 100);
     clutter_actor_restore_easing_state (another_actor);

Implicit animations use a default duration of 250 milliseconds, and a default easing mode of ‘CLUTTER_EASE_OUT_CUBIC’, unless you call clutter-actor-set-easing-mode and clutter-actor-set-easing-duration after changing the easing state of the actor.

It is important to note that if you modify the state on an animatable property while a transition is in flight, the transition's final value will be updated, as well as its duration and progress mode by using the current easing state; for instance, in the following example: 

     
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_x (actor, 200);
     clutter_actor_restore_easing_state (actor);
     
     clutter_actor_save_easing_state (actor);
     clutter_actor_set_x (actor, 100);
     clutter_actor_restore_easing_state (actor);

the first call to clutter-actor-set-x will begin a transition of the <"x"> property to the value of 200; the second call to clutter-actor-set-x will change the transition's final value to 100.

It is possible to retrieve the <clutter-transition> used by the animatable properties by using clutter-actor-get-transition and using the property name as the transition name.

The explicit animation model supported by Clutter requires that you create a <clutter-transition> object, and set the initial and final values. The transition will not start unless you add it to the <clutter-actor>. 

     
     ClutterTransition *transition;
     
     transition = clutter_property_transition_new ("opacity");
     clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 3000);
     clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), 2);
     clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
     clutter_transition_set_interval (transition, clutter_interval_new (G_TYPE_UINT, 255, 0));
     
     clutter_actor_add_transition (actor, "animate-opacity", transition);

The example above will animate the <"opacity"> property of an actor between fully opaque and fully transparent, and back, over a span of 3 seconds. The animation does not begin until it is added to the actor.

The explicit animation API should also be used when using custom animatable properties for <clutter-action>, <clutter-constraint>, and <clutter-effect> instances associated to an actor; see the section on custom animatable properties below for an example.

Finally, explicit animations are useful for creating animations that run continuously, for instance: 

     
     /&#x002A; this animation will pulse the actor's opacity continuously &#x002A;/
     ClutterTransition *transition;
     ClutterInterval *interval;
     
     transition = clutter_property_transition_new ("opacity");
     
     /&#x002A; we want to animate the opacity between 0 and 255 &#x002A;/
     internal = clutter_interval_new (G_TYPE_UINT, 0, 255);
     clutter_transition_set_interval (transition, interval);
     
     /&#x002A; over a one second duration, running an infinite amount of times &#x002A;/
     clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
     clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);
     
     /&#x002A; we want to fade in and out, so we need to auto-reverse the transition &#x002A;/
     clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);
     
     /&#x002A; and we want to use an easing function that eases both in and out &#x002A;/
     clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                         CLUTTER_EASE_IN_OUT_CUBIC);
     
     /&#x002A; add the transition to the desired actor; this will
      &#x002A; start the animation.
      &#x002A;/
     clutter_actor_add_transition (actor, "opacityAnimation", transition);

4.8 Implementing an actor

Careful consideration should be given when deciding to implement a <clutter-actor> sub-class. It is generally recommended to implement a sub-class of <clutter-actor> only for actors that should be used as leaf nodes of a scene graph.

If your actor should be painted in a custom way, you should override the <"paint"> signal class handler. You can either opt to chain up to the parent class implementation or decide to fully override the default paint implementation; Clutter will set up the transformations and clip regions prior to emitting the <"paint"> signal.

By overriding the clutter-actor-class.get-preferred-width and clutter-actor-class.get-preferred-height virtual functions it is possible to change or provide the preferred size of an actor; similarly, by overriding the clutter-actor-class.allocate virtual function it is possible to control the layout of the children of an actor. Make sure to always chain up to the parent implementation of the clutter-actor-class.allocate virtual function.

In general, it is strongly encouraged to use delegation and composition instead of direct subclassing.

4.9 ClutterActor custom properties for <clutter-script>

<clutter-actor> defines a custom "rotation" property which allows a short-hand description of the rotations to be applied to an actor.

The syntax of the "rotation" property is the following: 

     
     "rotation" : [
       { "<axis>" : [ <angle>, [ <center> ] ] }
     ]

where the axis is the name of an enumeration value of type <clutter-rotate-axis> and angle is a floating point value representing the rotation angle on the given axis, in degrees.

The center array is optional, and if present it must contain the center of rotation as described by two coordinates: Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for "z-axis".

<clutter-actor> will also parse every positional and dimensional property defined as a string through clutter-units-from-string; you should read the documentation for the <clutter-units> parser format for the valid units and syntax.

4.10 Custom animatable properties

<clutter-actor> allows accessing properties of <clutter-action>, <clutter-effect>, and <clutter-constraint> instances associated to an actor instance for animation purposes.

In order to access a specific <clutter-action> or a <clutter-constraint> property it is necessary to set the <"name"> property on the given action or constraint.

The property can be accessed using the following syntax: 

     
     @<section>.<meta-name>.<property-name>

The initial @ is mandatory.

The section fragment can be one between "actions", "constraints" and "effects".

The meta-name fragment is the name of the action or constraint, as specified by the <"name"> property.

The property-name fragment is the name of the action or constraint property to be animated.

The example below animates a <clutter-bind-constraint> applied to an actor using clutter-actor-animate. The rect has a binding constraint for the origin actor, and in its initial state is overlapping the actor to which is bound to. 

     
     constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_X, 0.0);
     clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-x");
     clutter_actor_add_constraint (rect, constraint);
     
     constraint = clutter_bind_constraint_new (origin, CLUTTER_BIND_Y, 0.0);
     clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "bind-y");
     clutter_actor_add_constraint (rect, constraint);
     
     clutter_actor_set_reactive (origin, TRUE);
     
     g_signal_connect (origin, "button-press-event",
                       G_CALLBACK (on_button_press),
                       rect);

On button press, the rectangle "slides" from behind the actor to which is bound to, using the <"offset"> property to achieve the effect: 

     
     gboolean
     on_button_press (ClutterActor *origin,
                      ClutterEvent *event,
                      ClutterActor *rect)
     {
       ClutterTransition *transition;
       ClutterInterval *interval;
     
       /&#x002A; the offset that we want to apply; this will make the actor
        &#x002A; slide in from behind the origin and rest at the right of
        &#x002A; the origin, plus a padding value.
        &#x002A;/
       float new_offset = clutter_actor_get_width (origin) + h_padding;
     
       /&#x002A; the property we wish to animate; the "@constraints" section
        &#x002A; tells Clutter to check inside the constraints associated
        &#x002A; with the actor; the "bind-x" section is the name of the
        &#x002A; constraint; and the "offset" is the name of the property
        &#x002A; on the constraint.
        &#x002A;/
       const char *prop = "@constraints.bind-x.offset";
     
       /&#x002A; create a new transition for the given property &#x002A;/
       transition = clutter_property_transition_new (prop);
     
       /&#x002A; set the easing mode and duration &#x002A;/
       clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                           CLUTTER_EASE_OUT_CUBIC);
       clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);
     
       /&#x002A; create the interval with the initial and final values &#x002A;/
       interval = clutter_interval_new (G_TYPE_FLOAT, 0, new_offset);
       clutter_transition_set_interval (transition, interval);
     
       /&#x002A; add the transition to the actor; this causes the animation
        &#x002A; to start. the name "offsetAnimation" can be used to retrieve
        &#x002A; the transition later.
        &#x002A;/
       clutter_actor_add_transition (rect, "offsetAnimation", transition);
     
       /&#x002A; we handled the event &#x002A;/
       return CLUTTER_EVENT_STOP;
     }

4.11 Usage

— Function: clutter-actor-new ⇒  (ret <clutter-actor>)

Creates a new <clutter-actor>.

A newly created actor has a floating reference, which will be sunk when it is added to another actor.

ret
the newly created <clutter-actor>.

Since 1.10

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

Sets flags on self

This function will emit notifications for the changed properties

self
a <clutter-actor>
flags
the flags to set

Since 1.0

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

Unsets flags on self

This function will emit notifications for the changed properties

self
a <clutter-actor>
flags
the flags to unset

Since 1.0

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

Retrieves the flags set on self

self
a <clutter-actor>
ret
a bitwise or of <clutter-actor-flags> or 0

Since 1.0

— 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-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-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-realize (self <clutter-actor>)
— Method: realize

Realization informs the actor that it is attached to a stage. It can use this to allocate resources if it wanted to delay allocation until it would be rendered. However it is perfectly acceptable for an actor to create resources before being realized because Clutter only ever has a single rendering context so that actor is free to be moved from one stage to another.

This function does nothing if the actor is already realized.

Because a realized actor must have realized parent actors, calling clutter-actor-realize will also realize all parents of the actor.

This function does not realize child actors, except in the special case that realizing the stage, when the stage is visible, will suddenly map (and thus realize) the children of the stage.

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

Unrealization informs the actor that it may be being destroyed or moved to another stage. The actor may want to destroy any underlying graphics resources at this point. However it is perfectly acceptable for it to retain the resources until the actor is destroyed because Clutter only ever uses a single rendering context and all of the graphics resources are valid on any stage.

Because mapped actors must be realized, actors may not be unrealized if they are mapped. This function hides the actor to be sure it isn't mapped, an application-visible side effect that you may not be expecting.

This function should not be called by application code.

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.

This function is context-aware, and will either cause a regular paint or a pick paint.

This function will emit the <"paint"> signal or the <"pick"> signal, depending on the context.

This function does not paint the actor if the actor is set to 0, unless it is performing a pick paint.

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

Run the next stage of the paint sequence. This function should only be called within the implementation of the ‘run’ virtual of a <clutter-effect>. It will cause the run method of the next effect to be applied, or it will paint the actual actor if the current effect is the last effect in the chain.

self
A <clutter-actor>

Since 1.8

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

This function will not do anything if self is not visible, or if the actor is inside an invisible part of the scenegraph.

Also be aware that painting is a NOP for actors with an opacity of 0

When you are implementing a custom actor you must queue a redraw whenever some private state changes that will affect painting or picking of your actor.

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-should-pick-paint (self <clutter-actor>) ⇒  (ret bool)
— Method: should-pick-paint

Should be called inside the implementation of the <"pick"> virtual function in order to check whether the actor should paint itself in pick mode or not.

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-map (self <clutter-actor>)
— Method: map

Sets the ‘CLUTTER_ACTOR_MAPPED’ flag on the actor and possibly maps and realizes its children if they are visible. Does nothing if the actor is not visible.

Calling this function is strongly disencouraged: the default implementation of clutter-actor-class.map will map all the children of an actor when mapping its parent.

When overriding map, it is mandatory to chain up to the parent implementation.

self
A <clutter-actor>

Since 1.0

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

Unsets the ‘CLUTTER_ACTOR_MAPPED’ flag on the actor and possibly unmaps its children if they were mapped.

Calling this function is not encouraged: the default <clutter-actor> implementation of clutter-actor-class.unmap will also unmap any eventual children by default when their parent is unmapped.

When overriding clutter-actor-class.unmap, it is mandatory to chain up to the parent implementation.

It is important to note that the implementation of the clutter-actor-class.unmap virtual function may be called after the clutter-actor-class.destroy or the g-object-class.dispose implementation, but it is guaranteed to be called before the g-object-class.finalize implementation.

self
A <clutter-actor>

Since 1.0

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

Asks the actor's implementation whether it may contain overlapping primitives.

For example; Clutter may use this to determine whether the painting should be redirected to an offscreen buffer to correctly implement the opacity property.

Custom actors can override the default response by implementing the <clutter-actor>has-overlaps virtual function. See clutter-actor-set-offscreen-redirect for more information.

self
A <clutter-actor>
ret
‘#t’ if the actor may have overlapping primitives, and ‘#f’ otherwise

Since 1.8

— Function: clutter-actor-allocate (self <clutter-actor>) (box <clutter-actor-box>) (flags <clutter-allocation-flags>)
— 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 flags parameter describes additional information about the allocation, for instance 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
flags
flags that control the allocation

Since 0.8

— Function: clutter-actor-allocate-align-fill (self <clutter-actor>) (box <clutter-actor-box>) (x_align double) (y_align double) (x_fill bool) (y_fill bool) (flags <clutter-allocation-flags>)
— Method: allocate-align-fill

Allocates self by taking into consideration the available allocation area; an alignment factor on either axis; and whether the actor should fill the allocation on either axis.

The box should contain the available allocation width and height; if the x1 and y1 members of <clutter-actor-box> are not set to 0, the allocation will be offset by their value.

This function takes into consideration the geometry request specified by the <"request-mode"> property, and the text direction.

This function is useful for fluid layout managers, like <clutter-bin-layout> or <clutter-table-layout>

self
a <clutter-actor>
box
a <clutter-actor-box>, containing the available width and height
x-align
the horizontal alignment, between 0 and 1
y-align
the vertical alignment, between 0 and 1
x-fill
whether the actor should fill horizontally
y-fill
whether the actor should fill vertically
flags
allocation flags to be passed to clutter-actor-allocate

Since 1.4

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

Stores the allocation of self as defined by box.

This function can only be called from within the implementation of the clutter-actor-class.allocate virtual function.

The allocation should have been adjusted to take into account constraints, alignment, and margin properties. If you are implementing a <clutter-actor> subclass that provides its own layout management policy for its children instead of using a <clutter-layout-manager> delegate, you should not call this function on the children of self; instead, you should call clutter-actor-allocate, which will adjust the allocation box for you.

This function should only be used by subclasses of <clutter-actor> that wish to store their allocation but cannot chain up to the parent's implementation; the default implementation of the clutter-actor-class.allocate virtual function will call this function.

It is important to note that, while chaining up was the recommended behaviour for <clutter-actor> subclasses prior to the introduction of this function, it is recommended to call clutter-actor-set-allocation instead.

If the <clutter-actor> is using a <clutter-layout-manager> delegate object to handle the allocation of its children, this function will call the clutter-layout-manager-allocate function only if the ‘CLUTTER_DELEGATE_LAYOUT’ flag is set on flags, otherwise it is expected that the subclass will call clutter-layout-manager-allocate by itself. For instance, the following code: 

          
          static void
          my_actor_allocate (ClutterActor *actor,
                             const ClutterActorBox *allocation,
                             ClutterAllocationFlags flags)
          {
            ClutterActorBox new_alloc;
            ClutterAllocationFlags new_flags;
          
            adjust_allocation (allocation, &new_alloc);
          
            new_flags = flags | CLUTTER_DELEGATE_LAYOUT;
          
            /&#x002A; this will use the layout manager set on the actor &#x002A;/
            clutter_actor_set_allocation (actor, &new_alloc, new_flags);
          }

is equivalent to this: 

          
          static void
          my_actor_allocate (ClutterActor *actor,
                             const ClutterActorBox *allocation,
                             ClutterAllocationFlags flags)
          {
            ClutterLayoutManager *layout;
            ClutterActorBox new_alloc;
          
            adjust_allocation (allocation, &new_alloc);
          
            clutter_actor_set_allocation (actor, &new_alloc, flags);
          
            layout = clutter_actor_get_layout_manager (actor);
            clutter_layout_manager_allocate (layout,
                                             CLUTTER_CONTAINER (actor),
                                             &new_alloc,
                                             flags);
          }
self
a <clutter-actor>
box
a <clutter-actor-box>
flags
allocation flags

Since 1.10

— 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 float) (min_height_p float) (natural_width_p float) (natural_height_p float)
— 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 float) ⇒  (min_width_p float) (natural_width_p float)
— 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 float) ⇒  (min_height_p float) (natural_height_p float)
— 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-request-mode (self <clutter-actor>) (mode <clutter-request-mode>)
— Method: set-request-mode

Sets the geometry request mode of self.

The mode determines the order for invoking clutter-actor-get-preferred-width and clutter-actor-get-preferred-height

self
a <clutter-actor>
mode
the request mode

Since 1.2

— Function: clutter-actor-get-request-mode (self <clutter-actor>) ⇒  (ret <clutter-request-mode>)
— Method: get-request-mode

Retrieves the geometry request mode of self

self
a <clutter-actor>
ret
the request mode for the actor

Since 1.2

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

Checks if the actor has an up-to-date allocation assigned to it. This means that the actor should have an allocation: it's visible and has a parent. It also means that there is no outstanding relayout request in progress for the actor or its children (There might be other outstanding layout requests in progress that will cause the actor to get a new allocation when the stage is laid out, however).

If this function returns ‘#f’, then the actor will normally be allocated before it is next drawn on the screen.

self
a <clutter-actor>
ret
‘#t’ if the actor has an up-to-date allocation

Since 1.4

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

Sets the horizontal alignment policy of a <clutter-actor>, in case the actor received extra horizontal space.

See also the <"x-align"> property.

self
a <clutter-actor>
x-align
the horizontal alignment policy

Since 1.10

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

Retrieves the horizontal alignment policy set using clutter-actor-set-x-align.

self
a <clutter-actor>
ret
the horizontal alignment policy.

Since 1.10

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

Sets the vertical alignment policy of a <clutter-actor>, in case the actor received extra vertical space.

See also the <"y-align"> property.

self
a <clutter-actor>
y-align
the vertical alignment policy

Since 1.10

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

Retrieves the vertical alignment policy set using clutter-actor-set-y-align.

self
a <clutter-actor>
ret
the vertical alignment policy.

Since 1.10

— Function: clutter-margin-new ⇒  (ret <clutter-margin>)

Creates a new <clutter-margin>.

ret
a newly allocated <clutter-margin>. Use clutter-margin-free to free the resources associated with it when done.

Since 1.10

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

Sets all the components of the margin of a <clutter-actor>.

self
a <clutter-actor>
margin
a <clutter-margin>

Since 1.10

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

Retrieves all the components of the margin of a <clutter-actor>.

self
a <clutter-actor>
margin
return location for a <clutter-margin>.

Since 1.10

— Function: clutter-actor-set-margin-top (self <clutter-actor>) (margin float)
— Method: set-margin-top

Sets the margin from the top of a <clutter-actor>.

self
a <clutter-actor>
margin
the top margin

Since 1.10

— Function: clutter-actor-get-margin-top (self <clutter-actor>) ⇒  (ret float)
— Method: get-margin-top

Retrieves the top margin of a <clutter-actor>.

self
a <clutter-actor>
ret
the top margin

Since 1.10

— Function: clutter-actor-set-margin-right (self <clutter-actor>) (margin float)
— Method: set-margin-right

Sets the margin from the right of a <clutter-actor>.

self
a <clutter-actor>
margin
the right margin

Since 1.10

— Function: clutter-actor-get-margin-right (self <clutter-actor>) ⇒  (ret float)
— Method: get-margin-right

Retrieves the right margin of a <clutter-actor>.

self
a <clutter-actor>
ret
the right margin

Since 1.10

— Function: clutter-actor-set-margin-bottom (self <clutter-actor>) (margin float)
— Method: set-margin-bottom

Sets the margin from the bottom of a <clutter-actor>.

self
a <clutter-actor>
margin
the bottom margin

Since 1.10

— Function: clutter-actor-get-margin-bottom (self <clutter-actor>) ⇒  (ret float)
— Method: get-margin-bottom

Retrieves the bottom margin of a <clutter-actor>.

self
a <clutter-actor>
ret
the bottom margin

Since 1.10

— Function: clutter-actor-set-margin-left (self <clutter-actor>) (margin float)
— Method: set-margin-left

Sets the margin from the left of a <clutter-actor>.

self
a <clutter-actor>
margin
the left margin

Since 1.10

— Function: clutter-actor-get-margin-left (self <clutter-actor>) ⇒  (ret float)
— Method: get-margin-left

Retrieves the left margin of a <clutter-actor>.

self
a <clutter-actor>
ret
the left margin

Since 1.10

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

Sets the <clutter-layout-manager> delegate object that will be used to lay out the children of self.

The <clutter-actor> will take a reference on the passed manager which will be released either when the layout manager is removed, or when the actor is destroyed.

self
a <clutter-actor>
manager
a <clutter-layout-manager>, or ‘#f’ to unset it.

Since 1.10

— Function: clutter-actor-get-layout-manager (self <clutter-actor>) ⇒  (ret <clutter-layout-manager>)
— Method: get-layout-manager

Retrieves the <clutter-layout-manager> used by self.

self
a <clutter-actor>
ret
a pointer to the <clutter-layout-manager>, or ‘#f’.

Since 1.10

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

Sets the background color of a <clutter-actor>.

The background color will be used to cover the whole allocation of the actor. The default background color of an actor is transparent.

To check whether an actor has a background color, you can use the <"background-color-set"> actor property.

The <"background-color"> property is animatable.

self
a <clutter-actor>
color
a <clutter-color>, or ‘#f’ to unset a previously set color.

Since 1.10

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

Retrieves the color set using clutter-actor-set-background-color.

self
a <clutter-actor>
color
return location for a <clutter-color>.

Since 1.10

— Function: clutter-actor-set-size (self <clutter-actor>) (width float) (height float)
— 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 float) (height float)
— 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-box 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 float) (y float)
— 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 float) (y float)
— 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 float)
— Method: set-width

Forces a width on an actor, causing the actor's preferred width and height (if any) to be ignored.

If width is -1 the actor will use its preferred width request instead of overriding it, i.e. you can "unset" the width with -1.

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, or -1

Since 0.2

— Function: clutter-actor-get-width (self <clutter-actor>) ⇒  (ret float)
— 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-box 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 float)
— Method: set-height

Forces a height on an actor, causing the actor's preferred width and height (if any) to be ignored.

If height is -1 the actor will use its preferred height instead of overriding it, i.e. you can "unset" the height with -1.

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, or -1

Since 0.2

— Function: clutter-actor-get-height (self <clutter-actor>) ⇒  (ret float)
— 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-box 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 float)
— 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.

The <"x"> property is animatable.

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 float)
— 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 float)
— 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.

The <"y"> property is animatable.

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 float)
— 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 float) (dy float)
— 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-depth (self <clutter-actor>) (depth float)
— Method: set-depth

Sets the Z coordinate of self to depth.

The unit used by depth is dependant on the perspective setup. See also clutter-stage-set-perspective.

self
a <clutter-actor>
depth
Z co-ord
— Function: clutter-actor-get-depth (self <clutter-actor>) ⇒  (ret float)
— 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 relative to the scale center and the anchor point. The scale center is unchanged by this function and defaults to 0,0.

The <"scale-x"> and <"scale-y"> properties are animatable.

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-set-scale-full (self <clutter-actor>) (scale_x double) (scale_y double) (center_x float) (center_y float)
— Method: set-scale-full

Scales an actor with the given factors around the given center point. The center point is specified in pixels relative to the anchor point (usually the top left corner of the actor).

The <"scale-x"> and <"scale-y"> properties are animatable.

self
A <clutter-actor>
scale-x
double factor to scale actor by horizontally.
scale-y
double factor to scale actor by vertically.
center-x
X coordinate of the center of the scale.
center-y
Y coordinate of the center of the scale

Since 1.0

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

Retrieves an actors scale factors.

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

Since 0.2

— Function: clutter-actor-get-scale-center (self <clutter-actor>) ⇒  (center_x float) (center_y float)
— Method: get-scale-center

Retrieves the scale center coordinate in pixels relative to the top left corner of the actor. If the scale center was specified using a <clutter-gravity> this will calculate the pixel offset using the current size of the actor.

self
A <clutter-actor>
center-x
Location to store the X position of the scale center, or ‘#f’.
center-y
Location to store the Y position of the scale center, or ‘#f’.

Since 1.0

— Function: clutter-actor-get-scale-gravity (self <clutter-actor>) ⇒  (ret <clutter-gravity>)
— Method: get-scale-gravity

Retrieves the scale center as a compass direction. If the scale center was specified in pixels or units this will return ‘CLUTTER_GRAVITY_NONE’.

self
A <clutter-actor>
ret
the scale gravity

Since 1.0

— 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-set-rotation (self <clutter-actor>) (axis <clutter-rotate-axis>) (angle double) (x float) (y float) (z float)
— 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.8

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

Retrieves the angle and center of rotation on the given axis, set using clutter-actor-set-rotation.

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

— 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-anchor-point (self <clutter-actor>) (anchor_x float) (anchor_y float)
— Method: set-anchor-point

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
anchor-y
Y coordinate of the anchor point

Since 0.6

— Function: clutter-actor-get-anchor-point (self <clutter-actor>) ⇒  (anchor_x float) (anchor_y float)
— 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 float) (anchor_y float)
— 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-transform-stage-point (self <clutter-actor>) (x float) (y float) ⇒  (ret bool) (x_out float) (y_out float)
— 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.

This function can be computationally intensive.

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.
y
y screen coordinate of the point to unproject.
x-out
return location for the unprojected x coordinance.
y-out
return location for the unprojected y coordinance.
ret
‘#t’ if conversion was successful.

Since 0.6

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

Gets the absolute size of an actor in pixels, taking into account the scaling factors.

If the actor has a valid allocation, the allocated size will be used. If the actor has not a valid allocation then the preferred size will be transformed and returned.

If you want the transformed allocation, see clutter-actor-get-abs-allocation-vertices instead.

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

— 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-get-paint-visibility (self <clutter-actor>) ⇒  (ret bool)
— Method: get-paint-visibility

Retrieves the 'paint' visibility of an actor recursively checking for non visible parents.

This is by definition the same as ‘CLUTTER_ACTOR_IS_MAPPED’.

self
A <clutter-actor>
ret
‘#t’ if the actor is visibile and will be painted.

Since 0.8.4

— Function: clutter-actor-get-paint-box (self <clutter-actor>) (box <clutter-actor-box>) ⇒  (ret bool)
— Method: get-paint-box

Retrieves the paint volume of the passed <clutter-actor>, and transforms it into a 2D bounding box in stage coordinates.

This function is useful to determine the on screen area occupied by the actor. The box is only an approximation and may often be considerably larger due to the optimizations used to calculate the box. The box is never smaller though, so it can reliably be used for culling.

There are times when a 2D paint box can't be determined, e.g. because the actor isn't yet parented under a stage or because the actor is unable to determine a paint volume.

self
a <clutter-actor>
box
return location for a <clutter-actor-box>.
ret
‘#t’ if a 2D paint box could be determined, else ‘#f’.

Since 1.6

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

Sets the contents of a <clutter-actor>.

self
a <clutter-actor>
content
a <clutter-content>, or ‘#f’.

Since 1.10

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

Retrieves the contents of self.

self
a <clutter-actor>
ret
a pointer to the <clutter-content> instance, or ‘#f’ if none was set.

Since 1.10

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

Sets the gravity of the <clutter-content> used by self.

See the description of the <"content-gravity"> property for more information.

The <"content-gravity"> property is animatable.

self
a <clutter-actor>
gravity
the <clutter-content-gravity>

Since 1.10

— Function: clutter-actor-get-content-gravity (self <clutter-actor>) ⇒  (ret <clutter-content-gravity>)
— Method: get-content-gravity

Retrieves the content gravity as set using clutter-actor-get-content-gravity.

self
a <clutter-actor>
ret
the content gravity

Since 1.10

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

Retrieves the bounding box for the <clutter-content> of self.

The bounding box is relative to the actor's allocation.

If no <clutter-content> is set for self, or if self has not been allocated yet, then the result is undefined.

The content box is guaranteed to be, at most, as big as the allocation of the <clutter-actor>.

If the <clutter-content> used by the actor has a preferred size, then it is possible to modify the content box by using the <"content-gravity"> property.

self
a <clutter-actor>
box
the return location for the bounding box for the <clutter-content>.

Since 1.10

— Function: clutter-actor-set-clip (self <clutter-actor>) (xoff float) (yoff float) (width float) (height float)
— Method: 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
yoff
Y offset of the clip rectangle
width
Width of the clip rectangle
height
Height of the clip rectangle

Since 0.6

— 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 float) (yoff float) (width float) (height float)
— Method: get-clip

Gets the clip area for self, if any is set

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

The <"opacity"> property is animatable.

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-is-in-clone-paint (self <clutter-actor>) ⇒  (ret bool)
— Method: is-in-clone-paint

Checks whether self is being currently painted by a <clutter-clone>

This function is useful only inside the ::paint virtual function implementations or within handlers for the <"paint"> signal

This function should not be used by applications

self
a <clutter-actor>
ret
‘#t’ if the <clutter-actor> is currently being painted by a <clutter-clone>, and ‘#f’ otherwise

Since 1.0

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

Adds child to the children of self.

This function will acquire a reference on child that will only be released when calling clutter-actor-remove-child.

This function will take into consideration the <"depth"> of child, and will keep the list of children sorted.

This function will emit the <"actor-added"> signal on self.

self
a <clutter-actor>
child
a <clutter-actor>

Since 1.10

— Function: clutter-actor-insert-child-above (self <clutter-actor>) (child <clutter-actor>) (sibling <clutter-actor>)
— Method: insert-child-above

Inserts child into the list of children of self, above another child of self or, if sibling is ‘#f’, above all the children of self.

This function will acquire a reference on child that will only be released when calling clutter-actor-remove-child.

This function will not take into consideration the <"depth"> of child.

This function will emit the <"actor-added"> signal on self.

self
a <clutter-actor>
child
a <clutter-actor>
sibling
a child of self, or ‘#f’.

Since 1.10

— Function: clutter-actor-insert-child-at-index (self <clutter-actor>) (child <clutter-actor>) (index_ int)
— Method: insert-child-at-index

Inserts child into the list of children of self, using the given index. If index is greater than the number of children in self, or is less than 0, then the new child is added at the end.

This function will acquire a reference on child that will only be released when calling clutter-actor-remove-child.

This function will not take into consideration the <"depth"> of child.

This function will emit the <"actor-added"> signal on self.

self
a <clutter-actor>
child
a <clutter-actor>
index
the index

Since 1.10

— Function: clutter-actor-insert-child-below (self <clutter-actor>) (child <clutter-actor>) (sibling <clutter-actor>)
— Method: insert-child-below

Inserts child into the list of children of self, below another child of self or, if sibling is ‘#f’, below all the children of self.

This function will acquire a reference on child that will only be released when calling clutter-actor-remove-child.

This function will not take into consideration the <"depth"> of child.

This function will emit the <"actor-added"> signal on self.

self
a <clutter-actor>
child
a <clutter-actor>
sibling
a child of self, or ‘#f’.

Since 1.10

— Function: clutter-actor-replace-child (self <clutter-actor>) (old_child <clutter-actor>) (new_child <clutter-actor>)
— Method: replace-child

Replaces old-child with new-child in the list of children of self.

self
a <clutter-actor>
old-child
the child of self to replace
new-child
the <clutter-actor> to replace old-child

Since 1.10

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

Removes child from the children of self.

This function will release the reference added by clutter-actor-add-child, so if you want to keep using child you will have to acquire a referenced on it before calling this function.

This function will emit the <"actor-removed"> signal on self.

self
a <clutter-actor>
child
a <clutter-actor>

Since 1.10

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

Removes all children of self.

This function releases the reference added by inserting a child actor in the list of children of self.

If the reference count of a child drops to zero, the child will be destroyed. If you want to ensure the destruction of all the children of self, use clutter-actor-destroy-all-children.

self
a <clutter-actor>

Since 1.10

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

Destroys all children of self.

This function releases the reference added by inserting a child actor in the list of children of self, and ensures that the <"destroy"> signal is emitted on each child of the actor.

By default, <clutter-actor> will emit the <"destroy"> signal when its reference count drops to 0; the default handler of the <"destroy"> signal will destroy all the children of an actor. This function ensures that all children are destroyed, instead of just removed from self, unlike clutter-actor-remove-all-children which will merely release the reference and remove each child.

Unless you acquired an additional reference on each child of self prior to calling clutter-actor-remove-all-children and want to reuse the actors, you should use clutter-actor-destroy-all-children in order to make sure that children are destroyed and signal handlers are disconnected even in cases where circular references prevent this from automatically happening through reference counting alone.

self
a <clutter-actor>

Since 1.10

— Function: clutter-actor-get-first-child (self <clutter-actor>) ⇒  (ret <clutter-actor>)
— Method: get-first-child

Retrieves the first child of self.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

self
a <clutter-actor>
ret
a pointer to a <clutter-actor>, or ‘#f’.

Since 1.10

— Function: clutter-actor-get-next-sibling (self <clutter-actor>) ⇒  (ret <clutter-actor>)
— Method: get-next-sibling

Retrieves the sibling of self that comes after it in the list of children of self's parent.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

self
a <clutter-actor>
ret
a pointer to a <clutter-actor>, or ‘#f’.

Since 1.10

— Function: clutter-actor-get-previous-sibling (self <clutter-actor>) ⇒  (ret <clutter-actor>)
— Method: get-previous-sibling

Retrieves the sibling of self that comes before it in the list of children of self's parent.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

self
a <clutter-actor>
ret
a pointer to a <clutter-actor>, or ‘#f’.

Since 1.10

— Function: clutter-actor-get-last-child (self <clutter-actor>) ⇒  (ret <clutter-actor>)
— Method: get-last-child

Retrieves the last child of self.

The returned pointer is only valid until the scene graph changes; it is not safe to modify the list of children of self while iterating it.

self
a <clutter-actor>
ret
a pointer to a <clutter-actor>, or ‘#f’.

Since 1.10

— Function: clutter-actor-get-child-at-index (self <clutter-actor>) (index_ int) ⇒  (ret <clutter-actor>)
— Method: get-child-at-index

Retrieves the actor at the given index inside the list of children of self.

self
a <clutter-actor>
index
the position in the list of children
ret
a pointer to a <clutter-actor>, or ‘#f’.

Since 1.10

— Function: clutter-actor-get-children (self <clutter-actor>) ⇒  (ret glist-of)
— Method: get-children

Retrieves the list of children of self.

self
a <clutter-actor>
ret
A newly allocated <g-list> of <clutter-actor>s. Use g-list-free when done.

Since 1.10

— Function: clutter-actor-get-n-children (self <clutter-actor>) ⇒  (ret int)
— Method: get-n-children

Retrieves the number of children of self.

self
a <clutter-actor>
ret
the number of children of an actor

Since 1.10

— 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-set-child-at-index (self <clutter-actor>) (child <clutter-actor>) (index_ int)
— Method: set-child-at-index

Changes the index of child in the list of children of self.

This function is logically equivalent to removing child and calling clutter-actor-insert-child-at-index, but it will not emit signals or change state on child.

self
a <clutter-actor>
child
a <clutter-actor> child of self
index
the new index for child

Since 1.10

— Function: clutter-actor-contains (self <clutter-actor>) (descendant <clutter-actor>) ⇒  (ret bool)
— Method: contains

Determines if descendant is contained inside self (either as an immediate child, or as a deeper descendant). If self and descendant point to the same actor then it will also return ‘#t’.

self
A <clutter-actor>
descendant
A <clutter-actor>, possibly contained in self
ret
whether descendent is contained within self

Since 1.4

— 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-save-easing-state (self <clutter-actor>)
— Method: save-easing-state

Saves the current easing state for animatable properties, and creates a new state with the default values for easing mode and duration.

self
a <clutter-actor>

Since 1.10

— Function: clutter-actor-restore-easing-state (self <clutter-actor>)
— Method: restore-easing-state

Restores the easing state as it was prior to a call to clutter-actor-save-easing-state.

self
a <clutter-actor>

Since 1.10

— Function: clutter-actor-set-easing-duration (self <clutter-actor>) (msecs unsigned-int)
— Method: set-easing-duration

Sets the duration of the tweening for animatable properties of self for the current easing state.

self
a <clutter-actor>
msecs
the duration of the easing, or ‘#f’

Since 1.10

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

Retrieves the duration of the tweening for animatable properties of self for the current easing state.

self
a <clutter-actor>
ret
the duration of the tweening, in milliseconds

Since 1.10

— Function: clutter-actor-set-easing-mode (self <clutter-actor>) (mode <clutter-animation-mode>)
— Method: set-easing-mode

Sets the easing mode for the tweening of animatable properties of self.

self
a <clutter-actor>
mode
an easing mode, excluding ‘CLUTTER_CUSTOM_MODE’

Since 1.10

— Function: clutter-actor-get-easing-mode (self <clutter-actor>) ⇒  (ret <clutter-animation-mode>)
— Method: get-easing-mode

Retrieves the easing mode for the tweening of animatable properties of self for the current easing state.

self
a <clutter-actor>
ret
an easing mode

Since 1.10

— Function: clutter-actor-set-easing-delay (self <clutter-actor>) (msecs unsigned-int)
— Method: set-easing-delay

Sets the delay that should be applied before tweening animatable properties.

self
a <clutter-actor>
msecs
the delay before the start of the tweening, in milliseconds

Since 1.10

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

Retrieves the delay that should be applied when tweening animatable properties.

self
a <clutter-actor>
ret
a delay, in milliseconds

Since 1.10

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

Retrieves the <clutter-transition> of a <clutter-actor> by using the transition name.

Transitions created for animatable properties use the name of the property itself, for instance the code below: 

          
            clutter_actor_set_easing_duration (actor, 1000);
            clutter_actor_set_rotation (actor, CLUTTER_Y_AXIS, 360.0, x, y, z);
          
            transition = clutter_actor_get_transition (actor, "rotation-angle-y");
            g_signal_connect (transition, "completed",
                              G_CALLBACK (on_transition_complete),
                              actor);

will call the on-transition-complete callback when the transition is complete.

self
a <clutter-actor>
name
the name of the transition
ret
a <clutter-transition>, or ‘#f’ is none was found to match the passed name; the returned instance is owned by Clutter and it should not be freed.

Since 1.10

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

Adds a transition to the <clutter-actor>'s list of animations.

The name string is a per-actor unique identifier of the transition: only one <clutter-transition> can be associated to the specified name.

The transition will be given the easing duration, mode, and delay associated to the actor's current easing state; it is possible to modify these values after calling clutter-actor-add-transition.

The transition will be started once added.

This function will take a reference on the transition.

This function is usually called implicitly when modifying an animatable property.

self
a <clutter-actor>
name
the name of the transition to add
transition
the <clutter-transition> to add

Since 1.10

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

Removes the transition stored inside a <clutter-actor> using name identifier.

If the transition is currently in progress, it will be stopped.

This function releases the reference acquired when the transition was added to the <clutter-actor>.

self
a <clutter-actor>
name
the name of the transition to remove

Since 1.10

— 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-has-key-focus (self <clutter-actor>) ⇒  (ret bool)
— Method: has-key-focus

Checks whether self is the <clutter-actor> that has key focus

self
a <clutter-actor>
ret
‘#t’ if the actor has key focus, and ‘#f’ otherwise

Since 1.4

— Function: clutter-actor-grab-key-focus (self <clutter-actor>)
— Method: grab-key-focus

Sets the key focus of the <clutter-stage> including self to this <clutter-actor>.

self
a <clutter-actor>

Since 1.0

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

Checks whether an actor contains the pointer of a <clutter-input-device>

self
a <clutter-actor>
ret
‘#t’ if the actor contains the pointer, and ‘#f’ otherwise

Since 1.2

— Function: clutter-actor-get-pango-context (self <clutter-actor>) ⇒  (ret <pango-context>)
— Method: get-pango-context

Retrieves the <pango-context> for self. The actor's <pango-context> is already configured using the appropriate font map, resolution and font options.

Unlike clutter-actor-create-pango-context, this context is owend by the <clutter-actor> and it will be updated each time the options stored by the <clutter-backend> change.

You can use the returned <pango-context> to create a <pango-layout> and render text using cogl-pango-render-layout to reuse the glyphs cache also used by Clutter.

self
a <clutter-actor>
ret
the <pango-context> for a <clutter-actor>. The returned <pango-context> is owned by the actor and should not be unreferenced by the application code.

Since 1.0

— Function: clutter-actor-create-pango-context (self <clutter-actor>) ⇒  (ret <pango-context>)
— Method: create-pango-context

Creates a <pango-context> for the given actor. The <pango-context> is already configured using the appropriate font map, resolution and font options.

See also clutter-actor-get-pango-context.

self
a <clutter-actor>
ret
the newly created <pango-context>. Use g-object-unref on the returned value to deallocate its resources.

Since 1.0

— Function: clutter-actor-create-pango-layout (self <clutter-actor>) (text mchars) ⇒  (ret <pango-layout>)
— Method: create-pango-layout

Creates a new <pango-layout> from the same <pango-context> used by the <clutter-actor>. The <pango-layout> is already configured with the font map, resolution and font options, and the given text.

If you want to keep around a <pango-layout> created by this function you will have to connect to the <"font-changed"> and <"resolution-changed"> signals, and call pango-layout-context-changed in response to them.

self
a <clutter-actor>
text
(allow-none) the text to set on the <pango-layout>, or ‘#f’
ret
the newly created <pango-layout>. Use g-object-unref when done.

Since 1.0

— Function: clutter-actor-set-text-direction (self <clutter-actor>) (text_dir <clutter-text-direction>)
— Method: set-text-direction

Sets the <clutter-text-direction> for an actor

The passed text direction must not be ‘CLUTTER_TEXT_DIRECTION_DEFAULT’

If self implements <clutter-container> then this function will recurse inside all the children of self (including the internal ones).

Composite actors not implementing <clutter-container>, or actors requiring special handling when the text direction changes, should connect to the <"notify"> signal for the <"text-direction"> property

self
a <clutter-actor>
text-dir
the text direction for self

Since 1.2

— Function: clutter-actor-get-text-direction (self <clutter-actor>) ⇒  (ret <clutter-text-direction>)
— Method: get-text-direction

Retrieves the value set using clutter-actor-set-text-direction

If no text direction has been previously set, the default text direction, as returned by clutter-get-default-text-direction, will be returned instead

self
a <clutter-actor>
ret
the <clutter-text-direction> for the actor

Since 1.2

— Function: clutter-actor-get-accessible (self <clutter-actor>) ⇒  (ret <atk-object>)
— Method: get-accessible

Returns the accessible object that describes the actor to an assistive technology.

If no class-specific <atk-object> implementation is available for the actor instance in question, it will inherit an <atk-object> implementation from the first ancestor class for which such an implementation is defined.

The documentation of the ATK library contains more information about accessible objects and their uses.

self
a <clutter-actor>
ret
the <atk-object> associated with actor.
— Function: clutter-actor-add-action (self <clutter-actor>) (action <clutter-action>)
— Method: add-action

Adds action to the list of actions applied to self

A <clutter-action> can only belong to one actor at a time

The <clutter-actor> will hold a reference on action until either clutter-actor-remove-action or clutter-actor-clear-actions is called

self
a <clutter-actor>
action
a <clutter-action>

Since 1.4

— Function: clutter-actor-add-action-with-name (self <clutter-actor>) (name mchars) (action <clutter-action>)
— Method: add-action-with-name

A convenience function for setting the name of a <clutter-action> while adding it to the list of actions applied to self

This function is the logical equivalent of: 

          
            clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
            clutter_actor_add_action (self, action);
self
a <clutter-actor>
name
the name to set on the action
action
a <clutter-action>

Since 1.4

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

Removes action from the list of actions applied to self

The reference held by self on the <clutter-action> will be released

self
a <clutter-actor>
action
a <clutter-action>

Since 1.4

— Function: clutter-actor-remove-action-by-name (self <clutter-actor>) (name mchars)
— Method: remove-action-by-name

Removes the <clutter-action> with the given name from the list of actions applied to self

self
a <clutter-actor>
name
the name of the action to remove

Since 1.4

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

Returns whether the actor has any actions applied.

self
A <clutter-actor>
ret
‘#t’ if the actor has any actions, ‘#f’ otherwise

Since 1.10

— Function: clutter-actor-get-actions (self <clutter-actor>) ⇒  (ret glist-of)
— Method: get-actions

Retrieves the list of actions applied to self

self
a <clutter-actor>
ret
a copy of the list of <clutter-action>s. The contents of the list are owned by the <clutter-actor>. Use g-list-free to free the resources allocated by the returned <g-list>.

Since 1.4

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

Retrieves the <clutter-action> with the given name in the list of actions applied to self

self
a <clutter-actor>
name
the name of the action to retrieve
ret
a <clutter-action> for the given name, or ‘#f’. The returned <clutter-action> is owned by the actor and it should not be unreferenced directly.

Since 1.4

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

Clears the list of actions applied to self

self
a <clutter-actor>

Since 1.4

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

Adds constraint to the list of <clutter-constraint>s applied to self

The <clutter-actor> will hold a reference on the constraint until either clutter-actor-remove-constraint or clutter-actor-clear-constraints is called.

self
a <clutter-actor>
constraint
a <clutter-constraint>

Since 1.4

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

Removes constraint from the list of constraints applied to self

The reference held by self on the <clutter-constraint> will be released

self
a <clutter-actor>
constraint
a <clutter-constraint>

Since 1.4

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

Returns whether the actor has any constraints applied.

self
A <clutter-actor>
ret
‘#t’ if the actor has any constraints, ‘#f’ otherwise

Since 1.10

— Function: clutter-actor-get-constraints (self <clutter-actor>) ⇒  (ret glist-of)
— Method: get-constraints

Retrieves the list of constraints applied to self

self
a <clutter-actor>
ret
a copy of the list of <clutter-constraint>s. The contents of the list are owned by the <clutter-actor>. Use g-list-free to free the resources allocated by the returned <g-list>.

Since 1.4

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

Retrieves the <clutter-constraint> with the given name in the list of constraints applied to self

self
a <clutter-actor>
name
the name of the constraint to retrieve
ret
a <clutter-constraint> for the given name, or ‘#f’. The returned <clutter-constraint> is owned by the actor and it should not be unreferenced directly.

Since 1.4

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

Clears the list of constraints applied to self

self
a <clutter-actor>

Since 1.4

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

Adds effect to the list of <clutter-effect>s applied to self

The <clutter-actor> will hold a reference on the effect until either clutter-actor-remove-effect or clutter-actor-clear-effects is called.

self
a <clutter-actor>
effect
a <clutter-effect>

Since 1.4

— Function: clutter-actor-add-effect-with-name (self <clutter-actor>) (name mchars) (effect <clutter-effect>)
— Method: add-effect-with-name

A convenience function for setting the name of a <clutter-effect> while adding it to the list of effectss applied to self

This function is the logical equivalent of: 

          
            clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
            clutter_actor_add_effect (self, effect);
self
a <clutter-actor>
name
the name to set on the effect
effect
a <clutter-effect>

Since 1.4

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

Removes effect from the list of effects applied to self

The reference held by self on the <clutter-effect> will be released

self
a <clutter-actor>
effect
a <clutter-effect>

Since 1.4

— Function: clutter-actor-remove-effect-by-name (self <clutter-actor>) (name mchars)
— Method: remove-effect-by-name

Removes the <clutter-effect> with the given name from the list of effects applied to self

self
a <clutter-actor>
name
the name of the effect to remove

Since 1.4

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

Returns whether the actor has any effects applied.

self
A <clutter-actor>
ret
‘#t’ if the actor has any effects, ‘#f’ otherwise

Since 1.10

— Function: clutter-actor-get-effects (self <clutter-actor>) ⇒  (ret glist-of)
— Method: get-effects

Retrieves the <clutter-effect>s applied on self, if any

self
a <clutter-actor>
ret
a list of <clutter-effect>s, or ‘#f’. The elements of the returned list are owned by Clutter and they should not be freed. You should free the returned list using g-list-free when done.

Since 1.4

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

Retrieves the <clutter-effect> with the given name in the list of effects applied to self

self
a <clutter-actor>
name
the name of the effect to retrieve
ret
a <clutter-effect> for the given name, or ‘#f’. The returned <clutter-effect> is owned by the actor and it should not be unreferenced directly.

Since 1.4

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

Clears the list of effects applied to self

self
a <clutter-actor>

Since 1.4

— Function: clutter-actor-box-new (x_1 float) (y_1 float) (x_2 float) (y_2 float) ⇒  (ret <clutter-actor-box>)

Allocates a new <clutter-actor-box> using the passed coordinates for the top left and bottom right points

x-1
X coordinate of the top left point
y-1
Y coordinate of the top left point
x-2
X coordinate of the bottom right point
y-2
Y coordinate of the bottom right point
ret
the newly allocated <clutter-actor-box>. Use clutter-actor-box-free to free the resources

Since 1.0

— Function: clutter-actor-box-init (self <clutter-actor-box>) (x_1 float) (y_1 float) (x_2 float) (y_2 float)

Initializes box with the given coordinates.

box
a <clutter-actor-box>
x-1
X coordinate of the top left point
y-1
Y coordinate of the top left point
x-2
X coordinate of the bottom right point
y-2
Y coordinate of the bottom right point

Since 1.10

— Function: clutter-actor-box-init-rect (self <clutter-actor-box>) (x float) (y float) (width float) (height float)

Initializes box with the given origin and size.

box
a <clutter-actor-box>
x
X coordinate of the origin
y
Y coordinate of the origin
width
width of the box
height
height of the box

Since 1.10

— Function: clutter-actor-box-equal (self <clutter-actor-box>) (box_b <clutter-actor-box>) ⇒  (ret bool)

Checks box-a and box-b for equality

box-a
a <clutter-actor-box>
box-b
a <clutter-actor-box>
ret
‘#t’ if the passed <clutter-actor-box> are equal

Since 1.0

— Function: clutter-actor-box-get-x (self <clutter-actor-box>) ⇒  (ret float)

Retrieves the X coordinate of the origin of box

box
a <clutter-actor-box>
ret
the X coordinate of the origin

Since 1.0

— Function: clutter-actor-box-get-y (self <clutter-actor-box>) ⇒  (ret float)

Retrieves the Y coordinate of the origin of box

box
a <clutter-actor-box>
ret
the Y coordinate of the origin

Since 1.0

— Function: clutter-actor-box-get-width (self <clutter-actor-box>) ⇒  (ret float)

Retrieves the width of the box

box
a <clutter-actor-box>
ret
the width of the box

Since 1.0

— Function: clutter-actor-box-get-height (self <clutter-actor-box>) ⇒  (ret float)

Retrieves the height of the box

box
a <clutter-actor-box>
ret
the height of the box

Since 1.0

— Function: clutter-actor-box-set-origin (self <clutter-actor-box>) (x float) (y float)

Changes the origin of box, maintaining the size of the <clutter-actor-box>.

box
a <clutter-actor-box>
x
the X coordinate of the new origin
y
the Y coordinate of the new origin

Since 1.6

— Function: clutter-actor-box-get-origin (self <clutter-actor-box>) ⇒  (x float) (y float)

Retrieves the origin of box

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

Since 1.0

— Function: clutter-actor-box-set-size (self <clutter-actor-box>) (width float) (height float)

Sets the size of box, maintaining the origin of the <clutter-actor-box>.

box
a <clutter-actor-box>
width
the new width
height
the new height

Since 1.6

— Function: clutter-actor-box-get-size (self <clutter-actor-box>) ⇒  (width float) (height float)

Retrieves the size of box

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

Since 1.0

— Function: clutter-actor-box-get-area (self <clutter-actor-box>) ⇒  (ret float)

Retrieves the area of box

box
a <clutter-actor-box>
ret
the area of a <clutter-actor-box>, in pixels

Since 1.0

— Function: clutter-actor-box-contains (self <clutter-actor-box>) (x float) (y float) ⇒  (ret bool)

Checks whether a point with x, y coordinates is contained withing box

box
a <clutter-actor-box>
x
X coordinate of the point
y
Y coordinate of the point
ret
‘#t’ if the point is contained by the <clutter-actor-box>

Since 1.0

— Function: clutter-actor-box-clamp-to-pixel (self <clutter-actor-box>)

Clamps the components of box to the nearest integer

box
the <clutter-actor-box> to clamp.

Since 1.2

— Function: clutter-actor-box-interpolate (self <clutter-actor-box>) (final <clutter-actor-box>) (progress double) (result <clutter-actor-box>)

Interpolates between initial and final<clutter-actor-box>es using progress

initial
the initial <clutter-actor-box>
final
the final <clutter-actor-box>
progress
the interpolation progress
result
return location for the interpolation.

Since 1.2

— Function: clutter-actor-box-union (self <clutter-actor-box>) (b <clutter-actor-box>) (result <clutter-actor-box>)

Unions the two boxes a and b and stores the result in result.

a
(in) the first <clutter-actor-box>
b
the second <clutter-actor-box>.
result
the <clutter-actor-box> representing a union of a and b.

Since 1.4

— Function: clutter-vertex-new (x float) (y float) (z float) ⇒  (ret <clutter-vertex>)

Creates a new <clutter-vertex> for the point in 3D space identified by the 3 coordinates x, y, z

x
X coordinate
y
Y coordinate
z
Z coordinate
ret
the newly allocate <clutter-vertex>. Use clutter-vertex-free to free the resources

Since 1.0

— Function: clutter-vertex-init (self <clutter-vertex>) (x float) (y float) (z float)

Initializes vertex with the given coordinates.

vertex
a <clutter-vertex>
x
X coordinate
y
Y coordinate
z
Z coordinate

Since 1.10

— Function: clutter-vertex-equal (self <clutter-vertex>) (vertex_b <clutter-vertex>) ⇒  (ret bool)

Compares vertex-a and vertex-b for equality

vertex-a
a <clutter-vertex>
vertex-b
a <clutter-vertex>
ret
‘#t’ if the passed <clutter-vertex> are equal

Since 1.0

— Function: clutter-geometry-union (self <clutter-geometry>) (geometry_b <clutter-geometry>) (result <clutter-geometry>)

Find the union of two rectangles represented as <clutter-geometry>.

geometry-a
a <clutter-geometry>
geometry-b
another <clutter-geometry>
result
location to store the result.

Since 1.4

— Function: clutter-geometry-intersects (self <clutter-geometry>) (geometry1 <clutter-geometry>) ⇒  (ret bool)

Determines if geometry0 and geometry1 intersect returning ‘#t’ if they do else ‘#f’.

geometry0
The first geometry to test
geometry1
The second geometry to test
ret
‘#t’ of geometry0 and geometry1 intersect else ‘#f’.

Since 1.4

— Function: clutter-paint-volume-set-origin (self <clutter-paint-volume>) (origin <clutter-vertex>)

Sets the origin of the paint volume.

The origin is defined as the X, Y and Z coordinates of the top-left corner of an actor's paint volume, in actor coordinates.

The default is origin is assumed at: (0, 0, 0)

pv
a <clutter-paint-volume>
origin
a <clutter-vertex>

Since 1.6

— Function: clutter-paint-volume-get-origin (self <clutter-paint-volume>) (vertex <clutter-vertex>)

Retrieves the origin of the <clutter-paint-volume>.

pv
a <clutter-paint-volume>
vertex
the return location for a <clutter-vertex>.

Since 1.6

— Function: clutter-paint-volume-set-width (self <clutter-paint-volume>) (width float)

Sets the width of the paint volume. The width is measured along the x axis in the actor coordinates that pv is associated with.

pv
a <clutter-paint-volume>
width
the width of the paint volume, in pixels

Since 1.6

— Function: clutter-paint-volume-get-width (self <clutter-paint-volume>) ⇒  (ret float)

Retrieves the width of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the x-axis.

If, for example, clutter-actor-get-transformed-paint-volume is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the width might not simply be 100px if the child actor has a 3D rotation applied to it.

Remember; after clutter-actor-get-transformed-paint-volume is used then a transformed child volume will be defined relative to the ancestor container actor and so a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported width, except that it must always be >= to the true width. This is because actors may report simple, loose fitting paint-volumes for efficiency

pv
a <clutter-paint-volume>
ret
the width, in units of pv's local coordinate system.

Since 1.6

— Function: clutter-paint-volume-set-height (self <clutter-paint-volume>) (height float)

Sets the height of the paint volume. The height is measured along the y axis in the actor coordinates that pv is associated with.

pv
a <clutter-paint-volume>
height
the height of the paint volume, in pixels

Since 1.6

— Function: clutter-paint-volume-get-height (self <clutter-paint-volume>) ⇒  (ret float)

Retrieves the height of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the y-axis.

If, for example, clutter-actor-get-transformed-paint-volume is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the height might not simply be 100px if the child actor has a 3D rotation applied to it.

Remember; after clutter-actor-get-transformed-paint-volume is used then a transformed child volume will be defined relative to the ancestor container actor and so a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported height, except that it must always be >= to the true height. This is because actors may report simple, loose fitting paint-volumes for efficiency

pv
a <clutter-paint-volume>
ret
the height, in units of pv's local coordinate system.

Since 1.6

— Function: clutter-paint-volume-set-depth (self <clutter-paint-volume>) (depth float)

Sets the depth of the paint volume. The depth is measured along the z axis in the actor coordinates that pv is associated with.

pv
a <clutter-paint-volume>
depth
the depth of the paint volume, in pixels

Since 1.6

— Function: clutter-paint-volume-get-depth (self <clutter-paint-volume>) ⇒  (ret float)

Retrieves the depth of the volume's, axis aligned, bounding box.

In other words; this takes into account what actor's coordinate space pv belongs too and conceptually fits an axis aligned box around the volume. It returns the size of that bounding box as measured along the z-axis.

If, for example, clutter-actor-get-transformed-paint-volume is used to transform a 2D child actor that is 100px wide, 100px high and 0px deep into container coordinates then the depth might not simply be 0px if the child actor has a 3D rotation applied to it.

Remember; after clutter-actor-get-transformed-paint-volume is used then the transformed volume will be defined relative to the container actor and in container coordinates a 2D child actor can have a 3D bounding volume.

There are no accuracy guarantees for the reported depth, except that it must always be >= to the true depth. This is because actors may report simple, loose fitting paint-volumes for efficiency.

pv
a <clutter-paint-volume>
ret
the depth, in units of pv's local coordinate system.

Since 1.6

— Function: clutter-paint-volume-union (self <clutter-paint-volume>) (another_pv <clutter-paint-volume>)

Updates the geometry of pv to encompass pv and another-pv.

There are no guarantees about how precisely the two volumes will be encompassed.

pv
The first <clutter-paint-volume> and destination for resulting union
another-pv
A second <clutter-paint-volume> to union with pv

Since 1.6

— Function: clutter-paint-volume-union-box (self <clutter-paint-volume>) (box <clutter-actor-box>)

Unions the 2D region represented by box to a <clutter-paint-volume>.

This function is similar to clutter-paint-volume-union, but it is specific for 2D regions.

pv
a <clutter-paint-volume>
box
a <clutter-actor-box> to union to pv

Since 1.10