## ClutterActor

ClutterActor — The basic element of the scene graph

## Functions

#define | CLUTTER_ACTOR_SET_FLAGS ()
#define | CLUTTER_ACTOR_UNSET_FLAGS ()
#define | CLUTTER_ACTOR_IS_MAPPED ()
#define | CLUTTER_ACTOR_IS_REALIZED ()
#define | CLUTTER_ACTOR_IS_VISIBLE ()
#define | CLUTTER_ACTOR_IS_REACTIVE ()
#define | CLUTTER_CALLBACK ()
void | ( *ClutterCallback ) ()
ClutterActor * | clutter_actor_new ()
void | clutter_actor_set_flags ()
void | clutter_actor_unset_flags ()
ClutterActorFlags | clutter_actor_get_flags ()
void | clutter_actor_set_name ()
const gchar * | clutter_actor_get_name ()
guint32 | clutter_actor_get_gid ()
void | clutter_actor_show ()
void | clutter_actor_show_all ()
void | clutter_actor_hide ()
void | clutter_actor_hide_all ()
gboolean | clutter_actor_is_visible ()
void | clutter_actor_realize ()
void | clutter_actor_unrealize ()
gboolean | clutter_actor_is_realized ()
void | clutter_actor_paint ()
void | clutter_actor_continue_paint ()
void | clutter_actor_queue_redraw ()
void | clutter_actor_queue_redraw_with_clip ()
void | clutter_actor_queue_relayout ()
void | clutter_actor_destroy ()
gboolean | clutter_actor_event ()
gboolean | clutter_actor_should_pick_paint ()
void | clutter_actor_map ()
void | clutter_actor_unmap ()
gboolean | clutter_actor_is_mapped ()
gboolean | clutter_actor_has_overlaps ()
gboolean | clutter_actor_has_mapped_clones ()
void | clutter_actor_allocate ()
void | clutter_actor_allocate_preferred_size ()
void | clutter_actor_allocate_available_size ()
void | clutter_actor_allocate_align_fill ()
void | clutter_actor_set_allocation ()
void | clutter_actor_get_allocation_box ()
void | clutter_actor_get_allocation_geometry ()
void | clutter_actor_get_allocation_vertices ()
void | clutter_actor_get_preferred_size ()
void | clutter_actor_get_preferred_width ()
void | clutter_actor_get_preferred_height ()
void | clutter_actor_set_fixed_position_set ()
gboolean | clutter_actor_get_fixed_position_set ()
void | clutter_actor_set_request_mode ()
ClutterRequestMode | clutter_actor_get_request_mode ()
gboolean | clutter_actor_has_allocation ()
void | clutter_actor_set_x_align ()
ClutterActorAlign | clutter_actor_get_x_align ()
void | clutter_actor_set_y_align ()
ClutterActorAlign | clutter_actor_get_y_align ()
ClutterMargin * | clutter_margin_copy ()
void | clutter_margin_free ()
ClutterMargin * | clutter_margin_new ()
void | clutter_actor_set_margin ()
void | clutter_actor_get_margin ()
void | clutter_actor_set_margin_top ()
gfloat | clutter_actor_get_margin_top ()
void | clutter_actor_set_margin_right ()
gfloat | clutter_actor_get_margin_right ()
void | clutter_actor_set_margin_bottom ()
gfloat | clutter_actor_get_margin_bottom ()
void | clutter_actor_set_margin_left ()
gfloat | clutter_actor_get_margin_left ()
void | clutter_actor_set_x_expand ()
gboolean | clutter_actor_get_x_expand ()
void | clutter_actor_set_y_expand ()
gboolean | clutter_actor_get_y_expand ()
gboolean | clutter_actor_needs_expand ()
void | clutter_actor_set_layout_manager ()
ClutterLayoutManager * | clutter_actor_get_layout_manager ()
void | clutter_actor_set_background_color ()
void | clutter_actor_get_background_color ()
void | clutter_actor_set_geometry ()
void | clutter_actor_get_geometry ()
void | clutter_actor_set_size ()
void | clutter_actor_get_size ()
void | clutter_actor_set_position ()
void | clutter_actor_get_position ()
void | clutter_actor_set_width ()
gfloat | clutter_actor_get_width ()
void | clutter_actor_set_height ()
gfloat | clutter_actor_get_height ()
void | clutter_actor_set_x ()
gfloat | clutter_actor_get_x ()
void | clutter_actor_set_y ()
gfloat | clutter_actor_get_y ()
void | clutter_actor_move_by ()
void | clutter_actor_set_z_position ()
gfloat | clutter_actor_get_z_position ()
void | clutter_actor_set_pivot_point ()
void | clutter_actor_get_pivot_point ()
void | clutter_actor_set_pivot_point_z ()
gfloat | clutter_actor_get_pivot_point_z ()
void | clutter_actor_set_scale ()
void | clutter_actor_get_scale ()
void | clutter_actor_set_scale_z ()
gdouble | clutter_actor_get_scale_z ()
gboolean | clutter_actor_is_scaled ()
void | clutter_actor_set_rotation_angle ()
gdouble | clutter_actor_get_rotation_angle ()
gboolean | clutter_actor_is_rotated ()
void | clutter_actor_set_translation ()
void | clutter_actor_get_translation ()
void | clutter_actor_set_transform ()
void | clutter_actor_get_transform ()
void | clutter_actor_set_child_transform ()
void | clutter_actor_get_child_transform ()
void | clutter_actor_apply_transform_to_point ()
gboolean | clutter_actor_transform_stage_point ()
void | clutter_actor_apply_relative_transform_to_point ()
void | clutter_actor_get_transformed_position ()
void | clutter_actor_get_transformed_size ()
guint8 | clutter_actor_get_paint_opacity ()
gboolean | clutter_actor_get_paint_visibility ()
void | clutter_actor_get_abs_allocation_vertices ()
const ClutterPaintVolume * | clutter_actor_get_paint_volume ()
gboolean | clutter_actor_get_paint_box ()
const ClutterPaintVolume * | clutter_actor_get_transformed_paint_volume ()
const ClutterPaintVolume * | clutter_actor_get_default_paint_volume ()
void | clutter_actor_set_content ()
ClutterContent * | clutter_actor_get_content ()
void | clutter_actor_set_content_gravity ()
ClutterContentGravity | clutter_actor_get_content_gravity ()
void | clutter_actor_set_content_scaling_filters ()
void | clutter_actor_get_content_scaling_filters ()
void | clutter_actor_set_content_repeat ()
ClutterContentRepeat | clutter_actor_get_content_repeat ()
void | clutter_actor_get_content_box ()
void | clutter_actor_set_clip ()
void | clutter_actor_remove_clip ()
gboolean | clutter_actor_has_clip ()
void | clutter_actor_get_clip ()
void | clutter_actor_set_clip_to_allocation ()
gboolean | clutter_actor_get_clip_to_allocation ()
void | clutter_actor_set_opacity ()
guint8 | clutter_actor_get_opacity ()
void | clutter_actor_set_opacity_override ()
gint | clutter_actor_get_opacity_override ()
void | clutter_actor_set_offscreen_redirect ()
ClutterOffscreenRedirect | clutter_actor_get_offscreen_redirect ()
gboolean | clutter_actor_is_in_clone_paint ()
void | clutter_actor_add_child ()
void | clutter_actor_insert_child_above ()
void | clutter_actor_insert_child_at_index ()
void | clutter_actor_insert_child_below ()
void | clutter_actor_replace_child ()
void | clutter_actor_remove_child ()
void | clutter_actor_remove_all_children ()
void | clutter_actor_destroy_all_children ()
ClutterActor * | clutter_actor_get_first_child ()
ClutterActor * | clutter_actor_get_next_sibling ()
ClutterActor * | clutter_actor_get_previous_sibling ()
ClutterActor * | clutter_actor_get_last_child ()
ClutterActor * | clutter_actor_get_child_at_index ()
GList * | clutter_actor_get_children ()
gint | clutter_actor_get_n_children ()
ClutterActor * | clutter_actor_get_parent ()
void | clutter_actor_set_child_above_sibling ()
void | clutter_actor_set_child_at_index ()
void | clutter_actor_set_child_below_sibling ()
gboolean | clutter_actor_contains ()
ClutterActor * | clutter_actor_get_stage ()
void | clutter_actor_iter_init ()
gboolean | clutter_actor_iter_is_valid ()
gboolean | clutter_actor_iter_next ()
gboolean | clutter_actor_iter_prev ()
void | clutter_actor_iter_remove ()
void | clutter_actor_iter_destroy ()
ClutterActor * | ( *ClutterActorCreateChildFunc ) ()
void | clutter_actor_bind_model ()
void | clutter_actor_bind_model_with_properties ()
void | clutter_actor_save_easing_state ()
void | clutter_actor_restore_easing_state ()
void | clutter_actor_set_easing_duration ()
guint | clutter_actor_get_easing_duration ()
void | clutter_actor_set_easing_mode ()
ClutterAnimationMode | clutter_actor_get_easing_mode ()
void | clutter_actor_set_easing_delay ()
guint | clutter_actor_get_easing_delay ()
ClutterTransition * | clutter_actor_get_transition ()
void | clutter_actor_add_transition ()
void | clutter_actor_remove_transition ()
void | clutter_actor_remove_all_transitions ()
void | clutter_actor_set_reactive ()
gboolean | clutter_actor_get_reactive ()
gboolean | clutter_actor_has_key_focus ()
void | clutter_actor_grab_key_focus ()
gboolean | clutter_actor_has_pointer ()
PangoContext * | clutter_actor_get_pango_context ()
PangoContext * | clutter_actor_create_pango_context ()
PangoLayout * | clutter_actor_create_pango_layout ()
void | clutter_actor_set_text_direction ()
ClutterTextDirection | clutter_actor_get_text_direction ()
AtkObject * | clutter_actor_get_accessible ()
void | clutter_actor_add_action ()
void | clutter_actor_add_action_with_name ()
void | clutter_actor_remove_action ()
void | clutter_actor_remove_action_by_name ()
gboolean | clutter_actor_has_actions ()
GList * | clutter_actor_get_actions ()
ClutterAction * | clutter_actor_get_action ()
void | clutter_actor_clear_actions ()
void | clutter_actor_add_constraint ()
void | clutter_actor_add_constraint_with_name ()
void | clutter_actor_remove_constraint ()
void | clutter_actor_remove_constraint_by_name ()
gboolean | clutter_actor_has_constraints ()
GList * | clutter_actor_get_constraints ()
ClutterConstraint * | clutter_actor_get_constraint ()
void | clutter_actor_clear_constraints ()
void | clutter_actor_add_effect ()
void | clutter_actor_add_effect_with_name ()
void | clutter_actor_remove_effect ()
void | clutter_actor_remove_effect_by_name ()
gboolean | clutter_actor_has_effects ()
GList * | clutter_actor_get_effects ()
ClutterEffect * | clutter_actor_get_effect ()
void | clutter_actor_clear_effects ()
void | clutter_actor_set_scale_full ()
void | clutter_actor_set_scale_with_gravity ()
void | clutter_actor_get_scale_center ()
ClutterGravity | clutter_actor_get_scale_gravity ()
void | clutter_actor_set_depth ()
gfloat | clutter_actor_get_depth ()
void | clutter_actor_push_internal ()
void | clutter_actor_pop_internal ()
void | clutter_actor_set_parent ()
void | clutter_actor_reparent ()
void | clutter_actor_unparent ()
void | clutter_actor_raise ()
void | clutter_actor_lower ()
void | clutter_actor_raise_top ()
void | clutter_actor_lower_bottom ()
gboolean | clutter_actor_set_shader ()
ClutterShader * | clutter_actor_get_shader ()
void | clutter_actor_set_shader_param ()
void | clutter_actor_set_shader_param_float ()
void | clutter_actor_set_shader_param_int ()
void | clutter_actor_set_anchor_point ()
void | clutter_actor_get_anchor_point ()
void | clutter_actor_set_anchor_point_from_gravity ()
ClutterGravity | clutter_actor_get_anchor_point_gravity ()
void | clutter_actor_move_anchor_point ()
void | clutter_actor_move_anchor_point_from_gravity ()
void | clutter_actor_set_rotation ()
gdouble | clutter_actor_get_rotation ()
void | clutter_actor_set_z_rotation_from_gravity ()
ClutterGravity | clutter_actor_get_z_rotation_gravity ()
void | clutter_actor_get_transformation_matrix ()

## Properties

ClutterAction * | actions | Write
ClutterActorBox * | allocation | Read
ClutterGravity | anchor-gravity | Read / Write
gfloat | anchor-x | Read / Write
gfloat | anchor-y | Read / Write
ClutterColor * | background-color | Read / Write
gboolean | background-color-set | Read
ClutterMatrix * | child-transform | Read / Write
gboolean | child-transform-set | Read
ClutterGeometry * | clip | Read / Write
ClutterRect * | clip-rect | Read / Write
gboolean | clip-to-allocation | Read / Write
ClutterConstraint * | constraints | Write
ClutterContent * | content | Read / Write
ClutterActorBox * | content-box | Read
ClutterContentGravity | content-gravity | Read / Write
ClutterContentRepeat | content-repeat | Read / Write
gfloat | depth | Read / Write
ClutterEffect * | effect | Write
ClutterActor * | first-child | Read
gboolean | fixed-position-set | Read / Write
gfloat | fixed-x | Read / Write
gfloat | fixed-y | Read / Write
gboolean | has-clip | Read
gboolean | has-pointer | Read
gfloat | height | Read / Write
ClutterActor * | last-child | Read
ClutterLayoutManager * | layout-manager | Read / Write
ClutterScalingFilter | magnification-filter | Read / Write
gboolean | mapped | Read
gfloat | margin-bottom | Read / Write
gfloat | margin-left | Read / Write
gfloat | margin-right | Read / Write
gfloat | margin-top | Read / Write
gfloat | min-height | Read / Write
gboolean | min-height-set | Read / Write
gfloat | min-width | Read / Write
gboolean | min-width-set | Read / Write
ClutterScalingFilter | minification-filter | Read / Write
gchar * | name | Read / Write
gfloat | natural-height | Read / Write
gboolean | natural-height-set | Read / Write
gfloat | natural-width | Read / Write
gboolean | natural-width-set | Read / Write
ClutterOffscreenRedirect | offscreen-redirect | Read / Write
guint | opacity | Read / Write
ClutterPoint * | pivot-point | Read / Write
gfloat | pivot-point-z | Read / Write
ClutterPoint * | position | Read / Write
gboolean | reactive | Read / Write
gboolean | realized | Read
ClutterRequestMode | request-mode | Read / Write
gdouble | rotation-angle-x | Read / Write
gdouble | rotation-angle-y | Read / Write
gdouble | rotation-angle-z | Read / Write
ClutterVertex * | rotation-center-x | Read / Write
ClutterVertex * | rotation-center-y | Read / Write
ClutterVertex * | rotation-center-z | Read / Write
ClutterGravity | rotation-center-z-gravity | Read / Write
gfloat | scale-center-x | Read / Write
gfloat | scale-center-y | Read / Write
ClutterGravity | scale-gravity | Read / Write
gdouble | scale-x | Read / Write
gdouble | scale-y | Read / Write
gdouble | scale-z | Read / Write
gboolean | show-on-set-parent | Read / Write
ClutterSize * | size | Read / Write
ClutterTextDirection | text-direction | Read / Write
ClutterMatrix * | transform | Read / Write
gboolean | transform-set | Read
gfloat | translation-x | Read / Write
gfloat | translation-y | Read / Write
gfloat | translation-z | Read / Write
gboolean | visible | Read / Write
gfloat | width | Read / Write
gfloat | x | Read / Write
ClutterActorAlign | x-align | Read / Write
gboolean | x-expand | Read / Write
gfloat | y | Read / Write
ClutterActorAlign | y-align | Read / Write
gboolean | y-expand | Read / Write
gfloat | z-position | Read / Write

## Signals

void | allocation-changed | Run Last
gboolean | button-press-event | Run Last
gboolean | button-release-event | Run Last
gboolean | captured-event | Run Last
void | destroy | No Hooks
gboolean | enter-event | Run Last
gboolean | event | Run Last
void | hide | Run First
void | key-focus-in | Run Last
void | key-focus-out | Run Last
gboolean | key-press-event | Run Last
gboolean | key-release-event | Run Last
gboolean | leave-event | Run Last
gboolean | motion-event | Run Last
void | paint | No Hooks
void | parent-set | Run Last
void | pick | Run Last
void | queue-redraw | No Hooks
void | queue-relayout | No Hooks
void | realize | Run Last
gboolean | scroll-event | Run Last
void | show | Run First
gboolean | touch-event | Run Last
void | transition-stopped | No Hooks
void | transitions-completed | Run Last
void | unrealize | Run Last

## Types and Values

enum | ClutterActorFlags
enum | ClutterRequestMode
| ClutterActor
struct | ClutterActorClass
enum | ClutterAllocationFlags
enum | ClutterActorAlign
struct | ClutterMargin
enum | ClutterContentGravity
enum | ClutterScalingFilter
enum | ClutterContentRepeat
enum | ClutterOffscreenRedirect
| ClutterActorIter

## Object Hierarchy

        GBoxed
        ╰── ClutterMargin
        GObject
        ╰── GInitiallyUnowned
            ╰── ClutterActor
                ├── ClutterBox
                ├── ClutterTexture
                ├── ClutterClone
                ├── ClutterGroup
                ├── ClutterRectangle
                ├── ClutterScrollActor
                ╰── ClutterText

## Implemented Interfaces

ClutterActor implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Description

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.

#### 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:

1. translation by the origin of the “allocation” property

2. translation by the actor's “z-position” property

3. translation by the actor's “pivot-point” property

4. scaling by the “scale-x” and “scale-y” factors

5. rotation around the “rotation-angle-x” and “rotation-center-x”

6. rotation around the “rotation-angle-y” and “rotation-center-y”

7. rotation around the “rotation-angle-z” and “rotation-center-z”

8. negative translation by the “anchor-x” and “anchor-y” point.

9. negative translation by the actor's “pivot-point”

#### 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 `ClutterActorClass.get_preferred_width()` and the `ClutterActorClass.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.

#### 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. ClutterActor 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()`.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19

    ClutterActor *actor = clutter_actor_new ();

    // set the bounding box of the actor
    clutter_actor_set_position (actor, 0, 0);
    clutter_actor_set_size (actor, 480, 640);

    // set the background color of the actor
    clutter_actor_set_background_color (actor, CLUTTER_COLOR_Orange);

    // set the bounding box of the child, relative to the parent
    ClutterActor *child = clutter_actor_new ();
    clutter_actor_set_position (child, 20, 20);
    clutter_actor_set_size (child, 80, 240);

    // set the background color of the child
    clutter_actor_set_background_color (child, CLUTTER_COLOR_Blue);

    // add the child to the actor
    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 ClutterActor, use the “actor-added” signal; similarly, to track removals of children from a ClutterActor, use the “actor-removed” signal.

See basic-actor.c.

#### Painting an actor

There are three ways to paint an actor:

- set a delegate ClutterContent as the value for the “content” property of the actor

- subclass ClutterActor and override the `ClutterActorClass.paint_node()` virtual function

- subclass ClutterActor and override the `ClutterActorClass.paint()` virtual function.

A ClutterContent is a delegate object that takes over the painting operations of one, or more actors. The ClutterContent painting will be performed on top of the “background-color” of the actor, and before calling the actor's own implementation of the `ClutterActorClass.paint_node()` virtual function.

    1
    2
    3
    4
    5
    6
    7
    8

    ClutterActor *actor = clutter_actor_new ();

    // set the bounding box
    clutter_actor_set_position (actor, 50, 50);
    clutter_actor_set_size (actor, 100, 100);

    // set the content; the image_content variable is set elsewhere
    clutter_actor_set_content (actor, image_content);

The `ClutterActorClass.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 ClutterPaintNode 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”.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33

    static void
    my_actor_paint_node (ClutterActor     *actor,
                         ClutterPaintNode *root)
    {
      ClutterPaintNode *node;
      ClutterActorBox box;

      // where the content of the actor should be painted
      clutter_actor_get_allocation_box (actor, &box);

      // the cogl_texture variable is set elsewhere
      node = clutter_texture_node_new (cogl_texture, CLUTTER_COLOR_White,
                                       CLUTTER_SCALING_FILTER_TRILINEAR,
                                       CLUTTER_SCALING_FILTER_LINEAR);

      // paint the content of the node using the allocation
      clutter_paint_node_add_rectangle (node, &box);

      // add the node, and transfer ownership
      clutter_paint_node_add_child (root, node);
      clutter_paint_node_unref (node);
    }

    The #ClutterActorClass.paint() virtual function is invoked when the
    #ClutterActor::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 #ClutterActorClass.paint()
    virtual function, as well as connecting to the #ClutterActor::paint
    signal. These hooks into the paint sequence are considered legacy, and
    will be removed when the Clutter API changes.

#### Handling events on an actor

A ClutterActor can receive and handle input device events, for instance pointer events and key events, as long as its “reactive” property is set to `TRUE`.

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 is emitted, alongside eventual event-specific signals like “button-press-event” or “motion-event”; 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`.

#### 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. You have two models at your disposal:

- an implicit animation model

- an explicit animation model

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, if the property is defined to be animatable in its documentation.

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.

Implicit animations depend on the current easing state; in order to use the default easing state for an actor you should call the `clutter_actor_save_easing_state()` function:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

    // assume that the actor is currently positioned at (100, 100)

    // store the current easing state and reset the new easing state to
    // its default values
    clutter_actor_save_easing_state (actor);

    // change the actor's position
    clutter_actor_set_position (actor, 500, 500);

    // restore the previously saved easing state
    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.

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15

    clutter_actor_save_easing_state (actor);

    // animate the actor's opacity and depth
    clutter_actor_set_opacity (actor, 0);
    clutter_actor_set_depth (actor, -100);

    clutter_actor_restore_easing_state (actor);

    clutter_actor_save_easing_state (another_actor);

    // animate another actor's opacity
    clutter_actor_set_opacity (another_actor, 255);
    clutter_actor_set_depth (another_actor, 100);

    clutter_actor_restore_easing_state (another_actor);

Changing the easing state will affect all the following property transitions, but will not affect existing transitions.

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:

    1
    2
    3
    4
    5
    6
    7
    8
    9

    clutter_actor_save_easing_state (actor);
    clutter_actor_set_easing_duration (actor, 1000);
    clutter_actor_set_x (actor, 200);
    clutter_actor_restore_easing_state (actor);

    clutter_actor_save_easing_state (actor);
    clutter_actor_set_easing_duration (actor, 500);
    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 from the current value to the value of 200 over a duration of one second; the second call to `clutter_actor_set_x()` will change the transition's final value to 100 and the duration to 500 milliseconds.

It is possible to receive a notification of the completion of an implicit transition by using the “transition-stopped” signal, decorated with the name of the property. In case you want to know when all the currently in flight transitions are complete, use the “transitions-completed” signal instead.

It is possible to retrieve the ClutterTransition 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 ClutterTransition object, and optionally set the initial and final values. The transition will not start unless you add it to the ClutterActor.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10

    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_from (transition, G_TYPE_UINT, 255);
    clutter_transition_set_to (transition, G_TYPE_UINT, 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 applies to all GObject properties, as well as the custom properties defined through the ClutterAnimatable interface, regardless of whether they are defined as implicitly animatable or not.

The explicit animation API should also be used when using custom animatable properties for ClutterAction, ClutterConstraint, and ClutterEffect 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23

    // this animation will pulse the actor's opacity continuously
    ClutterTransition *transition;
    ClutterInterval *interval;

    transition = clutter_property_transition_new ("opacity");

    // we want to animate the opacity between 0 and 255
    clutter_transition_set_from (transition, G_TYPE_UINT, 0);
    clutter_transition_set_to (transition, G_TYPE_UINT, 255);

    // over a one second duration, running an infinite amount of times
    clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 1000);
    clutter_timeline_set_repeat_count (CLUTTER_TIMELINE (transition), -1);

    // we want to fade in and out, so we need to auto-reverse the transition
    clutter_timeline_set_auto_reverse (CLUTTER_TIMELINE (transition), TRUE);

    // and we want to use an easing function that eases both in and out
    clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                        CLUTTER_EASE_IN_OUT_CUBIC);

    // add the transition to the desired actor to start it
    clutter_actor_add_transition (actor, "opacityAnimation", transition);

#### Implementing an actor

Careful consideration should be given when deciding to implement a ClutterActor sub-class. It is generally recommended to implement a sub-class of ClutterActor 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 `ClutterActorClass.get_preferred_width()` and `ClutterActorClass.get_preferred_height()` virtual functions it is possible to change or provide the preferred size of an actor; similarly, by overriding the `ClutterActorClass.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 `ClutterActorClass.allocate()` virtual function.

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

#### ClutterActor custom properties for ClutterScript

ClutterActor 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:

    1

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

where:

- axis is the name of an enumeration value of type ClutterRotateAxis

- angle is a floating point value representing the rotation angle on the given axis in degrees

- center-point is an optional array, 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"

  - X and Y for "z-axis".

ClutterActor also defines a scriptable "margin" property which follows the CSS "margin" shorthand.

    1
    2
    3
    4
    5
    6
    7
    8

    // 4 values
    "margin" : [ top, right, bottom, left ]
    // 3 values
    "margin" : [ top, left/right, bottom ]
    // 2 values
    "margin" : [ top/bottom, left/right ]
    // 1 value
    "margin" : [ top/right/bottom/left ]

ClutterActor will also parse every positional and dimensional property defined as a string through `clutter_units_from_string()`; you should read the documentation for the ClutterUnits parser format for the valid units and syntax.

#### Custom animatable properties

ClutterActor allows accessing properties of ClutterAction, ClutterEffect, and ClutterConstraint instances associated to an actor instance for animation purposes.

In order to access a specific ClutterAction or a ClutterConstraint property it is necessary to set the “name” property on the given action or constraint.

The property can be accessed using the following syntax:

    1

    @<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, effect, or constraint, as specified by the “name” property of ClutterActorMeta

- the `property-name` fragment is the name of the action, effect, or constraint property to be animated.

The example below animates a ClutterBindConstraint applied to an actor using an explicit transition. The `rect` actor has a binding constraint on the `origin` actor, and in its initial state is overlapping the actor to which is bound to.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13

    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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39

    gboolean
    on_button_press (ClutterActor *origin,
                     ClutterEvent *event,
                     ClutterActor *rect)
    {
      ClutterTransition *transition;

      // the offset that we want to apply; this will make the actor
      // slide in from behind the origin and rest at the right of
      // the origin, plus a padding value
      float new_offset = clutter_actor_get_width (origin) + h_padding;

      // the property we wish to animate; the "@constraints" section
      // tells Clutter to check inside the constraints associated
      // with the actor; the "bind-x" section is the name of the
      // constraint; and the "offset" is the name of the property
      // on the constraint
      const char *prop = "@constraints.bind-x.offset";

      // create a new transition for the given property
      transition = clutter_property_transition_new (prop);

      // set the easing mode and duration
      clutter_timeline_set_progress_mode (CLUTTER_TIMELINE (transition),
                                          CLUTTER_EASE_OUT_CUBIC);
      clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);

      // create the interval with the initial and final values
      clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f);
      clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset);

      // add the transition to the actor; this causes the animation
      // to start. the name "offsetAnimation" can be used to retrieve
      // the transition later
      clutter_actor_add_transition (rect, "offsetAnimation", transition);

      // we handled the event
      return CLUTTER_EVENT_STOP;
    }

## Functions

### CLUTTER_ACTOR_SET_FLAGS()

    #define             CLUTTER_ACTOR_SET_FLAGS(a,f)

`CLUTTER_ACTOR_SET_FLAGS` has been deprecated since version 1.24 and should not be used in newly-written code.

Changing flags directly is heavily discouraged in newly written code. ClutterActor will take care of setting the internal state.

Sets the given flags on a ClutterActor

#### Parameters

a | a ClutterActor |
f | the ClutterActorFlags to set |

### CLUTTER_ACTOR_UNSET_FLAGS()

    #define             CLUTTER_ACTOR_UNSET_FLAGS(a,f)

`CLUTTER_ACTOR_UNSET_FLAGS` has been deprecated since version 1.24 and should not be used in newly-written code.

Changing flags directly is heavily discouraged in newly written code. ClutterActor will take care of unsetting the internal state.

Unsets the given flags on a ClutterActor

#### Parameters

a | a ClutterActor |
f | the ClutterActorFlags to unset |

### CLUTTER_ACTOR_IS_MAPPED()

    #define             CLUTTER_ACTOR_IS_MAPPED(a)

`CLUTTER_ACTOR_IS_MAPPED` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `clutter_actor_is_mapped()` or the “mapped” property instead of this macro.

Evaluates to `TRUE` if the `CLUTTER_ACTOR_MAPPED` flag is set.

The mapped state is set when the actor is visible and all its parents up to a top-level (e.g. a ClutterStage) are visible, realized, and mapped.

This check can be used to see if an actor is going to be painted, as only actors with the `CLUTTER_ACTOR_MAPPED` flag set are going to be painted.

The `CLUTTER_ACTOR_MAPPED` flag is managed by Clutter itself, and it should not be checked directly; instead, the recommended usage is to connect a handler on the “notify” signal for the “mapped” property of ClutterActor, and check the presence of the `CLUTTER_ACTOR_MAPPED` flag on state changes.

It is also important to note that Clutter may delay the changes of the `CLUTTER_ACTOR_MAPPED` flag on top-levels due to backend-specific limitations, or during the reparenting of an actor, to optimize unnecessary (and potentially expensive) state changes.

#### Parameters

a | a ClutterActor |

Since: 0.2

### CLUTTER_ACTOR_IS_REALIZED()

    #define             CLUTTER_ACTOR_IS_REALIZED(a)

`CLUTTER_ACTOR_IS_REALIZED` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `clutter_actor_is_realized()` or the “realized” property instead of this macro.

Evaluates to `TRUE` if the `CLUTTER_ACTOR_REALIZED` flag is set.

The realized state has an actor-dependant interpretation. If an actor wants to delay allocating resources until it is attached to a stage, it may use the realize state to do so. However it is perfectly acceptable for an actor to allocate Cogl resources before being realized because there is only one drawing context used by Clutter so any resources will work on any stage. If an actor is mapped it must also be realized, but an actor can be realized and unmapped (this is so hiding an actor temporarily doesn't do an expensive unrealize/realize).

To be realized an actor must be inside a stage, and all its parents must be realized.

#### Parameters

a | a ClutterActor |

Since: 0.2

### CLUTTER_ACTOR_IS_VISIBLE()

    #define             CLUTTER_ACTOR_IS_VISIBLE(a)

`CLUTTER_ACTOR_IS_VISIBLE` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `clutter_actor_is_visible()` or the “visible” property instead of this macro.

Evaluates to `TRUE` if the actor has been shown, `FALSE` if it's hidden. Equivalent to the ClutterActor::visible object property.

Note that an actor is only painted onscreen if it's mapped, which means it's visible, and all its parents are visible, and one of the parents is a toplevel stage; see also `CLUTTER_ACTOR_IS_MAPPED`.

#### Parameters

a | a ClutterActor |

Since: 0.2

### CLUTTER_ACTOR_IS_REACTIVE()

    #define             CLUTTER_ACTOR_IS_REACTIVE(a)

`CLUTTER_ACTOR_IS_REACTIVE` has been deprecated since version 1.24 and should not be used in newly-written code.

Use `clutter_actor_get_reactive()` or the “reactive” property instead of this macro.

Evaluates to `TRUE` if the `CLUTTER_ACTOR_REACTIVE` flag is set.

Only reactive actors will receive event-related signals.

#### Parameters

a | a ClutterActor |

Since: 0.6

### CLUTTER_CALLBACK()

    #define CLUTTER_CALLBACK(f)        ((ClutterCallback) (f))

Convenience macro to cast a function to ClutterCallback

#### Parameters

f | a function |

### ClutterCallback ()

    void
    (*ClutterCallback) (ClutterActor *actor,
                        gpointer data);

Generic callback

#### Parameters

actor | a ClutterActor |
data | user data. | [closure]

### clutter_actor_new ()

    ClutterActor *
    clutter_actor_new (void);

Creates a new ClutterActor.

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

#### Returns

the newly created ClutterActor

Since: 1.10

### clutter_actor_set_flags ()

    void
    clutter_actor_set_flags (ClutterActor *self,
                             ClutterActorFlags flags);

Sets `flags` on `self`

This function will emit notifications for the changed properties

#### Parameters

self | a ClutterActor |
flags | the flags to set |

Since: 1.0

### clutter_actor_unset_flags ()

    void
    clutter_actor_unset_flags (ClutterActor *self,
                               ClutterActorFlags flags);

Unsets `flags` on `self`

This function will emit notifications for the changed properties

#### Parameters

self | a ClutterActor |
flags | the flags to unset |

Since: 1.0

### clutter_actor_get_flags ()

    ClutterActorFlags
    clutter_actor_get_flags (ClutterActor *self);

Retrieves the flags set on `self`

#### Parameters

self | a ClutterActor |

#### Returns

a bitwise or of ClutterActorFlags or 0

Since: 1.0

### clutter_actor_set_name ()

    void
    clutter_actor_set_name (ClutterActor *self,
                            const gchar *name);

Sets the given name to `self` . The name can be used to identify a ClutterActor.

#### Parameters

self | A ClutterActor |
name | Textual tag to apply to actor |

### clutter_actor_get_name ()

    const gchar *
    clutter_actor_get_name (ClutterActor *self);

Retrieves the name of `self` .

#### Parameters

self | A ClutterActor |

#### Returns

the name of the actor, or `NULL`. The returned string is owned by the actor and should not be modified or freed.

### clutter_actor_get_gid ()

    guint32
    clutter_actor_get_gid (ClutterActor *self);

`clutter_actor_get_gid` has been deprecated since version 1.8 and should not be used in newly-written code.

The id is not used any longer, and this function always returns 0.

Retrieves the unique id for `self` .

#### Parameters

self | A ClutterActor |

#### Returns

Globally unique value for this object instance.

Since: 0.6

### clutter_actor_show ()

    void
    clutter_actor_show (ClutterActor *self);

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 `TRUE` as a side effect.

#### Parameters

self | A ClutterActor |

### clutter_actor_show_all ()

    void
    clutter_actor_show_all (ClutterActor *self);

`clutter_actor_show_all` has been deprecated since version 1.10 and should not be used in newly-written code.

Actors are visible by default

Calls `clutter_actor_show()` on all children of an actor (if any).

#### Parameters

self | a ClutterActor |

Since: 0.2

### clutter_actor_hide ()

    void
    clutter_actor_hide (ClutterActor *self);

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 `FALSE` as a side-effect.

#### Parameters

self | A ClutterActor |

### clutter_actor_hide_all ()

    void
    clutter_actor_hide_all (ClutterActor *self);

`clutter_actor_hide_all` has been deprecated since version 1.10 and should not be used in newly-written code.

Using `clutter_actor_hide()` on the actor will prevent its children from being painted as well.

Calls `clutter_actor_hide()` on all child actors (if any).

#### Parameters

self | a ClutterActor |

Since: 0.2

### clutter_actor_is_visible ()

    gboolean
    clutter_actor_is_visible (ClutterActor *self);

Checks whether an actor is marked as visible.

See also `CLUTTER_ACTOR_IS_VISIBLE` and “visible”.

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor visible

Since: 1.24

### clutter_actor_realize ()

    void
    clutter_actor_realize (ClutterActor *self);

`clutter_actor_realize` has been deprecated since version 1.16 and should not be used in newly-written code.

Actors are automatically realized, and nothing requires explicit realization.

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.

#### Parameters

self | A ClutterActor |

### clutter_actor_unrealize ()

    void
    clutter_actor_unrealize (ClutterActor *self);

`clutter_actor_unrealize` has been deprecated since version 1.16 and should not be used in newly-written code.

Actors are automatically unrealized, and nothing requires explicit realization.

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.

This function should not really be in the public API, because there isn't a good reason to call it. ClutterActor will already unrealize things for you when it's important to do so.

If you were using `clutter_actor_unrealize()` in a dispose implementation, then don't, just chain up to ClutterActor's dispose.

If you were using `clutter_actor_unrealize()` to implement unrealizing children of your container, then don't, ClutterActor will already take care of that.

#### Parameters

self | A ClutterActor |

### clutter_actor_is_realized ()

    gboolean
    clutter_actor_is_realized (ClutterActor *self);

Checks whether a ClutterActor is realized.

See also `CLUTTER_ACTOR_IS_REALIZED` and “realized”.

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor is realized

Since: 1.24

### clutter_actor_paint ()

    void
    clutter_actor_paint (ClutterActor *self);

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.

#### Parameters

self | A ClutterActor |

### clutter_actor_continue_paint ()

    void
    clutter_actor_continue_paint (ClutterActor *self);

Run the next stage of the paint sequence. This function should only be called within the implementation of the ‘run’ virtual of a ClutterEffect. 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.

#### Parameters

self | A ClutterActor |

Since: 1.8

### clutter_actor_queue_redraw ()

    void
    clutter_actor_queue_redraw (ClutterActor *self);

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.

#### Parameters

self | A ClutterActor |

### clutter_actor_queue_redraw_with_clip ()

    void
    clutter_actor_queue_redraw_with_clip (ClutterActor *self,
                                          const cairo_rectangle_int_t *clip);

Queues a redraw on `self` limited to a specific, actor-relative rectangular area.

If `clip` is `NULL` this function is equivalent to `clutter_actor_queue_redraw()`.

#### Parameters

self | a ClutterActor |
clip | a rectangular clip region, or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_queue_relayout ()

    void
    clutter_actor_queue_relayout (ClutterActor *self);

Indicates that the actor's size request or other layout-affecting properties may have changed. This function is used inside ClutterActor subclass implementations, not by applications directly.

Queueing a new layout automatically queues a redraw as well.

#### Parameters

self | A ClutterActor |

Since: 0.8

### clutter_actor_destroy ()

    void
    clutter_actor_destroy (ClutterActor *self);

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 ClutterStage returned by `clutter_stage_get_default()`.

#### Parameters

self | a ClutterActor |

### clutter_actor_event ()

    gboolean
    clutter_actor_event (ClutterActor *actor,
                         const ClutterEvent *event,
                         gboolean capture);

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

#### Parameters

actor | a ClutterActor |
event | a ClutterEvent |
capture | `TRUE` if event in in capture phase, `FALSE` otherwise. |

#### Returns

the return value from the signal emission: `TRUE` if the actor handled the event, or `FALSE` if the event was not handled

Since: 0.6

### clutter_actor_should_pick_paint ()

    gboolean
    clutter_actor_should_pick_paint (ClutterActor *self);

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.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor should paint its silhouette, `FALSE` otherwise

### clutter_actor_map ()

    void
    clutter_actor_map (ClutterActor *self);

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

#### Parameters

self | A ClutterActor |

Since: 1.0

### clutter_actor_unmap ()

    void
    clutter_actor_unmap (ClutterActor *self);

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 ClutterActor implementation of `ClutterActorClass.unmap()` will also unmap any eventual children by default when their parent is unmapped.

When overriding `ClutterActorClass.unmap()`, it is mandatory to chain up to the parent implementation.

It is important to note that the implementation of the `ClutterActorClass.unmap()` virtual function may be called after the `ClutterActorClass.destroy()` or the `GObjectClass.dispose()` implementation, but it is guaranteed to be called before the `GObjectClass.finalize()` implementation.

#### Parameters

self | A ClutterActor |

Since: 1.0

### clutter_actor_is_mapped ()

    gboolean
    clutter_actor_is_mapped (ClutterActor *self);

Checks whether a ClutterActor has been set as mapped.

See also `CLUTTER_ACTOR_IS_MAPPED` and “mapped”

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor is mapped

Since: 1.24

### clutter_actor_has_overlaps ()

    gboolean
    clutter_actor_has_overlaps (ClutterActor *self);

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 `ClutterActorClass.has_overlaps()` virtual function. See `clutter_actor_set_offscreen_redirect()` for more information.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor may have overlapping primitives, and `FALSE` otherwise

Since: 1.8

### clutter_actor_has_mapped_clones ()

    gboolean
    clutter_actor_has_mapped_clones (ClutterActor *self);

Returns whether a ClutterActor has any mapped clones.

Return: `TRUE` if the actor has mapped clones, and `FALSE` otherwise

#### Parameters

self | a ClutterActor |

Since: 1.16

### clutter_actor_allocate ()

    void
    clutter_actor_allocate (ClutterActor *self,
                            const ClutterActorBox *box,
                            ClutterAllocationFlags flags);

Assigns the size of a ClutterActor from the given `box` .

This function should only be called on the children of an actor when overriding the `ClutterActorClass.allocate()` virtual function.

This function will adjust the stored allocation to take into account the alignment flags set in the “x-align” and “y-align” properties, as well as the margin values set in the “margin-top”, “margin-right”, “margin-bottom”, and “margin-left” properties.

This function will respect the easing state of the ClutterActor and interpolate between the current allocation and the new one if the easing state duration is a positive value.

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.

#### Parameters

self | A ClutterActor |
box | new allocation of the actor, in parent-relative coordinates |
flags | flags that control the allocation |

Since: 0.8

### clutter_actor_allocate_preferred_size ()

    void
    clutter_actor_allocate_preferred_size (ClutterActor *self,
                                           ClutterAllocationFlags flags);

Allocates the natural size of `self` .

This function is a utility call for ClutterActor implementations that allocates the actor's preferred natural size. It can be used by fixed layout managers (like ClutterGroup or so called 'composite actors') inside the ClutterActor::allocate implementation to give each child exactly how much space it requires, regardless of the size of the parent.

This function is not meant to be used by applications. It is also not meant to be used outside the implementation of the ClutterActorClass.allocate virtual function.

#### Parameters

self | a ClutterActor |
flags | flags controlling the allocation |

Since: 0.8

### clutter_actor_allocate_available_size ()

    void
    clutter_actor_allocate_available_size (ClutterActor *self,
                                           gfloat x,
                                           gfloat y,
                                           gfloat available_width,
                                           gfloat available_height,
                                           ClutterAllocationFlags flags);

Allocates `self` taking into account the ClutterActor's preferred size, but limiting it to the maximum available width and height provided.

This function will do the right thing when dealing with the actor's request mode.

The implementation of this function is equivalent to:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36

    if (request_mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
      {
        clutter_actor_get_preferred_width (self, available_height,
                                           &min_width,
                                           &natural_width);
        width = CLAMP (natural_width, min_width, available_width);

        clutter_actor_get_preferred_height (self, width,
                                            &min_height,
                                            &natural_height);
        height = CLAMP (natural_height, min_height, available_height);
      }
    else if (request_mode == CLUTTER_REQUEST_WIDTH_FOR_HEIGHT)
      {
        clutter_actor_get_preferred_height (self, available_width,
                                            &min_height,
                                            &natural_height);
        height = CLAMP (natural_height, min_height, available_height);

        clutter_actor_get_preferred_width (self, height,
                                           &min_width,
                                           &natural_width);
        width = CLAMP (natural_width, min_width, available_width);
      }
    else if (request_mode == CLUTTER_REQUEST_CONTENT_SIZE)
      {
        clutter_content_get_preferred_size (content, &natural_width, &natural_height);

        width = CLAMP (natural_width, 0, available_width);
        height = CLAMP (natural_height, 0, available_height);
      }

    box.x1 = x; box.y1 = y;
    box.x2 = box.x1 + available_width;
    box.y2 = box.y1 + available_height;
    clutter_actor_allocate (self, &box, flags);

This function can be used by fluid layout managers to allocate an actor's preferred size without making it bigger than the area available for the container.

#### Parameters

self | a ClutterActor |
x | the actor's X coordinate |
y | the actor's Y coordinate |
available_width | the maximum available width, or -1 to use the actor's natural width |
available_height | the maximum available height, or -1 to use the actor's natural height |
flags | flags controlling the allocation |

Since: 1.0

### clutter_actor_allocate_align_fill ()

    void
    clutter_actor_allocate_align_fill (ClutterActor *self,
                                       const ClutterActorBox *box,
                                       gdouble x_align,
                                       gdouble y_align,
                                       gboolean x_fill,
                                       gboolean y_fill,
                                       ClutterAllocationFlags flags);

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 ClutterActorBox 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 using legacy alignment flags. Newly written layout managers should use the “x-align” and “y-align” properties, instead, and just call `clutter_actor_allocate()` inside their `ClutterActorClass.allocate()` implementation.

#### Parameters

self | a ClutterActor |
box | a ClutterActorBox, 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

### clutter_actor_set_allocation ()

    void
    clutter_actor_set_allocation (ClutterActor *self,
                                  const ClutterActorBox *box,
                                  ClutterAllocationFlags flags);

Stores the allocation of `self` as defined by `box` .

This function can only be called from within the implementation of the `ClutterActorClass.allocate()` virtual function.

The allocation should have been adjusted to take into account constraints, alignment, and margin properties. If you are implementing a ClutterActor subclass that provides its own layout management policy for its children instead of using a ClutterLayoutManager 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 ClutterActor that wish to store their allocation but cannot chain up to the parent's implementation; the default implementation of the `ClutterActorClass.allocate()` virtual function will call this function.

It is important to note that, while chaining up was the recommended behaviour for ClutterActor subclasses prior to the introduction of this function, it is recommended to call `clutter_actor_set_allocation()` instead.

If the ClutterActor is using a ClutterLayoutManager 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15

    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;

      // this will use the layout manager set on the actor
      clutter_actor_set_allocation (actor, &new_alloc, new_flags);
    }

is equivalent to this:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18

    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);
    }

#### Parameters

self | a ClutterActor |
box | a ClutterActorBox |
flags | allocation flags |

Since: 1.10

### clutter_actor_get_allocation_box ()

    void
    clutter_actor_get_allocation_box (ClutterActor *self,
                                      ClutterActorBox *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.

#### Parameters

self | A ClutterActor |
box | the function fills this in with the actor's allocation. | [out]

Since: 0.8

### clutter_actor_get_allocation_geometry ()

    void
    clutter_actor_get_allocation_geometry (ClutterActor *self,
                                           ClutterGeometry *geom);

`clutter_actor_get_allocation_geometry` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_allocation_box()` instead.

Gets the layout box an actor has been assigned. The allocation can only be assumed valid inside a `paint()` method; anywhere else, it may be out-of-date.

An allocation does not incorporate the actor's scale or anchor point; those transformations do not affect layout, only rendering.

The returned rectangle is in pixels.

#### Parameters

self | A ClutterActor |
geom | allocation geometry in pixels. | [out]

Since: 0.8

### clutter_actor_get_allocation_vertices ()

    void
    clutter_actor_get_allocation_vertices (ClutterActor *self,
                                           ClutterActor *ancestor,
                                           ClutterVertex verts[]);

Calculates the transformed coordinates of the four corners of the actor in the plane of `ancestor` . The returned vertices relate to the ClutterActorBox coordinates as follows:

- `verts` [0] contains (x1, y1)

- `verts` [1] contains (x2, y1)

- `verts` [2] contains (x1, y2)

- `verts` [3] contains (x2, y2)

If `ancestor` is `NULL` the ancestor will be the ClutterStage. In this case, the coordinates returned will be the coordinates on the stage before the projection is applied. This is different from the behaviour of `clutter_actor_get_abs_allocation_vertices()`.

#### Parameters

self | A ClutterActor |
ancestor | A ClutterActor to calculate the vertices against, or `NULL` to use the ClutterStage. | [allow-none]
verts | return location for an array of 4 ClutterVertex in which to store the result. | [out][array fixed-size=4][element-type Clutter.Vertex]

Since: 0.6

### clutter_actor_get_preferred_size ()

    void
    clutter_actor_get_preferred_size (ClutterActor *self,
                                      gfloat *min_width_p,
                                      gfloat *min_height_p,
                                      gfloat *natural_width_p,
                                      gfloat *natural_height_p);

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.

#### Parameters

self | a ClutterActor |
min_width_p | return location for the minimum width, or `NULL`. | [out][allow-none]
min_height_p | return location for the minimum height, or `NULL`. | [out][allow-none]
natural_width_p | return location for the natural width, or `NULL`. | [out][allow-none]
natural_height_p | return location for the natural height, or `NULL`. | [out][allow-none]

Since: 0.8

### clutter_actor_get_preferred_width ()

    void
    clutter_actor_get_preferred_width (ClutterActor *self,
                                       gfloat for_height,
                                       gfloat *min_width_p,
                                       gfloat *natural_width_p);

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.

#### Parameters

self | A ClutterActor |
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 `NULL`. | [out][allow-none]
natural_width_p | return location for the natural width, or `NULL`. | [out][allow-none]

Since: 0.8

### clutter_actor_get_preferred_height ()

    void
    clutter_actor_get_preferred_height (ClutterActor *self,
                                        gfloat for_width,
                                        gfloat *min_height_p,
                                        gfloat *natural_height_p);

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.

#### Parameters

self | A ClutterActor |
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 `NULL`. | [out][allow-none]
natural_height_p | return location for natural height, or `NULL`. | [out][allow-none]

Since: 0.8

### clutter_actor_set_fixed_position_set ()

    void
    clutter_actor_set_fixed_position_set (ClutterActor *self,
                                          gboolean is_set);

Sets whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

#### Parameters

self | A ClutterActor |
is_set | whether to use fixed position |

Since: 0.8

### clutter_actor_get_fixed_position_set ()

    gboolean
    clutter_actor_get_fixed_position_set (ClutterActor *self);

Checks whether an actor has a fixed position set (and will thus be unaffected by any layout manager).

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the fixed position is set on the actor

Since: 0.8

### clutter_actor_set_request_mode ()

    void
    clutter_actor_set_request_mode (ClutterActor *self,
                                    ClutterRequestMode 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()`

#### Parameters

self | a ClutterActor |
mode | the request mode |

Since: 1.2

### clutter_actor_get_request_mode ()

    ClutterRequestMode
    clutter_actor_get_request_mode (ClutterActor *self);

Retrieves the geometry request mode of `self`

#### Parameters

self | a ClutterActor |

#### Returns

the request mode for the actor

Since: 1.2

### clutter_actor_has_allocation ()

    gboolean
    clutter_actor_has_allocation (ClutterActor *self);

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 `FALSE`, then the actor will normally be allocated before it is next drawn on the screen.

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor has an up-to-date allocation

Since: 1.4

### clutter_actor_set_x_align ()

    void
    clutter_actor_set_x_align (ClutterActor *self,
                               ClutterActorAlign x_align);

Sets the horizontal alignment policy of a ClutterActor, in case the actor received extra horizontal space.

See also the “x-align” property.

#### Parameters

self | a ClutterActor |
x_align | the horizontal alignment policy |

Since: 1.10

### clutter_actor_get_x_align ()

    ClutterActorAlign
    clutter_actor_get_x_align (ClutterActor *self);

Retrieves the horizontal alignment policy set using `clutter_actor_set_x_align()`.

#### Parameters

self | a ClutterActor |

#### Returns

the horizontal alignment policy.

Since: 1.10

### clutter_actor_set_y_align ()

    void
    clutter_actor_set_y_align (ClutterActor *self,
                               ClutterActorAlign y_align);

Sets the vertical alignment policy of a ClutterActor, in case the actor received extra vertical space.

See also the “y-align” property.

#### Parameters

self | a ClutterActor |
y_align | the vertical alignment policy |

Since: 1.10

### clutter_actor_get_y_align ()

    ClutterActorAlign
    clutter_actor_get_y_align (ClutterActor *self);

Retrieves the vertical alignment policy set using `clutter_actor_set_y_align()`.

#### Parameters

self | a ClutterActor |

#### Returns

the vertical alignment policy.

Since: 1.10

### clutter_margin_copy ()

    ClutterMargin *
    clutter_margin_copy (const ClutterMargin *margin_);

Creates a new ClutterMargin and copies the contents of `margin_` into the newly created structure.

#### Parameters

margin_ | a ClutterMargin |

#### Returns

a copy of the ClutterMargin.

[transfer full]

Since: 1.10

### clutter_margin_free ()

    void
    clutter_margin_free (ClutterMargin *margin_);

Frees the resources allocated by `clutter_margin_new()` and `clutter_margin_copy()`.

#### Parameters

margin_ | a ClutterMargin |

Since: 1.10

### clutter_margin_new ()

    ClutterMargin *
    clutter_margin_new (void);

Creates a new ClutterMargin.

#### Returns

a newly allocated ClutterMargin. Use `clutter_margin_free()` to free the resources associated with it when done.

[transfer full]

Since: 1.10

### clutter_actor_set_margin ()

    void
    clutter_actor_set_margin (ClutterActor *self,
                              const ClutterMargin *margin);

Sets all the components of the margin of a ClutterActor.

#### Parameters

self | a ClutterActor |
margin | a ClutterMargin |

Since: 1.10

### clutter_actor_get_margin ()

    void
    clutter_actor_get_margin (ClutterActor *self,
                              ClutterMargin *margin);

Retrieves all the components of the margin of a ClutterActor.

#### Parameters

self | a ClutterActor |
margin | return location for a ClutterMargin. | [out caller-allocates]

Since: 1.10

### clutter_actor_set_margin_top ()

    void
    clutter_actor_set_margin_top (ClutterActor *self,
                                  gfloat margin);

Sets the margin from the top of a ClutterActor.

The “margin-top” property is animatable.

#### Parameters

self | a ClutterActor |
margin | the top margin |

Since: 1.10

### clutter_actor_get_margin_top ()

    gfloat
    clutter_actor_get_margin_top (ClutterActor *self);

Retrieves the top margin of a ClutterActor.

#### Parameters

self | a ClutterActor |

#### Returns

the top margin

Since: 1.10

### clutter_actor_set_margin_right ()

    void
    clutter_actor_set_margin_right (ClutterActor *self,
                                    gfloat margin);

Sets the margin from the right of a ClutterActor.

The “margin-right” property is animatable.

#### Parameters

self | a ClutterActor |
margin | the right margin |

Since: 1.10

### clutter_actor_get_margin_right ()

    gfloat
    clutter_actor_get_margin_right (ClutterActor *self);

Retrieves the right margin of a ClutterActor.

#### Parameters

self | a ClutterActor |

#### Returns

the right margin

Since: 1.10

### clutter_actor_set_margin_bottom ()

    void
    clutter_actor_set_margin_bottom (ClutterActor *self,
                                     gfloat margin);

Sets the margin from the bottom of a ClutterActor.

The “margin-bottom” property is animatable.

#### Parameters

self | a ClutterActor |
margin | the bottom margin |

Since: 1.10

### clutter_actor_get_margin_bottom ()

    gfloat
    clutter_actor_get_margin_bottom (ClutterActor *self);

Retrieves the bottom margin of a ClutterActor.

#### Parameters

self | a ClutterActor |

#### Returns

the bottom margin

Since: 1.10

### clutter_actor_set_margin_left ()

    void
    clutter_actor_set_margin_left (ClutterActor *self,
                                   gfloat margin);

Sets the margin from the left of a ClutterActor.

The “margin-left” property is animatable.

#### Parameters

self | a ClutterActor |
margin | the left margin |

Since: 1.10

### clutter_actor_get_margin_left ()

    gfloat
    clutter_actor_get_margin_left (ClutterActor *self);

Retrieves the left margin of a ClutterActor.

#### Parameters

self | a ClutterActor |

#### Returns

the left margin

Since: 1.10

### clutter_actor_set_x_expand ()

    void
    clutter_actor_set_x_expand (ClutterActor *self,
                                gboolean expand);

Sets whether a ClutterActor should expand horizontally; this means that layout manager should allocate extra space for the actor, if possible.

Setting an actor to expand will also make all its parent expand, so that it's possible to build an actor tree and only set this flag on its leaves and not on every single actor.

#### Parameters

self | a ClutterActor |
expand | whether the actor should expand horizontally |

Since: 1.12

### clutter_actor_get_x_expand ()

    gboolean
    clutter_actor_get_x_expand (ClutterActor *self);

Retrieves the value set with `clutter_actor_set_x_expand()`.

See also: `clutter_actor_needs_expand()`

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor has been set to expand

Since: 1.12

### clutter_actor_set_y_expand ()

    void
    clutter_actor_set_y_expand (ClutterActor *self,
                                gboolean expand);

Sets whether a ClutterActor should expand horizontally; this means that layout manager should allocate extra space for the actor, if possible.

Setting an actor to expand will also make all its parent expand, so that it's possible to build an actor tree and only set this flag on its leaves and not on every single actor.

#### Parameters

self | a ClutterActor |
expand | whether the actor should expand vertically |

Since: 1.12

### clutter_actor_get_y_expand ()

    gboolean
    clutter_actor_get_y_expand (ClutterActor *self);

Retrieves the value set with `clutter_actor_set_y_expand()`.

See also: `clutter_actor_needs_expand()`

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor has been set to expand

Since: 1.12

### clutter_actor_needs_expand ()

    gboolean
    clutter_actor_needs_expand (ClutterActor *self,
                                ClutterOrientation orientation);

Checks whether an actor, or any of its children, is set to expand horizontally or vertically.

This function should only be called by layout managers that can assign extra space to their children.

If you want to know whether the actor was explicitly set to expand, use `clutter_actor_get_x_expand()` or `clutter_actor_get_y_expand()`.

#### Parameters

self | a ClutterActor |
orientation | the direction of expansion |

#### Returns

`TRUE` if the actor should expand

Since: 1.12

### clutter_actor_set_layout_manager ()

    void
    clutter_actor_set_layout_manager (ClutterActor *self,
                                      ClutterLayoutManager *manager);

Sets the ClutterLayoutManager delegate object that will be used to lay out the children of `self` .

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

#### Parameters

self | a ClutterActor |
manager | a ClutterLayoutManager, or `NULL` to unset it. | [allow-none]

Since: 1.10

### clutter_actor_get_layout_manager ()

    ClutterLayoutManager *
    clutter_actor_get_layout_manager (ClutterActor *self);

Retrieves the ClutterLayoutManager used by `self` .

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to the ClutterLayoutManager, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_set_background_color ()

    void
    clutter_actor_set_background_color (ClutterActor *self,
                                        const ClutterColor *color);

Sets the background color of a ClutterActor.

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.

#### Parameters

self | a ClutterActor |
color | a ClutterColor, or `NULL` to unset a previously set color. | [allow-none]

Since: 1.10

### clutter_actor_get_background_color ()

    void
    clutter_actor_get_background_color (ClutterActor *self,
                                        ClutterColor *color);

Retrieves the color set using `clutter_actor_set_background_color()`.

#### Parameters

self | a ClutterActor |
color | return location for a ClutterColor. | [out caller-allocates]

Since: 1.10

### clutter_actor_set_geometry ()

    void
    clutter_actor_set_geometry (ClutterActor *self,
                                const ClutterGeometry *geometry);

`clutter_actor_set_geometry` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_position()` and `clutter_actor_set_size()` instead.

Sets the actor's fixed position and forces its minimum and natural size, in pixels. This means the untransformed actor will have the given geometry. This is the same as calling `clutter_actor_set_position()` and `clutter_actor_set_size()`.

#### Parameters

self | A ClutterActor |
geometry | A ClutterGeometry |

### clutter_actor_get_geometry ()

    void
    clutter_actor_get_geometry (ClutterActor *self,
                                ClutterGeometry *geometry);

`clutter_actor_get_geometry` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_get_position()` and `clutter_actor_get_size()`, or `clutter_actor_get_allocation_geometry()` instead.

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

#### Parameters

self | A ClutterActor |
geometry | A location to store actors ClutterGeometry. | [out caller-allocates]

### clutter_actor_set_size ()

    void
    clutter_actor_set_size (ClutterActor *self,
                            gfloat width,
                            gfloat height);

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.

#### Parameters

self | A ClutterActor |
width | New width of actor in pixels, or -1 |
height | New height of actor in pixels, or -1 |

### clutter_actor_get_size ()

    void
    clutter_actor_get_size (ClutterActor *self,
                            gfloat *width,
                            gfloat *height);

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()`.

#### Parameters

self | A ClutterActor |
width | return location for the width, or `NULL`. | [out][allow-none]
height | return location for the height, or `NULL`. | [out][allow-none]

Since: 0.2

### clutter_actor_set_position ()

    void
    clutter_actor_set_position (ClutterActor *self,
                                gfloat x,
                                gfloat y);

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.

#### Parameters

self | A ClutterActor |
x | New left position of actor in pixels. |
y | New top position of actor in pixels. |

### clutter_actor_get_position ()

    void
    clutter_actor_get_position (ClutterActor *self,
                                gfloat *x,
                                gfloat *y);

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.

#### Parameters

self | a ClutterActor |
x | return location for the X coordinate, or `NULL`. | [out][allow-none]
y | return location for the Y coordinate, or `NULL`. | [out][allow-none]

Since: 0.6

### clutter_actor_set_width ()

    void
    clutter_actor_set_width (ClutterActor *self,
                             gfloat 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.

#### Parameters

self | A ClutterActor |
width | Requested new width for the actor, in pixels, or -1 |

Since: 0.2

### clutter_actor_get_width ()

    gfloat
    clutter_actor_get_width (ClutterActor *self);

Retrieves the width of a ClutterActor.

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.

#### Parameters

self | A ClutterActor |

#### Returns

the width of the actor, in pixels

### clutter_actor_set_height ()

    void
    clutter_actor_set_height (ClutterActor *self,
                              gfloat 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.

#### Parameters

self | A ClutterActor |
height | Requested new height for the actor, in pixels, or -1 |

Since: 0.2

### clutter_actor_get_height ()

    gfloat
    clutter_actor_get_height (ClutterActor *self);

Retrieves the height of a ClutterActor.

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.

#### Parameters

self | A ClutterActor |

#### Returns

the height of the actor, in pixels

### clutter_actor_set_x ()

    void
    clutter_actor_set_x (ClutterActor *self,
                         gfloat 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.

#### Parameters

self | a ClutterActor |
x | the actor's position on the X axis |

Since: 0.6

### clutter_actor_get_x ()

    gfloat
    clutter_actor_get_x (ClutterActor *self);

Retrieves the X coordinate of a ClutterActor.

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.

#### Parameters

self | A ClutterActor |

#### Returns

the X coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)

### clutter_actor_set_y ()

    void
    clutter_actor_set_y (ClutterActor *self,
                         gfloat 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.

#### Parameters

self | a ClutterActor |
y | the actor's position on the Y axis |

Since: 0.6

### clutter_actor_get_y ()

    gfloat
    clutter_actor_get_y (ClutterActor *self);

Retrieves the Y coordinate of a ClutterActor.

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.

#### Parameters

self | A ClutterActor |

#### Returns

the Y coordinate, in pixels, ignoring any transformation (i.e. scaling, rotation)

### clutter_actor_move_by ()

    void
    clutter_actor_move_by (ClutterActor *self,
                           gfloat dx,
                           gfloat dy);

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()`, or with an additional translation, using `clutter_actor_set_translation()`.

#### Parameters

self | A ClutterActor |
dx | Distance to move Actor on X axis. |
dy | Distance to move Actor on Y axis. |

Since: 0.2

### clutter_actor_set_z_position ()

    void
    clutter_actor_set_z_position (ClutterActor *self,
                                  gfloat z_position);

Sets the actor's position on the Z axis.

See “z-position”.

#### Parameters

self | a ClutterActor |
z_position | the position on the Z axis |

Since: 1.12

### clutter_actor_get_z_position ()

    gfloat
    clutter_actor_get_z_position (ClutterActor *self);

Retrieves the actor's position on the Z axis.

#### Parameters

self | a ClutterActor |

#### Returns

the position on the Z axis.

Since: 1.12

### clutter_actor_set_pivot_point ()

    void
    clutter_actor_set_pivot_point (ClutterActor *self,
                                   gfloat pivot_x,
                                   gfloat pivot_y);

Sets the position of the “pivot-point” around which the scaling and rotation transformations occur.

The pivot point's coordinates are in normalized space, with the (0, 0) point being the top left corner of the actor, and the (1, 1) point being the bottom right corner.

#### Parameters

self | a ClutterActor |
pivot_x | the normalized X coordinate of the pivot point |
pivot_y | the normalized Y coordinate of the pivot point |

Since: 1.12

### clutter_actor_get_pivot_point ()

    void
    clutter_actor_get_pivot_point (ClutterActor *self,
                                   gfloat *pivot_x,
                                   gfloat *pivot_y);

Retrieves the coordinates of the “pivot-point”.

#### Parameters

self | a ClutterActor |
pivot_x | return location for the normalized X coordinate of the pivot point, or `NULL`. | [out][allow-none]
pivot_y | return location for the normalized Y coordinate of the pivot point, or `NULL`. | [out][allow-none]

Since: 1.12

### clutter_actor_set_pivot_point_z ()

    void
    clutter_actor_set_pivot_point_z (ClutterActor *self,
                                     gfloat pivot_z);

Sets the component on the Z axis of the “pivot-point” around which the scaling and rotation transformations occur.

The `pivot_z` value is expressed as a distance along the Z axis.

#### Parameters

self | a ClutterActor |
pivot_z | the Z coordinate of the actor's pivot point |

Since: 1.12

### clutter_actor_get_pivot_point_z ()

    gfloat
    clutter_actor_get_pivot_point_z (ClutterActor *self);

Retrieves the Z component of the “pivot-point”.

#### Parameters

self | a ClutterActor |

Since: 1.12

### clutter_actor_set_scale ()

    void
    clutter_actor_set_scale (ClutterActor *self,
                             gdouble scale_x,
                             gdouble scale_y);

Scales an actor with the given factors.

The scale transformation is relative the the “pivot-point”.

The “scale-x” and “scale-y” properties are animatable.

#### Parameters

self | A ClutterActor |
scale_x | double factor to scale actor by horizontally. |
scale_y | double factor to scale actor by vertically. |

Since: 0.2

### clutter_actor_get_scale ()

    void
    clutter_actor_get_scale (ClutterActor *self,
                             gdouble *scale_x,
                             gdouble *scale_y);

Retrieves an actors scale factors.

#### Parameters

self | A ClutterActor |
scale_x | Location to store horizonal scale factor, or `NULL`. | [out][allow-none]
scale_y | Location to store vertical scale factor, or `NULL`. | [out][allow-none]

Since: 0.2

### clutter_actor_set_scale_z ()

    void
    clutter_actor_set_scale_z (ClutterActor *self,
                               gdouble scale_z);

Scales an actor on the Z axis by the given `scale_z` factor.

The scale transformation is relative the the “pivot-point”.

The “scale-z” property is animatable.

#### Parameters

self | a ClutterActor |
scale_z | the scaling factor along the Z axis |

Since: 1.12

### clutter_actor_get_scale_z ()

    gdouble
    clutter_actor_get_scale_z (ClutterActor *self);

Retrieves the scaling factor along the Z axis, as set using `clutter_actor_set_scale_z()`.

#### Parameters

self | A ClutterActor |

#### Returns

the scaling factor along the Z axis

Since: 1.12

### clutter_actor_is_scaled ()

    gboolean
    clutter_actor_is_scaled (ClutterActor *self);

Checks whether the actor is scaled in either dimension.

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor is scaled.

Since: 0.6

### clutter_actor_set_rotation_angle ()

    void
    clutter_actor_set_rotation_angle (ClutterActor *self,
                                      ClutterRotateAxis axis,
                                      gdouble angle);

Sets the `angle` of rotation of a ClutterActor on the given `axis` .

This function is a convenience for setting the rotation properties “rotation-angle-x”, “rotation-angle-y”, and “rotation-angle-z”.

The center of rotation is established by the “pivot-point” property.

#### Parameters

self | a ClutterActor |
axis | the axis to set the angle one |
angle | the angle of rotation, in degrees |

Since: 1.12

### clutter_actor_get_rotation_angle ()

    gdouble
    clutter_actor_get_rotation_angle (ClutterActor *self,
                                      ClutterRotateAxis axis);

Retrieves the angle of rotation set by `clutter_actor_set_rotation_angle()`.

#### Parameters

self | a ClutterActor |
axis | the axis of the rotation |

#### Returns

the angle of rotation, in degrees

Since: 1.12

### clutter_actor_is_rotated ()

    gboolean
    clutter_actor_is_rotated (ClutterActor *self);

Checks whether any rotation is applied to the actor.

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor is rotated.

Since: 0.6

### clutter_actor_set_translation ()

    void
    clutter_actor_set_translation (ClutterActor *self,
                                   gfloat translate_x,
                                   gfloat translate_y,
                                   gfloat translate_z);

Sets an additional translation transformation on a ClutterActor, relative to the “pivot-point”.

#### Parameters

self | a ClutterActor |
translate_x | the translation along the X axis |
translate_y | the translation along the Y axis |
translate_z | the translation along the Z axis |

Since: 1.12

### clutter_actor_get_translation ()

    void
    clutter_actor_get_translation (ClutterActor *self,
                                   gfloat *translate_x,
                                   gfloat *translate_y,
                                   gfloat *translate_z);

Retrieves the translation set using `clutter_actor_set_translation()`.

#### Parameters

self | a ClutterActor |
translate_x | return location for the X component of the translation, or `NULL`. | [out][allow-none]
translate_y | return location for the Y component of the translation, or `NULL`. | [out][allow-none]
translate_z | return location for the Z component of the translation, or `NULL`. | [out][allow-none]

Since: 1.12

### clutter_actor_set_transform ()

    void
    clutter_actor_set_transform (ClutterActor *self,
                                 const ClutterMatrix *transform);

Overrides the transformations of a ClutterActor with a custom matrix, which will be applied relative to the origin of the actor's allocation and to the actor's pivot point.

The “transform” property is animatable.

#### Parameters

self | a ClutterActor |
transform | a ClutterMatrix, or `NULL` to unset a custom transformation. | [allow-none]

Since: 1.12

### clutter_actor_get_transform ()

    void
    clutter_actor_get_transform (ClutterActor *self,
                                 ClutterMatrix *transform);

Retrieves the current transformation matrix of a ClutterActor.

#### Parameters

self | a ClutterActor |
transform | a ClutterMatrix. | [out caller-allocates]

Since: 1.12

### clutter_actor_set_child_transform ()

    void
    clutter_actor_set_child_transform (ClutterActor *self,
                                       const ClutterMatrix *transform);

Sets the transformation matrix to be applied to all the children of `self` prior to their own transformations. The default child transformation is the identity matrix.

If `transform` is `NULL`, the child transform will be unset.

The “child-transform” property is animatable.

#### Parameters

self | a ClutterActor |
transform | a ClutterMatrix, or `NULL`. | [allow-none]

Since: 1.12

### clutter_actor_get_child_transform ()

    void
    clutter_actor_get_child_transform (ClutterActor *self,
                                       ClutterMatrix *transform);

Retrieves the child transformation matrix set using `clutter_actor_set_child_transform()`; if none is currently set, the `transform` matrix will be initialized to the identity matrix.

#### Parameters

self | a ClutterActor |
transform | a ClutterMatrix. | [out caller-allocates]

Since: 1.12

### clutter_actor_apply_transform_to_point ()

    void
    clutter_actor_apply_transform_to_point
                                   (ClutterActor *self,
                                    const ClutterVertex *point,
                                    ClutterVertex *vertex);

Transforms `point` in coordinates relative to the actor into screen-relative coordinates with the current actor transformation (i.e. scale, rotation, etc)

#### Parameters

self | A ClutterActor |
point | A point as ClutterVertex |
vertex | The translated ClutterVertex. | [out caller-allocates]

Since: 0.4

### clutter_actor_transform_stage_point ()

    gboolean
    clutter_actor_transform_stage_point (ClutterActor *self,
                                         gfloat x,
                                         gfloat y,
                                         gfloat *x_out,
                                         gfloat *y_out);

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 the `ClutterActorClass.paint()` implementation

#### Parameters

self | A ClutterActor |
x | x screen coordinate of the point to unproject. | [in]
y | y screen coordinate of the point to unproject. | [in]
x_out | return location for the unprojected x coordinance. | [out]
y_out | return location for the unprojected y coordinance. | [out]

#### Returns

`TRUE` if conversion was successful.

Since: 0.6

### clutter_actor_apply_relative_transform_to_point ()

    void
    clutter_actor_apply_relative_transform_to_point
                                   (ClutterActor *self,
                                    ClutterActor *ancestor,
                                    const ClutterVertex *point,
                                    ClutterVertex *vertex);

Transforms `point` in coordinates relative to the actor into ancestor-relative coordinates using the relevant transform stack (i.e. scale, rotation, etc).

If `ancestor` is `NULL` the ancestor will be the ClutterStage. In this case, the coordinates returned will be the coordinates on the stage before the projection is applied. This is different from the behaviour of `clutter_actor_apply_transform_to_point()`.

#### Parameters

self | A ClutterActor |
ancestor | A ClutterActor ancestor, or `NULL` to use the default ClutterStage. | [allow-none]
point | A point as ClutterVertex |
vertex | The translated ClutterVertex. | [out caller-allocates]

Since: 0.6

### clutter_actor_get_transformed_position ()

    void
    clutter_actor_get_transformed_position
                                   (ClutterActor *self,
                                    gfloat *x,
                                    gfloat *y);

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

#### Parameters

self | A ClutterActor |
x | return location for the X coordinate, or `NULL`. | [out][allow-none]
y | return location for the Y coordinate, or `NULL`. | [out][allow-none]

Since: 0.8

### clutter_actor_get_transformed_size ()

    void
    clutter_actor_get_transformed_size (ClutterActor *self,
                                        gfloat *width,
                                        gfloat *height);

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.

#### Parameters

self | A ClutterActor |
width | return location for the width, or `NULL`. | [out][allow-none]
height | return location for the height, or `NULL`. | [out][allow-none]

Since: 0.8

### clutter_actor_get_paint_opacity ()

    guint8
    clutter_actor_get_paint_opacity (ClutterActor *self);

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.

#### Parameters

self | A ClutterActor |

#### Returns

The actor opacity value.

Since: 0.8

### clutter_actor_get_paint_visibility ()

    gboolean
    clutter_actor_get_paint_visibility (ClutterActor *self);

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

This is by definition the same as `CLUTTER_ACTOR_IS_MAPPED`.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor is visibile and will be painted.

Since: 0.8

### clutter_actor_get_abs_allocation_vertices ()

    void
    clutter_actor_get_abs_allocation_vertices
                                   (ClutterActor *self,
                                    ClutterVertex verts[]);

Calculates the transformed screen coordinates of the four corners of the actor; the returned vertices relate to the ClutterActorBox coordinates as follows:

- v[0] contains (x1, y1)

- v[1] contains (x2, y1)

- v[2] contains (x1, y2)

- v[3] contains (x2, y2)

#### Parameters

self | A ClutterActor |
verts | Pointer to a location of an array of 4 ClutterVertex where to store the result. | [out][array fixed-size=4]

Since: 0.4

### clutter_actor_get_paint_volume ()

    const ClutterPaintVolume *
    clutter_actor_get_paint_volume (ClutterActor *self);

Retrieves the paint volume of the passed ClutterActor, or `NULL` when a paint volume can't be determined.

The paint volume is defined as the 3D space occupied by an actor when being painted.

This function will call the `ClutterActorClass.get_paint_volume()` virtual function of the ClutterActor class. Sub-classes of ClutterActor should not usually care about overriding the default implementation, unless they are, for instance: painting outside their allocation, or actors with a depth factor (not in terms of “depth” but real 3D depth).

Note: 2D actors overriding `ClutterActorClass.get_paint_volume()` should ensure that their volume has a depth of 0. (This will be true as long as you don't call `clutter_paint_volume_set_depth()`.)

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to a ClutterPaintVolume, or `NULL` if no volume could be determined. The returned pointer is not guaranteed to be valid across multiple frames; if you want to keep it, you will need to copy it using `clutter_paint_volume_copy()`.

[transfer none]

Since: 1.6

### clutter_actor_get_paint_box ()

    gboolean
    clutter_actor_get_paint_box (ClutterActor *self,
                                 ClutterActorBox *box);

Retrieves the paint volume of the passed ClutterActor, 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.

#### Parameters

self | a ClutterActor |
box | return location for a ClutterActorBox. | [out]

#### Returns

`TRUE` if a 2D paint box could be determined, else `FALSE`.

Since: 1.6

### clutter_actor_get_transformed_paint_volume ()

    const ClutterPaintVolume *
    clutter_actor_get_transformed_paint_volume
                                   (ClutterActor *self,
                                    ClutterActor *relative_to_ancestor);

Retrieves the 3D paint volume of an actor like `clutter_actor_get_paint_volume()` does (Please refer to the documentation of `clutter_actor_get_paint_volume()` for more details.) and it additionally transforms the paint volume into the coordinate space of `relative_to_ancestor` . (Or the stage if `NULL` is passed for `relative_to_ancestor` )

This can be used by containers that base their paint volume on the volume of their children. Such containers can query the transformed paint volume of all of its children and union them together using `clutter_paint_volume_union()`.

#### Parameters

self | a ClutterActor |
relative_to_ancestor | A ClutterActor that is an ancestor of `self` (or `NULL` for the stage) |

#### Returns

a pointer to a ClutterPaintVolume, or `NULL` if no volume could be determined. The returned pointer is not guaranteed to be valid across multiple frames; if you wish to keep it, you will have to copy it using `clutter_paint_volume_copy()`.

[transfer none]

Since: 1.6

### clutter_actor_get_default_paint_volume ()

    const ClutterPaintVolume *
    clutter_actor_get_default_paint_volume
                                   (ClutterActor *self);

Retrieves the default paint volume for `self` .

This function provides the same ClutterPaintVolume that would be computed by the default implementation inside ClutterActor of the `ClutterActorClass.get_paint_volume()` virtual function.

This function should only be used by ClutterActor subclasses that cannot chain up to the parent implementation when computing their paint volume.

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to the default ClutterPaintVolume, relative to the ClutterActor, or `NULL` if the actor could not compute a valid paint volume. The returned value is not guaranteed to be stable across multiple frames, so if you want to retain it, you will need to copy it using `clutter_paint_volume_copy()`.

[transfer none]

Since: 1.10

### clutter_actor_set_content ()

    void
    clutter_actor_set_content (ClutterActor *self,
                               ClutterContent *content);

Sets the contents of a ClutterActor.

#### Parameters

self | a ClutterActor |
content | a ClutterContent, or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_get_content ()

    ClutterContent *
    clutter_actor_get_content (ClutterActor *self);

Retrieves the contents of `self` .

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to the ClutterContent instance, or `NULL` if none was set.

[transfer none]

Since: 1.10

### clutter_actor_set_content_gravity ()

    void
    clutter_actor_set_content_gravity (ClutterActor *self,
                                       ClutterContentGravity gravity);

Sets the gravity of the ClutterContent used by `self` .

See the description of the “content-gravity” property for more information.

The “content-gravity” property is animatable.

#### Parameters

self | a ClutterActor |
gravity | the ClutterContentGravity |

Since: 1.10

### clutter_actor_get_content_gravity ()

    ClutterContentGravity
    clutter_actor_get_content_gravity (ClutterActor *self);

Retrieves the content gravity as set using `clutter_actor_set_content_gravity()`.

#### Parameters

self | a ClutterActor |

#### Returns

the content gravity

Since: 1.10

### clutter_actor_set_content_scaling_filters ()

    void
    clutter_actor_set_content_scaling_filters
                                   (ClutterActor *self,
                                    ClutterScalingFilter min_filter,
                                    ClutterScalingFilter mag_filter);

Sets the minification and magnification filter to be applied when scaling the “content” of a ClutterActor.

The “minification-filter” will be used when reducing the size of the content; the “magnification-filter” will be used when increasing the size of the content.

#### Parameters

self | a ClutterActor |
min_filter | the minification filter for the content |
mag_filter | the magnification filter for the content |

Since: 1.10

### clutter_actor_get_content_scaling_filters ()

    void
    clutter_actor_get_content_scaling_filters
                                   (ClutterActor *self,
                                    ClutterScalingFilter *min_filter,
                                    ClutterScalingFilter *mag_filter);

Retrieves the values set using `clutter_actor_set_content_scaling_filters()`.

#### Parameters

self | a ClutterActor |
min_filter | return location for the minification filter, or `NULL`. | [out][allow-none]
mag_filter | return location for the magnification filter, or `NULL`. | [out][allow-none]

Since: 1.10

### clutter_actor_set_content_repeat ()

    void
    clutter_actor_set_content_repeat (ClutterActor *self,
                                      ClutterContentRepeat repeat);

Sets the policy for repeating the “content” of a ClutterActor. The behaviour is deferred to the ClutterContent implementation.

#### Parameters

self | a ClutterActor |
repeat | the repeat policy |

Since: 1.12

### clutter_actor_get_content_repeat ()

    ClutterContentRepeat
    clutter_actor_get_content_repeat (ClutterActor *self);

Retrieves the repeat policy for a ClutterActor set by `clutter_actor_set_content_repeat()`.

#### Parameters

self | a ClutterActor |

#### Returns

the content repeat policy

Since: 1.12

### clutter_actor_get_content_box ()

    void
    clutter_actor_get_content_box (ClutterActor *self,
                                   ClutterActorBox *box);

Retrieves the bounding box for the ClutterContent of `self` .

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

If no ClutterContent 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 ClutterActor.

If the ClutterContent used by the actor has a preferred size, then it is possible to modify the content box by using the “content-gravity” property.

#### Parameters

self | a ClutterActor |
box | the return location for the bounding box for the ClutterContent. | [out caller-allocates]

Since: 1.10

### clutter_actor_set_clip ()

    void
    clutter_actor_set_clip (ClutterActor *self,
                            gfloat xoff,
                            gfloat yoff,
                            gfloat width,
                            gfloat height);

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.

#### Parameters

self | A ClutterActor |
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

### clutter_actor_remove_clip ()

    void
    clutter_actor_remove_clip (ClutterActor *self);

Removes clip area from `self` .

#### Parameters

self | A ClutterActor |

### clutter_actor_has_clip ()

    gboolean
    clutter_actor_has_clip (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor has a clip area set.

Since: 0.2

### clutter_actor_get_clip ()

    void
    clutter_actor_get_clip (ClutterActor *self,
                            gfloat *xoff,
                            gfloat *yoff,
                            gfloat *width,
                            gfloat *height);

Gets the clip area for `self` , if any is set.

#### Parameters

self | a ClutterActor |
xoff | return location for the X offset of the clip rectangle, or `NULL`. | [out][allow-none]
yoff | return location for the Y offset of the clip rectangle, or `NULL`. | [out][allow-none]
width | return location for the width of the clip rectangle, or `NULL`. | [out][allow-none]
height | return location for the height of the clip rectangle, or `NULL`. | [out][allow-none]

Since: 0.6

### clutter_actor_set_clip_to_allocation ()

    void
    clutter_actor_set_clip_to_allocation (ClutterActor *self,
                                          gboolean clip_set);

Sets whether `self` should be clipped to the same size as its allocation

#### Parameters

self | a ClutterActor |
clip_set | `TRUE` to apply a clip tracking the allocation |

Since: 1.4

### clutter_actor_get_clip_to_allocation ()

    gboolean
    clutter_actor_get_clip_to_allocation (ClutterActor *self);

Retrieves the value set using `clutter_actor_set_clip_to_allocation()`

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the ClutterActor is clipped to its allocation

Since: 1.4

### clutter_actor_set_opacity ()

    void
    clutter_actor_set_opacity (ClutterActor *self,
                               guint8 opacity);

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

The “opacity” property is animatable.

#### Parameters

self | A ClutterActor |
opacity | New opacity value for the actor. |

### clutter_actor_get_opacity ()

    guint8
    clutter_actor_get_opacity (ClutterActor *self);

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()`.

#### Parameters

self | a ClutterActor |

#### Returns

the opacity of the actor

### clutter_actor_set_opacity_override ()

    void
    clutter_actor_set_opacity_override (ClutterActor *self,
                                        gint opacity);

Allows overriding the calculated paint opacity (as returned by `clutter_actor_get_paint_opacity()`). This is used internally by ClutterClone and ClutterOffscreenEffect, and should be used by actors that need to mimick those.

In almost all cases this should not used by applications.

#### Parameters

self | a ClutterActor |
opacity | the override opacity value, or -1 to reset |

Stability Level: Unstable

### clutter_actor_get_opacity_override ()

    gint
    clutter_actor_get_opacity_override (ClutterActor *self);

See `clutter_actor_set_opacity_override()`

#### Parameters

self | a ClutterActor |

#### Returns

the override value for the actor's opacity, or -1 if no override is set.

Since: 1.22

Stability Level: Unstable

### clutter_actor_set_offscreen_redirect ()

    void
    clutter_actor_set_offscreen_redirect (ClutterActor *self,
                                          ClutterOffscreenRedirect redirect);

Defines the circumstances where the actor should be redirected into an offscreen image. The offscreen image is used to flatten the actor into a single image while painting for two main reasons. Firstly, when the actor is painted a second time without any of its contents changing it can simply repaint the cached image without descending further down the actor hierarchy. Secondly, it will make the opacity look correct even if there are overlapping primitives in the actor.

Caching the actor could in some cases be a performance win and in some cases be a performance lose so it is important to determine which value is right for an actor before modifying this value. For example, there is never any reason to flatten an actor that is just a single texture (such as a ClutterTexture) because it is effectively already cached in an image so the offscreen would be redundant. Also if the actor contains primitives that are far apart with a large transparent area in the middle (such as a large CluterGroup with a small actor in the top left and a small actor in the bottom right) then the cached image will contain the entire image of the large area and the paint will waste time blending all of the transparent pixels in the middle.

The default method of implementing opacity on a container simply forwards on the opacity to all of the children. If the children are overlapping then it will appear as if they are two separate glassy objects and there will be a break in the color where they overlap. By redirecting to an offscreen buffer it will be as if the two opaque objects are combined into one and then made transparent which is usually what is expected.

The image below demonstrates the difference between redirecting and not. The image shows two Clutter groups, each containing a red and a green rectangle which overlap. The opacity on the group is set to 128 (which is 50%). When the offscreen redirect is not used, the red rectangle can be seen through the blue rectangle as if the two rectangles were separately transparent. When the redirect is used the group as a whole is transparent instead so the red rectangle is not visible where they overlap.

Figure 1. Sample of using an offscreen redirect for transparency

The default value for this property is 0, so we effectively will never redirect an actor offscreen by default. This means that there are times that transparent actors may look glassy as described above. The reason this is the default is because there is a performance trade off between quality and performance here. In many cases the default form of glassy opacity looks good enough, but if it's not you will need to set the `CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY` flag to enable redirection for opacity.

Custom actors that don't contain any overlapping primitives are recommended to override the `has_overlaps()` virtual to return `FALSE` for maximum efficiency.

#### Parameters

self | A ClutterActor |
redirect | New offscreen redirect flags for the actor. |

Since: 1.8

### clutter_actor_get_offscreen_redirect ()

    ClutterOffscreenRedirect
    clutter_actor_get_offscreen_redirect (ClutterActor *self);

Retrieves whether to redirect the actor to an offscreen buffer, as set by `clutter_actor_set_offscreen_redirect()`.

#### Parameters

self | a ClutterActor |

#### Returns

the value of the offscreen-redirect property of the actor

Since: 1.8

### clutter_actor_is_in_clone_paint ()

    gboolean
    clutter_actor_is_in_clone_paint (ClutterActor *self);

Checks whether `self` is being currently painted by a ClutterClone

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

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the ClutterActor is currently being painted by a ClutterClone, and `FALSE` otherwise

Since: 1.0

### clutter_actor_add_child ()

    void
    clutter_actor_add_child (ClutterActor *self,
                             ClutterActor *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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor |

Since: 1.10

### clutter_actor_insert_child_above ()

    void
    clutter_actor_insert_child_above (ClutterActor *self,
                                      ClutterActor *child,
                                      ClutterActor *sibling);

Inserts `child` into the list of children of `self` , above another child of `self` or, if `sibling` is `NULL`, 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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor |
sibling | a child of `self` , or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_insert_child_at_index ()

    void
    clutter_actor_insert_child_at_index (ClutterActor *self,
                                         ClutterActor *child,
                                         gint 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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor |
index_ | the index |

Since: 1.10

### clutter_actor_insert_child_below ()

    void
    clutter_actor_insert_child_below (ClutterActor *self,
                                      ClutterActor *child,
                                      ClutterActor *sibling);

Inserts `child` into the list of children of `self` , below another child of `self` or, if `sibling` is `NULL`, 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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor |
sibling | a child of `self` , or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_replace_child ()

    void
    clutter_actor_replace_child (ClutterActor *self,
                                 ClutterActor *old_child,
                                 ClutterActor *new_child);

Replaces `old_child` with `new_child` in the list of children of `self` .

#### Parameters

self | a ClutterActor |
old_child | the child of `self` to replace |
new_child | the ClutterActor to replace `old_child` |

Since: 1.10

### clutter_actor_remove_child ()

    void
    clutter_actor_remove_child (ClutterActor *self,
                                ClutterActor *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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor |

Since: 1.10

### clutter_actor_remove_all_children ()

    void
    clutter_actor_remove_all_children (ClutterActor *self);

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()`.

#### Parameters

self | a ClutterActor |

Since: 1.10

### clutter_actor_destroy_all_children ()

    void
    clutter_actor_destroy_all_children (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

Since: 1.10

### clutter_actor_get_first_child ()

    ClutterActor *
    clutter_actor_get_first_child (ClutterActor *self);

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.

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to a ClutterActor, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_get_next_sibling ()

    ClutterActor *
    clutter_actor_get_next_sibling (ClutterActor *self);

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.

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to a ClutterActor, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_get_previous_sibling ()

    ClutterActor *
    clutter_actor_get_previous_sibling (ClutterActor *self);

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.

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to a ClutterActor, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_get_last_child ()

    ClutterActor *
    clutter_actor_get_last_child (ClutterActor *self);

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.

#### Parameters

self | a ClutterActor |

#### Returns

a pointer to a ClutterActor, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_get_child_at_index ()

    ClutterActor *
    clutter_actor_get_child_at_index (ClutterActor *self,
                                      gint index_);

Retrieves the actor at the given `index_` inside the list of children of `self` .

#### Parameters

self | a ClutterActor |
index_ | the position in the list of children |

#### Returns

a pointer to a ClutterActor, or `NULL`.

[transfer none]

Since: 1.10

### clutter_actor_get_children ()

    GList *
    clutter_actor_get_children (ClutterActor *self);

Retrieves the list of children of `self` .

#### Parameters

self | a ClutterActor |

#### Returns

A newly allocated GList of ClutterActors. Use `g_list_free()` when done.

[transfer container][element-type ClutterActor]

Since: 1.10

### clutter_actor_get_n_children ()

    gint
    clutter_actor_get_n_children (ClutterActor *self);

Retrieves the number of children of `self` .

#### Parameters

self | a ClutterActor |

#### Returns

the number of children of an actor

Since: 1.10

### clutter_actor_get_parent ()

    ClutterActor *
    clutter_actor_get_parent (ClutterActor *self);

Retrieves the parent of `self` .

#### Parameters

self | A ClutterActor |

#### Returns

The ClutterActor parent, or `NULL` if no parent is set.

[transfer none]

### clutter_actor_set_child_above_sibling ()

    void
    clutter_actor_set_child_above_sibling (ClutterActor *self,
                                           ClutterActor *child,
                                           ClutterActor *sibling);

Sets `child` to be above `sibling` in the list of children of `self` .

If `sibling` is `NULL`, `child` will be the new last child of `self` .

This function is logically equivalent to removing `child` and using `clutter_actor_insert_child_above()`, but it will not emit signals or change state on `child` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor child of `self` |
sibling | a ClutterActor child of `self` , or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_set_child_at_index ()

    void
    clutter_actor_set_child_at_index (ClutterActor *self,
                                      ClutterActor *child,
                                      gint 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` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor child of `self` |
index_ | the new index for `child` |

Since: 1.10

### clutter_actor_set_child_below_sibling ()

    void
    clutter_actor_set_child_below_sibling (ClutterActor *self,
                                           ClutterActor *child,
                                           ClutterActor *sibling);

Sets `child` to be below `sibling` in the list of children of `self` .

If `sibling` is `NULL`, `child` will be the new first child of `self` .

This function is logically equivalent to removing `self` and using `clutter_actor_insert_child_below()`, but it will not emit signals or change state on `child` .

#### Parameters

self | a ClutterActor |
child | a ClutterActor child of `self` |
sibling | a ClutterActor child of `self` , or `NULL`. | [allow-none]

Since: 1.10

### clutter_actor_contains ()

    gboolean
    clutter_actor_contains (ClutterActor *self,
                            ClutterActor *descendant);

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

#### Parameters

self | A ClutterActor |
descendant | A ClutterActor, possibly contained in `self` |

#### Returns

whether `descendent` is contained within `self`

Since: 1.4

### clutter_actor_get_stage ()

    ClutterActor *
    clutter_actor_get_stage (ClutterActor *actor);

Retrieves the ClutterStage where `actor` is contained.

#### Parameters

actor | a ClutterActor |

#### Returns

the stage containing the actor, or `NULL`.

[transfer none][type Clutter.Stage]

Since: 0.8

### clutter_actor_iter_init ()

    void
    clutter_actor_iter_init (ClutterActorIter *iter,
                             ClutterActor *root);

Initializes a ClutterActorIter, which can then be used to iterate efficiently over a section of the scene graph, and associates it with `root` .

Modifying the scene graph section that contains `root` will invalidate the iterator.

    1
    2
    3
    4
    5
    6
    7
    8

    ClutterActorIter iter;
    ClutterActor *child;

    clutter_actor_iter_init (&iter, container);
    while (clutter_actor_iter_next (&iter, &child))
      {
        // do something with child
      }

#### Parameters

iter | a ClutterActorIter |
root | a ClutterActor |

Since: 1.10

### clutter_actor_iter_is_valid ()

    gboolean
    clutter_actor_iter_is_valid (const ClutterActorIter *iter);

Checks whether a ClutterActorIter is still valid.

An iterator is considered valid if it has been initialized, and if the ClutterActor that it refers to hasn't been modified after the initialization.

#### Parameters

iter | a ClutterActorIter |

#### Returns

`TRUE` if the iterator is valid, and `FALSE` otherwise

Since: 1.12

### clutter_actor_iter_next ()

    gboolean
    clutter_actor_iter_next (ClutterActorIter *iter,
                             ClutterActor **child);

Advances the `iter` and retrieves the next child of the root ClutterActor that was used to initialize the ClutterActorIterator.

If the iterator can advance, this function returns `TRUE` and sets the `child` argument.

If the iterator cannot advance, this function returns `FALSE`, and the contents of `child` are undefined.

#### Parameters

iter | a ClutterActorIter |
child | return location for a ClutterActor. | [out][transfer none]

#### Returns

`TRUE` if the iterator could advance, and `FALSE` otherwise.

Since: 1.10

### clutter_actor_iter_prev ()

    gboolean
    clutter_actor_iter_prev (ClutterActorIter *iter,
                             ClutterActor **child);

Advances the `iter` and retrieves the previous child of the root ClutterActor that was used to initialize the ClutterActorIterator.

If the iterator can advance, this function returns `TRUE` and sets the `child` argument.

If the iterator cannot advance, this function returns `FALSE`, and the contents of `child` are undefined.

#### Parameters

iter | a ClutterActorIter |
child | return location for a ClutterActor. | [out][transfer none]

#### Returns

`TRUE` if the iterator could advance, and `FALSE` otherwise.

Since: 1.10

### clutter_actor_iter_remove ()

    void
    clutter_actor_iter_remove (ClutterActorIter *iter);

Safely removes the ClutterActor currently pointer to by the iterator from its parent.

This function can only be called after `clutter_actor_iter_next()` or `clutter_actor_iter_prev()` returned `TRUE`, and cannot be called more than once for the same actor.

This function will call `clutter_actor_remove_child()` internally.

#### Parameters

iter | a ClutterActorIter |

Since: 1.10

### clutter_actor_iter_destroy ()

    void
    clutter_actor_iter_destroy (ClutterActorIter *iter);

Safely destroys the ClutterActor currently pointer to by the iterator from its parent.

This function can only be called after `clutter_actor_iter_next()` or `clutter_actor_iter_prev()` returned `TRUE`, and cannot be called more than once for the same actor.

This function will call `clutter_actor_destroy()` internally.

#### Parameters

iter | a ClutterActorIter |

Since: 1.10

### ClutterActorCreateChildFunc ()

    ClutterActor *
    (*ClutterActorCreateChildFunc) (gpointer item,
                                    gpointer user_data);

Creates a ClutterActor using the `item` in the model.

The usual way to implement this function is to create a ClutterActor instance and then bind the GObject properties to the actor properties of interest, using `g_object_bind_property()`. This way, when the `item` in the GListModel changes, the ClutterActor changes as well.

#### Parameters

item | the item in the model. | [type GObject]
user_data | Data passed to `clutter_actor_bind_model()` |

#### Returns

The newly created child ClutterActor.

[transfer full]

Since: 1.24

### clutter_actor_bind_model ()

    void
    clutter_actor_bind_model (ClutterActor *self,
                              GListModel *model,
                              ClutterActorCreateChildFunc create_child_func,
                              gpointer user_data,
                              GDestroyNotify notify);

Binds a GListModel to a ClutterActor.

If the ClutterActor was already bound to a GListModel, the previous binding is destroyed.

The existing children of ClutterActor are destroyed when setting a model, and new children are created and added, representing the contents of the `model` . The ClutterActor is updated whenever the `model` changes. If `model` is `NULL`, the ClutterActor is left empty.

When a ClutterActor is bound to a model, adding and removing children directly is undefined behaviour.

#### Parameters

self | a ClutterActor |
model | a GListModel. | [nullable]
create_child_func | a function that creates ClutterActor instances from the contents of the `model` |
user_data | user data passed to `create_child_func` |
notify | function called when unsetting the `model` |

Since: 1.24

### clutter_actor_bind_model_with_properties ()

    void
    clutter_actor_bind_model_with_properties
                                   (ClutterActor *self,
                                    GListModel *model,
                                    GType child_type,
                                    const char *first_model_property,
                                    ...);

Binds a GListModel to a ClutterActor.

Unlike `clutter_actor_bind_model()`, this function automatically creates a child ClutterActor of type `child_type` , and binds properties on the items inside the `model` to the corresponding properties on the child, for instance:

    1
    2
    3
    4
    5
    6
    7

    clutter_actor_bind_model_with_properties (actor, model,
                                              MY_TYPE_CHILD_VIEW,
                                              "label", "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE,
                                              "icon", "image", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE,
                                              "selected", "selected", G_BINDING_BIDIRECTIONAL,
                                              "active", "active", G_BINDING_BIDIRECTIONAL,
                                              NULL);

is the equivalent of calling `clutter_actor_bind_model()` with a ClutterActorCreateChildFunc of:

    1
    2
    3
    4
    5
    6
    7
    8

    ClutterActor *res = g_object_new (MY_TYPE_CHILD_VIEW, NULL);

    g_object_bind_property (item, "label", res, "text", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE);
    g_object_bind_property (item, "icon", res, "image", G_BINDING_DEFAULT | G_BINDING_SYNC_CREATE);
    g_object_bind_property (item, "selected", res, "selected", G_BINDING_BIDIRECTIONAL);
    g_object_bind_property (item, "active", res, "active", G_BINDING_BIDIRECTIONAL);

    return res;

If the ClutterActor was already bound to a GListModel, the previous binding is destroyed.

When a ClutterActor is bound to a model, adding and removing children directly is undefined behaviour.

See also: `clutter_actor_bind_model()`

#### Parameters

self | a ClutterActor |
model | a GListModel |
child_type | the type of ClutterActor to use when creating children mapping to items inside the `model` |
first_model_property | the first property of `model` to bind |
... | tuples of property names on the `model` , on the child, and the GBindingFlags used to bind them, terminated by `NULL` |

Since: 1.24

### clutter_actor_save_easing_state ()

    void
    clutter_actor_save_easing_state (ClutterActor *self);

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

New transitions created after calling this function will inherit the duration, easing mode, and delay of the new easing state; this also applies to transitions modified in flight.

#### Parameters

self | a ClutterActor |

Since: 1.10

### clutter_actor_restore_easing_state ()

    void
    clutter_actor_restore_easing_state (ClutterActor *self);

Restores the easing state as it was prior to a call to `clutter_actor_save_easing_state()`.

#### Parameters

self | a ClutterActor |

Since: 1.10

### clutter_actor_set_easing_duration ()

    void
    clutter_actor_set_easing_duration (ClutterActor *self,
                                       guint msecs);

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

#### Parameters

self | a ClutterActor |
msecs | the duration of the easing, or `NULL` |

Since: 1.10

### clutter_actor_get_easing_duration ()

    guint
    clutter_actor_get_easing_duration (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

#### Returns

the duration of the tweening, in milliseconds

Since: 1.10

### clutter_actor_set_easing_mode ()

    void
    clutter_actor_set_easing_mode (ClutterActor *self,
                                   ClutterAnimationMode mode);

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

#### Parameters

self | a ClutterActor |
mode | an easing mode, excluding `CLUTTER_CUSTOM_MODE` |

Since: 1.10

### clutter_actor_get_easing_mode ()

    ClutterAnimationMode
    clutter_actor_get_easing_mode (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

#### Returns

an easing mode

Since: 1.10

### clutter_actor_set_easing_delay ()

    void
    clutter_actor_set_easing_delay (ClutterActor *self,
                                    guint msecs);

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

#### Parameters

self | a ClutterActor |
msecs | the delay before the start of the tweening, in milliseconds |

Since: 1.10

### clutter_actor_get_easing_delay ()

    guint
    clutter_actor_get_easing_delay (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

#### Returns

a delay, in milliseconds

Since: 1.10

### clutter_actor_get_transition ()

    ClutterTransition *
    clutter_actor_get_transition (ClutterActor *self,
                                  const char *name);

Retrieves the ClutterTransition of a ClutterActor by using the transition `name` .

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

    1
    2
    3
    4
    5
    6
    7

    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, "stopped",
                      G_CALLBACK (on_transition_stopped),
                      actor);

will call the `on_transition_stopped` callback when the transition is finished.

If you just want to get notifications of the completion of a transition, you should use the “transition-stopped” signal, using the transition name as the signal detail.

#### Parameters

self | a ClutterActor |
name | the name of the transition |

#### Returns

a ClutterTransition, or `NULL` is none was found to match the passed name; the returned instance is owned by Clutter and it should not be freed.

[transfer none]

Since: 1.10

### clutter_actor_add_transition ()

    void
    clutter_actor_add_transition (ClutterActor *self,
                                  const char *name,
                                  ClutterTransition *transition);

Adds a `transition` to the ClutterActor's list of animations.

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

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.

#### Parameters

self | a ClutterActor |
name | the name of the transition to add |
transition | the ClutterTransition to add |

Since: 1.10

### clutter_actor_remove_transition ()

    void
    clutter_actor_remove_transition (ClutterActor *self,
                                     const char *name);

Removes the transition stored inside a ClutterActor 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 ClutterActor.

#### Parameters

self | a ClutterActor |
name | the name of the transition to remove |

Since: 1.10

### clutter_actor_remove_all_transitions ()

    void
    clutter_actor_remove_all_transitions (ClutterActor *self);

Removes all transitions associated to `self` .

#### Parameters

self | a ClutterActor |

Since: 1.10

### clutter_actor_set_reactive ()

    void
    clutter_actor_set_reactive (ClutterActor *actor,
                                gboolean reactive);

Sets `actor` as reactive. Reactive actors will receive events.

#### Parameters

actor | a ClutterActor |
reactive | whether the actor should be reactive to events |

Since: 0.6

### clutter_actor_get_reactive ()

    gboolean
    clutter_actor_get_reactive (ClutterActor *actor);

Checks whether `actor` is marked as reactive.

#### Parameters

actor | a ClutterActor |

#### Returns

`TRUE` if the actor is reactive

Since: 0.6

### clutter_actor_has_key_focus ()

    gboolean
    clutter_actor_has_key_focus (ClutterActor *self);

Checks whether `self` is the ClutterActor that has key focus

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor has key focus, and `FALSE` otherwise

Since: 1.4

### clutter_actor_grab_key_focus ()

    void
    clutter_actor_grab_key_focus (ClutterActor *self);

Sets the key focus of the ClutterStage including `self` to this ClutterActor.

#### Parameters

self | a ClutterActor |

Since: 1.0

### clutter_actor_has_pointer ()

    gboolean
    clutter_actor_has_pointer (ClutterActor *self);

Checks whether an actor contains the pointer of a ClutterInputDevice

#### Parameters

self | a ClutterActor |

#### Returns

`TRUE` if the actor contains the pointer, and `FALSE` otherwise

Since: 1.2

### clutter_actor_get_pango_context ()

    PangoContext *
    clutter_actor_get_pango_context (ClutterActor *self);

Retrieves the PangoContext for `self` . The actor's PangoContext is already configured using the appropriate font map, resolution and font options.

Unlike `clutter_actor_create_pango_context()`, this context is owend by the ClutterActor and it will be updated each time the options stored by the ClutterBackend change.

You can use the returned PangoContext to create a PangoLayout and render text using `cogl_pango_render_layout()` to reuse the glyphs cache also used by Clutter.

#### Parameters

self | a ClutterActor |

#### Returns

the PangoContext for a ClutterActor. The returned PangoContext is owned by the actor and should not be unreferenced by the application code.

[transfer none]

Since: 1.0

### clutter_actor_create_pango_context ()

    PangoContext *
    clutter_actor_create_pango_context (ClutterActor *self);

Creates a PangoContext for the given actor. The PangoContext is already configured using the appropriate font map, resolution and font options.

See also `clutter_actor_get_pango_context()`.

#### Parameters

self | a ClutterActor |

#### Returns

the newly created PangoContext. Use `g_object_unref()` on the returned value to deallocate its resources.

[transfer full]

Since: 1.0

### clutter_actor_create_pango_layout ()

    PangoLayout *
    clutter_actor_create_pango_layout (ClutterActor *self,
                                       const gchar *text);

Creates a new PangoLayout from the same PangoContext used by the ClutterActor. The PangoLayout is already configured with the font map, resolution and font options, and the given `text` .

If you want to keep around a PangoLayout 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.

#### Parameters

self | a ClutterActor |
text | the text to set on the PangoLayout, or `NULL`. | [allow-none]

#### Returns

the newly created PangoLayout. Use `g_object_unref()` when done.

[transfer full]

Since: 1.0

### clutter_actor_set_text_direction ()

    void
    clutter_actor_set_text_direction (ClutterActor *self,
                                      ClutterTextDirection text_dir);

Sets the ClutterTextDirection for an actor

The passed text direction must not be `CLUTTER_TEXT_DIRECTION_DEFAULT`

If `self` implements ClutterContainer then this function will recurse inside all the children of `self` (including the internal ones).

Composite actors not implementing ClutterContainer, or actors requiring special handling when the text direction changes, should connect to the “notify” signal for the “text-direction” property

#### Parameters

self | a ClutterActor |
text_dir | the text direction for `self` |

Since: 1.2

### clutter_actor_get_text_direction ()

    ClutterTextDirection
    clutter_actor_get_text_direction (ClutterActor *self);

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

#### Parameters

self | a ClutterActor |

#### Returns

the ClutterTextDirection for the actor

Since: 1.2

### clutter_actor_get_accessible ()

    AtkObject *
    clutter_actor_get_accessible (ClutterActor *self);

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

If no class-specific AtkObject implementation is available for the actor instance in question, it will inherit an AtkObject 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.

#### Parameters

self | a ClutterActor |

#### Returns

the AtkObject associated with `actor` .

[transfer none]

### clutter_actor_add_action ()

    void
    clutter_actor_add_action (ClutterActor *self,
                              ClutterAction *action);

Adds `action` to the list of actions applied to `self`

A ClutterAction can only belong to one actor at a time

The ClutterActor will hold a reference on `action` until either `clutter_actor_remove_action()` or `clutter_actor_clear_actions()` is called

#### Parameters

self | a ClutterActor |
action | a ClutterAction |

Since: 1.4

### clutter_actor_add_action_with_name ()

    void
    clutter_actor_add_action_with_name (ClutterActor *self,
                                        const gchar *name,
                                        ClutterAction *action);

A convenience function for setting the name of a ClutterAction while adding it to the list of actions applied to `self`

This function is the logical equivalent of:

    1
    2

    clutter_actor_meta_set_name (CLUTTER_ACTOR_META (action), name);
    clutter_actor_add_action (self, action);

#### Parameters

self | a ClutterActor |
name | the name to set on the action |
action | a ClutterAction |

Since: 1.4

### clutter_actor_remove_action ()

    void
    clutter_actor_remove_action (ClutterActor *self,
                                 ClutterAction *action);

Removes `action` from the list of actions applied to `self`

The reference held by `self` on the ClutterAction will be released

#### Parameters

self | a ClutterActor |
action | a ClutterAction |

Since: 1.4

### clutter_actor_remove_action_by_name ()

    void
    clutter_actor_remove_action_by_name (ClutterActor *self,
                                         const gchar *name);

Removes the ClutterAction with the given name from the list of actions applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the action to remove |

Since: 1.4

### clutter_actor_has_actions ()

    gboolean
    clutter_actor_has_actions (ClutterActor *self);

Returns whether the actor has any actions applied.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor has any actions, `FALSE` otherwise

Since: 1.10

### clutter_actor_get_actions ()

    GList *
    clutter_actor_get_actions (ClutterActor *self);

Retrieves the list of actions applied to `self`

#### Parameters

self | a ClutterActor |

#### Returns

a copy of the list of ClutterActions. The contents of the list are owned by the ClutterActor. Use `g_list_free()` to free the resources allocated by the returned GList.

[transfer container][element-type Clutter.Action]

Since: 1.4

### clutter_actor_get_action ()

    ClutterAction *
    clutter_actor_get_action (ClutterActor *self,
                              const gchar *name);

Retrieves the ClutterAction with the given name in the list of actions applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the action to retrieve |

#### Returns

a ClutterAction for the given name, or `NULL`. The returned ClutterAction is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4

### clutter_actor_clear_actions ()

    void
    clutter_actor_clear_actions (ClutterActor *self);

Clears the list of actions applied to `self`

#### Parameters

self | a ClutterActor |

Since: 1.4

### clutter_actor_add_constraint ()

    void
    clutter_actor_add_constraint (ClutterActor *self,
                                  ClutterConstraint *constraint);

Adds `constraint` to the list of ClutterConstraints applied to `self`

The ClutterActor will hold a reference on the `constraint` until either `clutter_actor_remove_constraint()` or `clutter_actor_clear_constraints()` is called.

#### Parameters

self | a ClutterActor |
constraint | a ClutterConstraint |

Since: 1.4

### clutter_actor_add_constraint_with_name ()

    void
    clutter_actor_add_constraint_with_name
                                   (ClutterActor *self,
                                    const gchar *name,
                                    ClutterConstraint *constraint);

A convenience function for setting the name of a ClutterConstraint while adding it to the list of constraints applied to `self`

This function is the logical equivalent of:

    1
    2

    clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), name);
    clutter_actor_add_constraint (self, constraint);

#### Parameters

self | a ClutterActor |
name | the name to set on the constraint |
constraint | a ClutterConstraint |

Since: 1.4

### clutter_actor_remove_constraint ()

    void
    clutter_actor_remove_constraint (ClutterActor *self,
                                     ClutterConstraint *constraint);

Removes `constraint` from the list of constraints applied to `self`

The reference held by `self` on the ClutterConstraint will be released

#### Parameters

self | a ClutterActor |
constraint | a ClutterConstraint |

Since: 1.4

### clutter_actor_remove_constraint_by_name ()

    void
    clutter_actor_remove_constraint_by_name
                                   (ClutterActor *self,
                                    const gchar *name);

Removes the ClutterConstraint with the given name from the list of constraints applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the constraint to remove |

Since: 1.4

### clutter_actor_has_constraints ()

    gboolean
    clutter_actor_has_constraints (ClutterActor *self);

Returns whether the actor has any constraints applied.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor has any constraints, `FALSE` otherwise

Since: 1.10

### clutter_actor_get_constraints ()

    GList *
    clutter_actor_get_constraints (ClutterActor *self);

Retrieves the list of constraints applied to `self`

#### Parameters

self | a ClutterActor |

#### Returns

a copy of the list of ClutterConstraints. The contents of the list are owned by the ClutterActor. Use `g_list_free()` to free the resources allocated by the returned GList.

[transfer container][element-type Clutter.Constraint]

Since: 1.4

### clutter_actor_get_constraint ()

    ClutterConstraint *
    clutter_actor_get_constraint (ClutterActor *self,
                                  const gchar *name);

Retrieves the ClutterConstraint with the given name in the list of constraints applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the constraint to retrieve |

#### Returns

a ClutterConstraint for the given name, or `NULL`. The returned ClutterConstraint is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4

### clutter_actor_clear_constraints ()

    void
    clutter_actor_clear_constraints (ClutterActor *self);

Clears the list of constraints applied to `self`

#### Parameters

self | a ClutterActor |

Since: 1.4

### clutter_actor_add_effect ()

    void
    clutter_actor_add_effect (ClutterActor *self,
                              ClutterEffect *effect);

Adds `effect` to the list of ClutterEffects applied to `self`

The ClutterActor will hold a reference on the `effect` until either `clutter_actor_remove_effect()` or `clutter_actor_clear_effects()` is called.

Note that as ClutterEffect is initially unowned, `clutter_actor_add_effect()` will sink any floating reference on `effect` .

#### Parameters

self | a ClutterActor |
effect | a ClutterEffect |

Since: 1.4

### clutter_actor_add_effect_with_name ()

    void
    clutter_actor_add_effect_with_name (ClutterActor *self,
                                        const gchar *name,
                                        ClutterEffect *effect);

A convenience function for setting the name of a ClutterEffect while adding it to the list of effects applied to `self` .

Note that as ClutterEffect is initially unowned, `clutter_actor_add_effect_with_name()` will sink any floating reference on `effect` .

This function is the logical equivalent of:

    1
    2

    clutter_actor_meta_set_name (CLUTTER_ACTOR_META (effect), name);
    clutter_actor_add_effect (self, effect);

#### Parameters

self | a ClutterActor |
name | the name to set on the effect |
effect | a ClutterEffect |

Since: 1.4

### clutter_actor_remove_effect ()

    void
    clutter_actor_remove_effect (ClutterActor *self,
                                 ClutterEffect *effect);

Removes `effect` from the list of effects applied to `self`

The reference held by `self` on the ClutterEffect will be released

#### Parameters

self | a ClutterActor |
effect | a ClutterEffect |

Since: 1.4

### clutter_actor_remove_effect_by_name ()

    void
    clutter_actor_remove_effect_by_name (ClutterActor *self,
                                         const gchar *name);

Removes the ClutterEffect with the given name from the list of effects applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the effect to remove |

Since: 1.4

### clutter_actor_has_effects ()

    gboolean
    clutter_actor_has_effects (ClutterActor *self);

Returns whether the actor has any effects applied.

#### Parameters

self | A ClutterActor |

#### Returns

`TRUE` if the actor has any effects, `FALSE` otherwise

Since: 1.10

### clutter_actor_get_effects ()

    GList *
    clutter_actor_get_effects (ClutterActor *self);

Retrieves the ClutterEffects applied on `self` , if any

#### Parameters

self | a ClutterActor |

#### Returns

a list of ClutterEffects, or `NULL`. 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.

[transfer container][element-type Clutter.Effect]

Since: 1.4

### clutter_actor_get_effect ()

    ClutterEffect *
    clutter_actor_get_effect (ClutterActor *self,
                              const gchar *name);

Retrieves the ClutterEffect with the given name in the list of effects applied to `self`

#### Parameters

self | a ClutterActor |
name | the name of the effect to retrieve |

#### Returns

a ClutterEffect for the given name, or `NULL`. The returned ClutterEffect is owned by the actor and it should not be unreferenced directly.

[transfer none]

Since: 1.4

### clutter_actor_clear_effects ()

    void
    clutter_actor_clear_effects (ClutterActor *self);

Clears the list of effects applied to `self`

#### Parameters

self | a ClutterActor |

Since: 1.4

### clutter_actor_set_scale_full ()

    void
    clutter_actor_set_scale_full (ClutterActor *self,
                                  gdouble scale_x,
                                  gdouble scale_y,
                                  gfloat center_x,
                                  gfloat center_y);

`clutter_actor_set_scale_full` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_set_pivot_point()` to control the scale center

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.

#### Parameters

self | A ClutterActor |
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 scaling |
center_y | Y coordinate of the center of the scaling |

Since: 1.0

### clutter_actor_set_scale_with_gravity ()

    void
    clutter_actor_set_scale_with_gravity (ClutterActor *self,
                                          gdouble scale_x,
                                          gdouble scale_y,
                                          ClutterGravity gravity);

`clutter_actor_set_scale_with_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_set_pivot_point()` to set the scale center using normalized coordinates instead.

Scales an actor with the given factors around the given center point. The center point is specified as one of the compass directions in ClutterGravity. For example, setting it to north will cause the top of the actor to remain unchanged and the rest of the actor to expand left, right and downwards.

The “scale-x” and “scale-y” properties are animatable.

#### Parameters

self | A ClutterActor |
scale_x | double factor to scale actor by horizontally. |
scale_y | double factor to scale actor by vertically. |
gravity | the location of the scale center expressed as a compass direction. |

Since: 1.0

### clutter_actor_get_scale_center ()

    void
    clutter_actor_get_scale_center (ClutterActor *self,
                                    gfloat *center_x,
                                    gfloat *center_y);

`clutter_actor_get_scale_center` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_pivot_point()` instead.

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

#### Parameters

self | A ClutterActor |
center_x | Location to store the X position of the scale center, or `NULL`. | [out][allow-none]
center_y | Location to store the Y position of the scale center, or `NULL`. | [out][allow-none]

Since: 1.0

### clutter_actor_get_scale_gravity ()

    ClutterGravity
    clutter_actor_get_scale_gravity (ClutterActor *self);

`clutter_actor_get_scale_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_pivot_point()` instead.

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

#### Parameters

self | A ClutterActor |

#### Returns

the scale gravity

Since: 1.0

### clutter_actor_set_depth ()

    void
    clutter_actor_set_depth (ClutterActor *self,
                             gfloat depth);

`clutter_actor_set_depth` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_set_z_position()` instead.

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()`.

#### Parameters

self | a ClutterActor |
depth | Z co-ord |

### clutter_actor_get_depth ()

    gfloat
    clutter_actor_get_depth (ClutterActor *self);

`clutter_actor_get_depth` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_z_position()` instead.

Retrieves the depth of `self` .

#### Parameters

self | a ClutterActor |

#### Returns

the depth of the actor

### clutter_actor_push_internal ()

    void
    clutter_actor_push_internal (ClutterActor *self);

`clutter_actor_push_internal` has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API, and ClutterActor implements the ClutterContainer interface, so this function is only useful for legacy containers overriding the default implementation.

Should be used by actors implementing the ClutterContainer and with internal children added through `clutter_actor_set_parent()`, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25

    static void
    my_actor_init (MyActor *self)
    {
      self->priv = my_actor_get_instance_private (self);

      clutter_actor_push_internal (CLUTTER_ACTOR (self));

      // calling clutter_actor_set_parent() now will result in
      // the internal flag being set on a child of MyActor

      // internal child - a background texture
      self->priv->background_tex = clutter_texture_new ();
      clutter_actor_set_parent (self->priv->background_tex,
                                CLUTTER_ACTOR (self));

      // internal child - a label
      self->priv->label = clutter_text_new ();
      clutter_actor_set_parent (self->priv->label,
                                CLUTTER_ACTOR (self));

      clutter_actor_pop_internal (CLUTTER_ACTOR (self));

      // calling clutter_actor_set_parent() now will not result in
      // the internal flag being set on a child of MyActor
    }

This function will be used by Clutter to toggle an "internal child" flag whenever `clutter_actor_set_parent()` is called; internal children are handled differently by Clutter, specifically when destroying their parent.

Call `clutter_actor_pop_internal()` when you finished adding internal children.

Nested calls to `clutter_actor_push_internal()` are allowed, but each one must by followed by a `clutter_actor_pop_internal()` call.

#### Parameters

self | a ClutterActor |

Since: 1.2

### clutter_actor_pop_internal ()

    void
    clutter_actor_pop_internal (ClutterActor *self);

`clutter_actor_pop_internal` has been deprecated since version 1.10 and should not be used in newly-written code.

All children of an actor are accessible through the ClutterActor API. This function is only useful for legacy containers overriding the default implementation of the ClutterContainer interface.

Disables the effects of `clutter_actor_push_internal()`.

#### Parameters

self | a ClutterActor |

Since: 1.2

### clutter_actor_set_parent ()

    void
    clutter_actor_set_parent (ClutterActor *self,
                              ClutterActor *parent);

`clutter_actor_set_parent` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_add_child()` instead.

Sets the parent of `self` to `parent` .

This function will result in `parent` acquiring a reference on `self` , eventually by sinking its floating reference first. The reference will be released by `clutter_actor_unparent()`.

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

#### Parameters

self | A ClutterActor |
parent | A new ClutterActor parent |

### clutter_actor_reparent ()

    void
    clutter_actor_reparent (ClutterActor *self,
                            ClutterActor *new_parent);

`clutter_actor_reparent` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_remove_child()` and `clutter_actor_add_child()` instead; remember to take a reference on the actor being removed before calling `clutter_actor_remove_child()` to avoid the reference count dropping to zero and the actor being destroyed.

Resets the parent actor of `self` .

This function is logically equivalent to calling `clutter_actor_unparent()` and `clutter_actor_set_parent()`, but more efficiently implemented, as it ensures the child is not finalized when unparented, and emits the “parent-set” signal only once.

In reality, calling this function is less useful than it sounds, as some application code may rely on changes in the intermediate state between removal and addition of the actor from its old parent to the `new_parent` . Thus, it is strongly encouraged to avoid using this function in application code.

#### Parameters

self | a ClutterActor |
new_parent | the new ClutterActor parent |

Since: 0.2

### clutter_actor_unparent ()

    void
    clutter_actor_unparent (ClutterActor *self);

`clutter_actor_unparent` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_remove_child()` instead.

Removes the parent of `self` .

This will cause the parent of `self` to release the reference acquired when calling `clutter_actor_set_parent()`, so if you want to keep `self` you will have to acquire a reference of your own, through `g_object_ref()`.

This function should only be called by legacy ClutterActors implementing the ClutterContainer interface.

#### Parameters

self | a ClutterActor |

Since: 0.2

### clutter_actor_raise ()

    void
    clutter_actor_raise (ClutterActor *self,
                         ClutterActor *below);

`clutter_actor_raise` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_above_sibling()` instead.

Puts `self` above `below` .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface

This function calls `clutter_container_raise_child()` internally.

#### Parameters

self | A ClutterActor |
below | A ClutterActor to raise above. | [allow-none]

### clutter_actor_lower ()

    void
    clutter_actor_lower (ClutterActor *self,
                         ClutterActor *above);

`clutter_actor_lower` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_below_sibling()` instead.

Puts `self` below `above` .

Both actors must have the same parent, and the parent must implement the ClutterContainer interface.

This function calls `clutter_container_lower_child()` internally.

#### Parameters

self | A ClutterActor |
above | A ClutterActor to lower below. | [allow-none]

### clutter_actor_raise_top ()

    void
    clutter_actor_raise_top (ClutterActor *self);

`clutter_actor_raise_top` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_above_sibling()` with a `NULL` sibling, instead.

Raises `self` to the top.

This function calls `clutter_actor_raise()` internally.

#### Parameters

self | A ClutterActor |

### clutter_actor_lower_bottom ()

    void
    clutter_actor_lower_bottom (ClutterActor *self);

`clutter_actor_lower_bottom` has been deprecated since version 1.10 and should not be used in newly-written code.

Use `clutter_actor_set_child_below_sibling()` with a `NULL` sibling, instead.

Lowers `self` to the bottom.

This function calls `clutter_actor_lower()` internally.

#### Parameters

self | A ClutterActor |

### clutter_actor_set_shader ()

    gboolean
    clutter_actor_set_shader (ClutterActor *self,
                              ClutterShader *shader);

`clutter_actor_set_shader` has been deprecated since version 1.8 and should not be used in newly-written code.

Use ClutterShaderEffect and `clutter_actor_add_effect()` instead.

Sets the ClutterShader to be used when rendering `self` .

If `shader` is `NULL` this function will unset any currently set shader for the actor.

Any ClutterEffect applied to `self` will take the precedence over the ClutterShader set using this function.

#### Parameters

self | a ClutterActor |
shader | a ClutterShader or `NULL` to unset the shader. | [allow-none]

#### Returns

`TRUE` if the shader was successfully applied or removed

Since: 0.6

### clutter_actor_get_shader ()

    ClutterShader *
    clutter_actor_get_shader (ClutterActor *self);

`clutter_actor_get_shader` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_actor_get_effect()` instead.

Queries the currently set ClutterShader on `self` .

#### Parameters

self | a ClutterActor |

#### Returns

The currently set ClutterShader or `NULL` if no shader is set.

[transfer none]

Since: 0.6

### clutter_actor_set_shader_param ()

    void
    clutter_actor_set_shader_param (ClutterActor *self,
                                    const gchar *param,
                                    const GValue *value);

`clutter_actor_set_shader_param` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_shader_effect_set_uniform_value()` instead

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

#### Parameters

self | a ClutterActor |
param | the name of the parameter |
value | the value of the parameter |

Since: 1.0

### clutter_actor_set_shader_param_float ()

    void
    clutter_actor_set_shader_param_float (ClutterActor *self,
                                          const gchar *param,
                                          gfloat value);

`clutter_actor_set_shader_param_float` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_shader_effect_set_uniform()` instead

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

#### Parameters

self | a ClutterActor |
param | the name of the parameter |
value | the value of the parameter |

Since: 0.8

### clutter_actor_set_shader_param_int ()

    void
    clutter_actor_set_shader_param_int (ClutterActor *self,
                                        const gchar *param,
                                        gint value);

`clutter_actor_set_shader_param_int` has been deprecated since version 1.8 and should not be used in newly-written code.

Use `clutter_shader_effect_set_uniform()` instead

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

#### Parameters

self | a ClutterActor |
param | the name of the parameter |
value | the value of the parameter |

Since: 0.8

### clutter_actor_set_anchor_point ()

    void
    clutter_actor_set_anchor_point (ClutterActor *self,
                                    gfloat anchor_x,
                                    gfloat anchor_y);

`clutter_actor_set_anchor_point` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

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.

#### Parameters

self | a ClutterActor |
anchor_x | X coordinate of the anchor point |
anchor_y | Y coordinate of the anchor point |

Since: 0.6

### clutter_actor_get_anchor_point ()

    void
    clutter_actor_get_anchor_point (ClutterActor *self,
                                    gfloat *anchor_x,
                                    gfloat *anchor_y);

`clutter_actor_get_anchor_point` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Gets the current anchor point of the `actor` in pixels.

#### Parameters

self | a ClutterActor |
anchor_x | return location for the X coordinate of the anchor point. | [out]
anchor_y | return location for the Y coordinate of the anchor point. | [out]

Since: 0.6

### clutter_actor_set_anchor_point_from_gravity ()

    void
    clutter_actor_set_anchor_point_from_gravity
                                   (ClutterActor *self,
                                    ClutterGravity gravity);

`clutter_actor_set_anchor_point_from_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and `clutter_actor_set_translation()` instead. E.g. For `CLUTTER_GRAVITY_CENTER` set pivot_point to (0.5,0.5) and the translation to (width/2,height/2).

Sets an anchor point on the actor, based on the given gravity (this is a convenience function wrapping `clutter_actor_set_anchor_point()`).

Since version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to `CLUTTER_GRAVITY_SOUTH_EAST` and later double the size of the actor, the anchor point will move to the bottom right.

#### Parameters

self | a ClutterActor |
gravity | ClutterGravity. |

Since: 0.6

### clutter_actor_get_anchor_point_gravity ()

    ClutterGravity
    clutter_actor_get_anchor_point_gravity
                                   (ClutterActor *self);

`clutter_actor_get_anchor_point_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead.

Retrieves the anchor position expressed as a ClutterGravity. If the anchor point was specified using pixels or units this will return `CLUTTER_GRAVITY_NONE`.

#### Parameters

self | a ClutterActor |

#### Returns

the ClutterGravity used by the anchor point

Since: 1.0

### clutter_actor_move_anchor_point ()

    void
    clutter_actor_move_anchor_point (ClutterActor *self,
                                     gfloat anchor_x,
                                     gfloat anchor_y);

`clutter_actor_move_anchor_point` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and `clutter_actor_set_translation()` instead.

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.

#### Parameters

self | a ClutterActor |
anchor_x | X coordinate of the anchor point |
anchor_y | Y coordinate of the anchor point |

Since: 0.6

### clutter_actor_move_anchor_point_from_gravity ()

    void
    clutter_actor_move_anchor_point_from_gravity
                                   (ClutterActor *self,
                                    ClutterGravity gravity);

`clutter_actor_move_anchor_point_from_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” and `clutter_actor_set_translation()` instead.

Sets an anchor point on the actor based on the given gravity, adjusting the actor postion so that its relative position within its parent remains unchanged.

Since version 1.0 the anchor point will be stored as a gravity so that if the actor changes size then the anchor point will move. For example, if you set the anchor point to `CLUTTER_GRAVITY_SOUTH_EAST` and later double the size of the actor, the anchor point will move to the bottom right.

#### Parameters

self | a ClutterActor |
gravity | ClutterGravity. |

Since: 0.6

### clutter_actor_set_rotation ()

    void
    clutter_actor_set_rotation (ClutterActor *self,
                                ClutterRotateAxis axis,
                                gdouble angle,
                                gfloat x,
                                gfloat y,
                                gfloat z);

`clutter_actor_set_rotation` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_set_rotation_angle()` and `clutter_actor_set_pivot_point()` instead.

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.

#### Parameters

self | a ClutterActor |
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

### clutter_actor_get_rotation ()

    gdouble
    clutter_actor_get_rotation (ClutterActor *self,
                                ClutterRotateAxis axis,
                                gfloat *x,
                                gfloat *y,
                                gfloat *z);

`clutter_actor_get_rotation` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_rotation_angle()` and `clutter_actor_get_pivot_point()` instead.

Retrieves the angle and center of rotation on the given axis, set using `clutter_actor_set_rotation()`.

#### Parameters

self | a ClutterActor |
axis | the axis of rotation |
x | return value for the X coordinate of the center of rotation. | [out]
y | return value for the Y coordinate of the center of rotation. | [out]
z | return value for the Z coordinate of the center of rotation. | [out]

#### Returns

the angle of rotation

Since: 0.8

### clutter_actor_set_z_rotation_from_gravity ()

    void
    clutter_actor_set_z_rotation_from_gravity
                                   (ClutterActor *self,
                                    gdouble angle,
                                    ClutterGravity gravity);

`clutter_actor_set_z_rotation_from_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_set_rotation_angle()` and `clutter_actor_set_pivot_point()` instead.

Sets the rotation angle of `self` around the Z axis using the center point specified as a compass point. For example to rotate such that the center of the actor remains static you can use `CLUTTER_GRAVITY_CENTER`. If the actor changes size the center point will move accordingly.

#### Parameters

self | a ClutterActor |
angle | the angle of rotation |
gravity | the center point of the rotation |

Since: 1.0

### clutter_actor_get_z_rotation_gravity ()

    ClutterGravity
    clutter_actor_get_z_rotation_gravity (ClutterActor *self);

`clutter_actor_get_z_rotation_gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use the “pivot-point” instead of a ClutterGravity

Retrieves the center for the rotation around the Z axis as a compass direction. If the center was specified in pixels or units this will return `CLUTTER_GRAVITY_NONE`.

#### Parameters

self | A ClutterActor |

#### Returns

the Z rotation center

Since: 1.0

### clutter_actor_get_transformation_matrix ()

    void
    clutter_actor_get_transformation_matrix
                                   (ClutterActor *self,
                                    ClutterMatrix *matrix);

`clutter_actor_get_transformation_matrix` has been deprecated since version 1.12 and should not be used in newly-written code.

Use `clutter_actor_get_transform()` instead

Retrieves the transformations applied to `self` relative to its parent.

#### Parameters

self | a ClutterActor |
matrix | the return location for a ClutterMatrix. | [out caller-allocates]

Since: 1.0

## Types and Values

### enum ClutterActorFlags

Flags used to signal the state of an actor.

#### Members

CLUTTER_ACTOR_MAPPED | the actor will be painted (is visible, and inside a toplevel, and all parents visible) |
CLUTTER_ACTOR_REALIZED | the resources associated to the actor have been allocated |
CLUTTER_ACTOR_REACTIVE | the actor 'reacts' to mouse events emmitting event signals |
CLUTTER_ACTOR_VISIBLE | the actor has been shown by the application program |
CLUTTER_ACTOR_NO_LAYOUT | the actor provides an explicit layout management policy for its children; this flag will prevent Clutter from automatic queueing of relayout and will defer all layouting to the actor itself |

### enum ClutterRequestMode

Specifies the type of requests for a ClutterActor.

#### Members

CLUTTER_REQUEST_HEIGHT_FOR_WIDTH | Height for width requests |
CLUTTER_REQUEST_WIDTH_FOR_HEIGHT | Width for height requests |
CLUTTER_REQUEST_CONTENT_SIZE | Use the preferred size of the ClutterContent, if it has any (available since 1.22) |

Since: 0.8

### ClutterActor

    typedef struct {
      guint32 flags;
    } ClutterActor;

Base class for actors.

#### Members

guint32 `flags`; | ClutterActorFlags |

### struct ClutterActorClass

    struct ClutterActorClass {
      void (* show)                 (ClutterActor          *self);
      void (* show_all)             (ClutterActor          *self);
      void (* hide)                 (ClutterActor          *self);
      void (* hide_all)             (ClutterActor          *self);
      void (* realize)              (ClutterActor          *self);
      void (* unrealize)            (ClutterActor          *self);
      void (* map)                  (ClutterActor          *self);
      void (* unmap)                (ClutterActor          *self);
      void (* paint)                (ClutterActor          *self);
      void (* parent_set)           (ClutterActor          *actor,
                                     ClutterActor          *old_parent);

      void (* destroy)              (ClutterActor          *self);
      void (* pick)                 (ClutterActor          *actor,
                                     const ClutterColor    *color);

      void (* queue_redraw)         (ClutterActor          *actor,
                                     ClutterActor          *leaf_that_queued);

      /* size negotiation */
      void (* get_preferred_width)  (ClutterActor           *self,
                                     gfloat                  for_height,
                                     gfloat                 *min_width_p,
                                     gfloat                 *natural_width_p);
      void (* get_preferred_height) (ClutterActor           *self,
                                     gfloat                  for_width,
                                     gfloat                 *min_height_p,
                                     gfloat                 *natural_height_p);
      void (* allocate)             (ClutterActor           *self,
                                     const ClutterActorBox  *box,
                                     ClutterAllocationFlags  flags);

      /* transformations */
      void (* apply_transform)      (ClutterActor           *actor,
                                     ClutterMatrix          *matrix);

      /* event signals */
      gboolean (* event)                (ClutterActor         *actor,
                                         ClutterEvent         *event);
      gboolean (* button_press_event)   (ClutterActor         *actor,
                                         ClutterButtonEvent   *event);
      gboolean (* button_release_event) (ClutterActor         *actor,
                                         ClutterButtonEvent   *event);
      gboolean (* scroll_event)         (ClutterActor         *actor,
                                         ClutterScrollEvent   *event);
      gboolean (* key_press_event)      (ClutterActor         *actor,
                                         ClutterKeyEvent      *event);
      gboolean (* key_release_event)    (ClutterActor         *actor,
                                         ClutterKeyEvent      *event);
      gboolean (* motion_event)         (ClutterActor         *actor,
                                         ClutterMotionEvent   *event);
      gboolean (* enter_event)          (ClutterActor         *actor,
                                         ClutterCrossingEvent *event);
      gboolean (* leave_event)          (ClutterActor         *actor,
                                         ClutterCrossingEvent *event);
      gboolean (* captured_event)       (ClutterActor         *actor,
                                         ClutterEvent         *event);
      void     (* key_focus_in)         (ClutterActor         *actor);
      void     (* key_focus_out)        (ClutterActor         *actor);

      void     (* queue_relayout)       (ClutterActor         *self);

      /* accessibility support */
      AtkObject * (* get_accessible)    (ClutterActor         *self);

      gboolean (* get_paint_volume)     (ClutterActor         *actor,
                                         ClutterPaintVolume   *volume);

      gboolean (* has_overlaps)         (ClutterActor         *self);

      void     (* paint_node)           (ClutterActor         *self,
                                         ClutterPaintNode     *root);

      gboolean (* touch_event)          (ClutterActor         *self,
                                         ClutterTouchEvent    *event);
    };

Base class for actors.

#### Members

`show` () | signal class handler for “show”; it must chain up to the parent's implementation |
`show_all` () | virtual function for containers and composite actors, to determine which children should be shown when calling `clutter_actor_show_all()` on the actor. Defaults to calling `clutter_actor_show()`. This virtual function is deprecated and it should not be overridden. |
`hide` () | signal class handler for “hide”; it must chain up to the parent's implementation |
`hide_all` () | virtual function for containers and composite actors, to determine which children should be shown when calling `clutter_actor_hide_all()` on the actor. Defaults to calling `clutter_actor_hide()`. This virtual function is deprecated and it should not be overridden. |
`realize` () | virtual function, used to allocate resources for the actor; it should chain up to the parent's implementation. This virtual function is deprecated and should not be overridden in newly written code. |
`unrealize` () | virtual function, used to deallocate resources allocated in ::realize; it should chain up to the parent's implementation. This function is deprecated and should not be overridden in newly written code. |
`map` () | virtual function for containers and composite actors, to map their children; it must chain up to the parent's implementation. Overriding this function is optional. |
`unmap` () | virtual function for containers and composite actors, to unmap their children; it must chain up to the parent's implementation. Overriding this function is optional. |
`paint` () | virtual function, used to paint the actor |
`parent_set` () | signal class handler for the “parent-set” |
`destroy` () | signal class handler for “destroy”. It must chain up to the parent's implementation |
`pick` () | virtual function, used to draw an outline of the actor with the given color |
`queue_redraw` () | class handler for “queue-redraw” |
`get_preferred_width` () | virtual function, used when querying the minimum and natural widths of an actor for a given height; it is used by `clutter_actor_get_preferred_width()` |
`get_preferred_height` () | virtual function, used when querying the minimum and natural heights of an actor for a given width; it is used by `clutter_actor_get_preferred_height()` |
`allocate` () | virtual function, used when settings the coordinates of an actor; it is used by `clutter_actor_allocate()`; it must chain up to the parent's implementation, or call `clutter_actor_set_allocation()` |
`apply_transform` () | virtual function, used when applying the transformations to an actor before painting it or when transforming coordinates or the allocation; it must chain up to the parent's implementation |
`event` () | class handler for “event” |
`button_press_event` () | class handler for “button-press-event” |
`button_release_event` () | class handler for “button-release-event” |
`scroll_event` () | signal class closure for “scroll-event” |
`key_press_event` () | signal class closure for “key-press-event” |
`key_release_event` () | signal class closure for “key-release-event” |
`motion_event` () | signal class closure for “motion-event” |
`enter_event` () | signal class closure for “enter-event” |
`leave_event` () | signal class closure for “leave-event” |
`captured_event` () | signal class closure for “captured-event” |
`key_focus_in` () | signal class closure for “key-focus-in” |
`key_focus_out` () | signal class closure for “key-focus-out” |
`queue_relayout` () | class handler for “queue-relayout” |
`get_accessible` () | virtual function, returns the accessible object that describes the actor to an assistive technology. |
`get_paint_volume` () | virtual function, for sub-classes to define their ClutterPaintVolume |
`has_overlaps` () | virtual function for sub-classes to advertise whether they need an offscreen redirect to get the correct opacity. See `clutter_actor_set_offscreen_redirect()` for details. |
`paint_node` () | virtual function for creating paint nodes and attaching them to the render tree |
`touch_event` () | signal class closure for “touch-event” |

### enum ClutterAllocationFlags

Flags passed to the `ClutterActorClass.allocate()` virtual function and to the `clutter_actor_allocate()` function.

#### Members

CLUTTER_ALLOCATION_NONE | No flag set |
CLUTTER_ABSOLUTE_ORIGIN_CHANGED | Whether the absolute origin of the actor has changed; this implies that any ancestor of the actor has been moved. |

CLUTTER_DELEGATE_LAYOUT

Whether the allocation should be delegated to the ClutterLayoutManager instance stored inside the “layout-manager” property of ClutterActor. This flag should only be used if you are subclassing ClutterActor and overriding the `ClutterActorClass.allocate()` virtual function, but you wish to use the default implementation of the virtual function inside ClutterActor. Added in Clutter 1.10.

Since: 1.0

### enum ClutterActorAlign

Controls how a ClutterActor should align itself inside the extra space assigned to it during the allocation.

Alignment only matters if the allocated space given to an actor is bigger than its natural size; for example, when the “x-expand” or the “y-expand” properties of ClutterActor are set to `TRUE`.

#### Members

CLUTTER_ACTOR_ALIGN_FILL | Stretch to cover the whole allocated space |
CLUTTER_ACTOR_ALIGN_START | Snap to left or top side, leaving space to the right or bottom. For horizontal layouts, in right-to-left locales this should be reversed. |
CLUTTER_ACTOR_ALIGN_CENTER | Center the actor inside the allocation |
CLUTTER_ACTOR_ALIGN_END | Snap to right or bottom side, leaving space to the left or top. For horizontal layouts, in right-to-left locales this should be reversed. |

Since: 1.10

### struct ClutterMargin

    struct ClutterMargin {
      float left;
      float right;
      float top;
      float bottom;
    };

A representation of the components of a margin.

#### Members

float `left`; | the margin from the left |
float `right`; | the margin from the right |
float `top`; | the margin from the top |
float `bottom`; | the margin from the bottom |

Since: 1.10

### enum ClutterContentGravity

Controls the alignment of the ClutterContent inside a ClutterActor.

#### Members

CLUTTER_CONTENT_GRAVITY_TOP_LEFT | Align the content to the top left corner |
CLUTTER_CONTENT_GRAVITY_TOP | Align the content to the top edge |
CLUTTER_CONTENT_GRAVITY_TOP_RIGHT | Align the content to the top right corner |
CLUTTER_CONTENT_GRAVITY_LEFT | Align the content to the left edge |
CLUTTER_CONTENT_GRAVITY_CENTER | Align the content to the center |
CLUTTER_CONTENT_GRAVITY_RIGHT | Align the content to the right edge |
CLUTTER_CONTENT_GRAVITY_BOTTOM_LEFT | Align the content to the bottom left corner |
CLUTTER_CONTENT_GRAVITY_BOTTOM | Align the content to the bottom edge |
CLUTTER_CONTENT_GRAVITY_BOTTOM_RIGHT | Align the content to the bottom right corner |
CLUTTER_CONTENT_GRAVITY_RESIZE_FILL | Resize the content to fill the allocation |
CLUTTER_CONTENT_GRAVITY_RESIZE_ASPECT | Resize the content to remain within the allocation, while maintaining the aspect ratio |

Since: 1.10

### enum ClutterScalingFilter

The scaling filters to be used with the “minification-filter” and “magnification-filter” properties.

#### Members

CLUTTER_SCALING_FILTER_LINEAR | Linear interpolation filter |
CLUTTER_SCALING_FILTER_NEAREST | Nearest neighbor interpolation filter |
CLUTTER_SCALING_FILTER_TRILINEAR | Trilinear minification filter, with mipmap generation; this filter linearly interpolates on every axis, as well as between mipmap levels. |

Since: 1.10

### enum ClutterContentRepeat

Content repeat modes.

#### Members

CLUTTER_REPEAT_NONE | No repeat |
CLUTTER_REPEAT_X_AXIS | Repeat the content on the X axis |
CLUTTER_REPEAT_Y_AXIS | Repeat the content on the Y axis |
CLUTTER_REPEAT_BOTH | Repeat the content on both axis |

Since: 1.12

### enum ClutterOffscreenRedirect

Possible flags to pass to `clutter_actor_set_offscreen_redirect()`.

#### Members

CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY | Only redirect the actor if it is semi-transparent and its `has_overlaps()` virtual returns `TRUE`. This is the default. |
CLUTTER_OFFSCREEN_REDIRECT_ALWAYS | Always redirect the actor to an offscreen buffer even if it is fully opaque. |

Since: 1.8

### ClutterActorIter

    typedef struct {
    } ClutterActorIter;

An iterator structure that allows to efficiently iterate over a section of the scene graph.

The contents of the ClutterActorIter structure are private and should only be accessed using the provided API.

Since: 1.10

## Property Details

### The `“actions”` property

      “actions”                  ClutterAction *

Adds a ClutterAction to the actor

Flags: Write

Since: 1.4

### The `“allocation”` property

      “allocation”               ClutterActorBox *

The allocation for the actor, in pixels

This is property is read-only, but you might monitor it to know when an actor moves or resizes

Flags: Read

Since: 0.8

### The `“anchor-gravity”` property

      “anchor-gravity”           ClutterGravity

The anchor point expressed as a ClutterGravity

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

`ClutterActor:anchor-gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0

### The `“anchor-x”` property

      “anchor-x”                 gfloat

The X coordinate of an actor's anchor point, relative to the actor coordinate space, in pixels.

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

`ClutterActor:anchor-x` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 0.8

### The `“anchor-y”` property

      “anchor-y”                 gfloat

The Y coordinate of an actor's anchor point, relative to the actor coordinate space, in pixels

It is highly recommended not to use “anchor-x”, “anchor-y”, and “anchor-gravity” in newly written code; the anchor point adds an additional translation that will affect the actor's relative position with regards to its parent, as well as the position of its children. This change needs to always be taken into account when positioning the actor. It is recommended to use the “pivot-point” property instead, as it will affect only the transformations.

`ClutterActor:anchor-y` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 0.8

### The `“background-color”` property

      “background-color”         ClutterColor *

Paints a solid fill of the actor's allocation using the specified color.

The “background-color” property is animatable.

Flags: Read / Write

Since: 1.10

### The `“background-color-set”` property

      “background-color-set”     gboolean

Whether the “background-color” property has been set.

Flags: Read

Default value: FALSE

Since: 1.10

### The `“child-transform”` property

      “child-transform”          ClutterMatrix *

Applies a transformation matrix on each child of an actor.

Setting this property with a ClutterMatrix will set the “child-transform-set” property to `TRUE` as a side effect; setting this property with `NULL` will set the “child-transform-set” property to `FALSE`.

The “child-transform” property is animatable.

Flags: Read / Write

Since: 1.12

### The `“child-transform-set”` property

      “child-transform-set”      gboolean

Whether the “child-transform” property is set.

Flags: Read

Default value: FALSE

Since: 1.12

### The `“clip”` property

      “clip”                     ClutterGeometry *

The visible region of the actor, in actor-relative coordinates

`ClutterActor:clip` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “clip-rect” instead.

Flags: Read / Write

### The `“clip-rect”` property

      “clip-rect”                ClutterRect *

The visible region of the actor, in actor-relative coordinates, expressed as a ClutterRect.

Setting this property to `NULL` will unset the existing clip.

Setting this property will change the “has-clip” property as a side effect.

Flags: Read / Write

Since: 1.12

### The `“clip-to-allocation”` property

      “clip-to-allocation”       gboolean

Whether the clip region should track the allocated area of the actor.

This property is ignored if a clip area has been explicitly set using `clutter_actor_set_clip()`.

Flags: Read / Write

Default value: FALSE

Since: 1.0

### The `“constraints”` property

      “constraints”              ClutterConstraint *

Adds a ClutterConstraint to the actor

Flags: Write

Since: 1.4

### The `“content”` property

      “content”                  ClutterContent *

The ClutterContent implementation that controls the content of the actor.

Flags: Read / Write

Since: 1.10

### The `“content-box”` property

      “content-box”              ClutterActorBox *

The bounding box for the ClutterContent used by the actor.

The value of this property is controlled by the “allocation” and “content-gravity” properties of ClutterActor.

The bounding box for the content is guaranteed to never exceed the allocation's of the actor.

Flags: Read

Since: 1.10

### The `“content-gravity”` property

      “content-gravity”          ClutterContentGravity

The alignment that should be honoured by the ClutterContent set with the “content” property.

Changing the value of this property will change the bounding box of the content; you can use the “content-box” property to get the position and size of the content within the actor's allocation.

This property is meaningful only for ClutterContent implementations that have a preferred size, and if the preferred size is smaller than the actor's allocation.

The “content-gravity” property is animatable.

Flags: Read / Write

Default value: CLUTTER_CONTENT_GRAVITY_RESIZE_FILL

Since: 1.10

### The `“content-repeat”` property

      “content-repeat”           ClutterContentRepeat

The repeat policy for the actor's “content”.

Flags: Read / Write

Since: 1.12

### The `“depth”` property

      “depth”                    gfloat

The position of the actor on the Z axis.

The “depth” property is relative to the parent's modelview matrix.

Setting this property will call `ClutterContainerIface.sort_depth_order()` which is usually a no-op, and it's most likely not what you want.

The “depth” property is animatable.

`ClutterActor:depth` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “z-position” instead.

Flags: Read / Write

Default value: 0

Since: 0.6

### The `“effect”` property

      “effect”                   ClutterEffect *

Adds ClutterEffect to the list of effects be applied on a ClutterActor

Flags: Write

Since: 1.4

### The `“first-child”` property

      “first-child”              ClutterActor *

The actor's first child.

Flags: Read

Since: 1.10

### The `“fixed-position-set”` property

      “fixed-position-set”       gboolean

This flag controls whether the “fixed-x” and “fixed-y” properties are used

Flags: Read / Write

Default value: FALSE

Since: 0.8

### The `“fixed-x”` property

      “fixed-x”                  gfloat

The fixed X position of the actor in pixels.

Writing this property sets “fixed-position-set” property as well, as a side effect

Flags: Read / Write

Default value: 0

Since: 0.8

### The `“fixed-y”` property

      “fixed-y”                  gfloat

The fixed Y position of the actor in pixels.

Writing this property sets the “fixed-position-set” property as well, as a side effect

Flags: Read / Write

Default value: 0

Since: 0.8

### The `“has-clip”` property

      “has-clip”                 gboolean

Whether the actor has the “clip” property set or not

Flags: Read

Default value: FALSE

### The `“has-pointer”` property

      “has-pointer”              gboolean

Whether the actor contains the pointer of a ClutterInputDevice or not.

Flags: Read

Default value: FALSE

Since: 1.2

### The `“height”` property

      “height”                   gfloat

Height of the actor (in pixels). If written, forces the minimum and natural size request of the actor to the given height. If read, returns the allocated height if available, otherwise the height request.

The “height” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“last-child”` property

      “last-child”               ClutterActor *

The actor's last child.

Flags: Read

Since: 1.10

### The `“layout-manager”` property

      “layout-manager”           ClutterLayoutManager *

A delegate object for controlling the layout of the children of an actor.

Flags: Read / Write

Since: 1.10

### The `“magnification-filter”` property

      “magnification-filter”     ClutterScalingFilter

The filter used when increasing the size of the content.

Flags: Read / Write

Default value: CLUTTER_SCALING_FILTER_LINEAR

### The `“mapped”` property

      “mapped”                   gboolean

Whether the actor is mapped (will be painted when the stage to which it belongs is mapped)

Flags: Read

Default value: FALSE

Since: 1.0

### The `“margin-bottom”` property

      “margin-bottom”            gfloat

The margin (in pixels) from the bottom of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-bottom” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10

### The `“margin-left”` property

      “margin-left”              gfloat

The margin (in pixels) from the left of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-left” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10

### The `“margin-right”` property

      “margin-right”             gfloat

The margin (in pixels) from the right of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-right” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10

### The `“margin-top”` property

      “margin-top”               gfloat

The margin (in pixels) from the top of the actor.

This property adds a margin to the actor's preferred size; the margin will be automatically taken into account when allocating the actor.

The “margin-top” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 1.10

### The `“min-height”` property

      “min-height”               gfloat

A forced minimum height request for the actor, in pixels

Writing this property sets the “min-height-set” property as well, as a side effect. This property overrides the usual height request of the actor.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8

### The `“min-height-set”` property

      “min-height-set”           gboolean

This flag controls whether the “min-height” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8

### The `“min-width”` property

      “min-width”                gfloat

A forced minimum width request for the actor, in pixels

Writing this property sets the “min-width-set” property as well, as a side effect.

This property overrides the usual width request of the actor.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8

### The `“min-width-set”` property

      “min-width-set”            gboolean

This flag controls whether the “min-width” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8

### The `“minification-filter”` property

      “minification-filter”      ClutterScalingFilter

The filter used when reducing the size of the content.

Flags: Read / Write

Default value: CLUTTER_SCALING_FILTER_LINEAR

### The `“name”` property

      “name”                     gchar *

The name of the actor

Flags: Read / Write

Default value: NULL

Since: 0.2

### The `“natural-height”` property

      “natural-height”           gfloat

A forced natural height request for the actor, in pixels

Writing this property sets the “natural-height-set” property as well, as a side effect. This property overrides the usual height request of the actor

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8

### The `“natural-height-set”` property

      “natural-height-set”       gboolean

This flag controls whether the “natural-height” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8

### The `“natural-width”` property

      “natural-width”            gfloat

A forced natural width request for the actor, in pixels

Writing this property sets the “natural-width-set” property as well, as a side effect. This property overrides the usual width request of the actor

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since: 0.8

### The `“natural-width-set”` property

      “natural-width-set”        gboolean

This flag controls whether the “natural-width” property is used

Flags: Read / Write

Default value: FALSE

Since: 0.8

### The `“offscreen-redirect”` property

      “offscreen-redirect”       ClutterOffscreenRedirect

Determines the conditions in which the actor will be redirected to an offscreen framebuffer while being painted. For example this can be used to cache an actor in a framebuffer or for improved handling of transparent actors. See `clutter_actor_set_offscreen_redirect()` for details.

Flags: Read / Write

Since: 1.8

### The `“opacity”` property

      “opacity”                  guint

Opacity of an actor, between 0 (fully transparent) and 255 (fully opaque)

The “opacity” property is animatable.

Flags: Read / Write

Allowed values: <= 255

Default value: 255

### The `“pivot-point”` property

      “pivot-point”              ClutterPoint *

The point around which the scaling and rotation transformations occur.

The pivot point is expressed in normalized coordinates space, with (0, 0) being the top left corner of the actor and (1, 1) the bottom right corner of the actor.

The default pivot point is located at (0, 0).

The “pivot-point” property is animatable.

Flags: Read / Write

Since: 1.12

### The `“pivot-point-z”` property

      “pivot-point-z”            gfloat

The Z component of the “pivot-point”, expressed as a value along the Z axis.

The “pivot-point-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

### The `“position”` property

      “position”                 ClutterPoint *

The position of the origin of the actor.

This property is a shorthand for setting and getting the “x” and “y” properties at the same time.

The “position” property is animatable.

Flags: Read / Write

Since: 1.12

### The `“reactive”` property

      “reactive”                 gboolean

Whether the actor is reactive to events or not

Only reactive actors will emit event-related signals

Flags: Read / Write

Default value: FALSE

Since: 0.6

### The `“realized”` property

      “realized”                 gboolean

Whether the actor has been realized

Flags: Read

Default value: FALSE

Since: 1.0

### The `“request-mode”` property

      “request-mode”             ClutterRequestMode

Request mode for the ClutterActor. The request mode determines the type of geometry management used by the actor, either height for width (the default) or width for height.

For actors implementing height for width, the parent container should get the preferred width first, and then the preferred height for that width.

For actors implementing width for height, the parent container should get the preferred height first, and then the preferred width for that height.

For instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33

    ClutterRequestMode mode;
    gfloat natural_width, min_width;
    gfloat natural_height, min_height;

    mode = clutter_actor_get_request_mode (child);
    if (mode == CLUTTER_REQUEST_HEIGHT_FOR_WIDTH)
      {
        clutter_actor_get_preferred_width (child, -1,
                                           &min_width,
                                           &natural_width);
        clutter_actor_get_preferred_height (child, natural_width,
                                            &min_height,
                                            &natural_height);
      }
    else if (mode == CLUTTER_REQUEST_WIDTH_FOR_HEIGHT)
      {
        clutter_actor_get_preferred_height (child, -1,
                                            &min_height,
                                            &natural_height);
        clutter_actor_get_preferred_width (child, natural_height,
                                           &min_width,
                                           &natural_width);
      }
    else if (mode == CLUTTER_REQUEST_CONTENT_SIZE)
      {
        ClutterContent *content = clutter_actor_get_content (child);

        min_width, min_height = 0;
        natural_width = natural_height = 0;

        if (content != NULL)
          clutter_content_get_preferred_size (content, &natural_width, &natural_height);
      }

will retrieve the minimum and natural width and height depending on the preferred request mode of the ClutterActor "child".

The `clutter_actor_get_preferred_size()` function will implement this check for you.

Flags: Read / Write

Default value: CLUTTER_REQUEST_HEIGHT_FOR_WIDTH

Since: 0.8

### The `“rotation-angle-x”` property

      “rotation-angle-x”         gdouble

The rotation angle on the X axis.

The “rotation-angle-x” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6

### The `“rotation-angle-y”` property

      “rotation-angle-y”         gdouble

The rotation angle on the Y axis

The “rotation-angle-y” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6

### The `“rotation-angle-z”` property

      “rotation-angle-z”         gdouble

The rotation angle on the Z axis

The “rotation-angle-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 0.6

### The `“rotation-center-x”` property

      “rotation-center-x”        ClutterVertex *

The rotation center on the X axis.

`ClutterActor:rotation-center-x` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6

### The `“rotation-center-y”` property

      “rotation-center-y”        ClutterVertex *

The rotation center on the Y axis.

`ClutterActor:rotation-center-y` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6

### The `“rotation-center-z”` property

      “rotation-center-z”        ClutterVertex *

The rotation center on the Z axis.

`ClutterActor:rotation-center-z` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Since: 0.6

### The `“rotation-center-z-gravity”` property

      “rotation-center-z-gravity” ClutterGravity

The rotation center on the Z axis expressed as a ClutterGravity.

`ClutterActor:rotation-center-z-gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0

### The `“scale-center-x”` property

      “scale-center-x”           gfloat

The horizontal center point for scaling

`ClutterActor:scale-center-x` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 1.0

### The `“scale-center-y”` property

      “scale-center-y”           gfloat

The vertical center point for scaling

`ClutterActor:scale-center-y` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: 0

Since: 1.0

### The `“scale-gravity”` property

      “scale-gravity”            ClutterGravity

The center point for scaling expressed as a ClutterGravity

`ClutterActor:scale-gravity` has been deprecated since version 1.12 and should not be used in newly-written code.

Use “pivot-point” instead

Flags: Read / Write

Default value: CLUTTER_GRAVITY_NONE

Since: 1.0

### The `“scale-x”` property

      “scale-x”                  gdouble

The horizontal scale of the actor.

The “scale-x” property is animatable.

Flags: Read / Write

Default value: 1

Since: 0.6

### The `“scale-y”` property

      “scale-y”                  gdouble

The vertical scale of the actor.

The “scale-y” property is animatable.

Flags: Read / Write

Default value: 1

Since: 0.6

### The `“scale-z”` property

      “scale-z”                  gdouble

The scale factor of the actor along the Z axis.

The “scale-y” property is animatable.

Flags: Read / Write

Default value: 1

Since: 1.12

### The `“show-on-set-parent”` property

      “show-on-set-parent”       gboolean

If `TRUE`, the actor is automatically shown when parented.

Calling `clutter_actor_hide()` on an actor which has not been parented will set this property to `FALSE` as a side effect.

Flags: Read / Write

Default value: TRUE

Since: 0.8

### The `“size”` property

      “size”                     ClutterSize *

The size of the actor.

This property is a shorthand for setting and getting the “width” and “height” at the same time.

The “size” property is animatable.

Flags: Read / Write

Since: 1.12

### The `“text-direction”` property

      “text-direction”           ClutterTextDirection

The direction of the text inside a ClutterActor.

Flags: Read / Write

Default value: CLUTTER_TEXT_DIRECTION_LTR

Since: 1.0

### The `“transform”` property

      “transform”                ClutterMatrix *

Overrides the transformations of a ClutterActor with a custom matrix.

The matrix specified by the “transform” property is applied to the actor and its children relative to the actor's “allocation” and “pivot-point”.

Application code should rarely need to use this function directly.

Setting this property with a ClutterMatrix will set the “transform-set” property to `TRUE` as a side effect; setting this property with `NULL` will set the “transform-set” property to `FALSE`.

The “transform” property is animatable.

Flags: Read / Write

Since: 1.12

### The `“transform-set”` property

      “transform-set”            gboolean

Whether the “transform” property is set.

Flags: Read

Default value: FALSE

Since: 1.12

### The `“translation-x”` property

      “translation-x”            gfloat

An additional translation applied along the X axis, relative to the actor's “pivot-point”.

The “translation-x” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

### The `“translation-y”` property

      “translation-y”            gfloat

An additional translation applied along the Y axis, relative to the actor's “pivot-point”.

The “translation-y” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

### The `“translation-z”` property

      “translation-z”            gfloat

An additional translation applied along the Z axis, relative to the actor's “pivot-point”.

The “translation-z” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

### The `“visible”` property

      “visible”                  gboolean

Whether the actor is set to be visible or not

See also “mapped”

Flags: Read / Write

Default value: FALSE

### The `“width”` property

      “width”                    gfloat

Width of the actor (in pixels). If written, forces the minimum and natural size request of the actor to the given width. If read, returns the allocated width if available, otherwise the width request.

The “width” property is animatable.

Flags: Read / Write

Allowed values: >= 0

Default value: 0

### The `“x”` property

      “x”                        gfloat

X coordinate of the actor in pixels. If written, forces a fixed position for the actor. If read, returns the fixed position if any, otherwise the allocation if available, otherwise 0.

The “x” property is animatable.

Flags: Read / Write

Default value: 0

### The `“x-align”` property

      “x-align”                  ClutterActorAlign

The alignment of an actor on the X axis, if the actor has been given extra space for its allocation. See also the “x-expand” property.

Flags: Read / Write

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since: 1.10

### The `“x-expand”` property

      “x-expand”                 gboolean

Whether a layout manager should assign more space to the actor on the X axis.

Flags: Read / Write

Default value: FALSE

Since: 1.12

### The `“y”` property

      “y”                        gfloat

Y coordinate of the actor in pixels. If written, forces a fixed position for the actor. If read, returns the fixed position if any, otherwise the allocation if available, otherwise 0.

The “y” property is animatable.

Flags: Read / Write

Default value: 0

### The `“y-align”` property

      “y-align”                  ClutterActorAlign

The alignment of an actor on the Y axis, if the actor has been given extra space for its allocation.

Flags: Read / Write

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since: 1.10

### The `“y-expand”` property

      “y-expand”                 gboolean

Whether a layout manager should assign more space to the actor on the Y axis.

Flags: Read / Write

Default value: FALSE

Since: 1.12

### The `“z-position”` property

      “z-position”               gfloat

The actor's position on the Z axis, relative to the parent's transformations.

Positive values will bring the actor's position nearer to the user, whereas negative values will bring the actor's position farther from the user.

The “z-position” does not affect the paint or allocation order.

The “z-position” property is animatable.

Flags: Read / Write

Default value: 0

Since: 1.12

## Signal Details

### The `“allocation-changed”` signal

    void
    user_function (ClutterActor          *actor,
                   ClutterActorBox       *box,
                   ClutterAllocationFlags flags,
                   gpointer               user_data)

The ::allocation-changed signal is emitted when the “allocation” property changes. Usually, application code should just use the notifications for the :allocation property but if you want to track the allocation flags as well, for instance to know whether the absolute origin of `actor` changed, then you might want use this signal instead.

#### Parameters

actor | the ClutterActor that emitted the signal |
box | a ClutterActorBox with the new allocation |
flags | ClutterAllocationFlags for the allocation |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“button-press-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the event |
event | a ClutterButtonEvent. | [type ClutterButtonEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“button-release-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the event |
event | a ClutterButtonEvent. | [type ClutterButtonEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“captured-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the signal |
event | a ClutterEvent |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“destroy”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

The ::destroy signal notifies that all references held on the actor which emitted it should be released.

The ::destroy signal should be used by all holders of a reference on `actor` .

This signal might result in the finalization of the ClutterActor if all references are released.

Composite actors and actors implementing the ClutterContainer interface should override the default implementation of the class handler of this signal and call `clutter_actor_destroy()` on their children. When overriding the default class handler, it is required to chain up to the parent's implementation.

#### Parameters

actor | the ClutterActor which emitted the signal |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 0.2

### The `“enter-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which the pointer has entered. |
event | a ClutterCrossingEvent. | [type ClutterCrossingEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the event |
event | a ClutterEvent |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“hide”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

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

#### Parameters

actor | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 0.2

### The `“key-focus-in”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

The ::key-focus-in signal is emitted when `actor` receives key focus.

#### Parameters

actor | the actor which now has key focus |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6

### The `“key-focus-out”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which now has key focus |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.6

### The `“key-press-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

The ::key-press-event signal is emitted each time a keyboard button is pressed while `actor` has key focus (see `clutter_stage_set_key_focus()`).

#### Parameters

actor | the actor which received the event |
event | a ClutterKeyEvent. | [type ClutterKeyEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“key-release-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

The ::key-release-event signal is emitted each time a keyboard button is released while `actor` has key focus (see `clutter_stage_set_key_focus()`).

#### Parameters

actor | the actor which received the event |
event | a ClutterKeyEvent. | [type ClutterKeyEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“leave-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which the pointer has left |
event | a ClutterCrossingEvent. | [type ClutterCrossingEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“motion-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the event |
event | a ClutterMotionEvent. | [type ClutterMotionEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“paint”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

The ::paint signal is emitted each time an actor is being painted.

Subclasses of ClutterActor should override the ClutterActorClass.paint virtual function paint themselves in that function.

It is strongly discouraged to connect a signal handler to the “paint” signal; if you want to change the paint sequence of an existing ClutterActor instance, either create a new ClutterActor class and override the ClutterActorClass.paint virtual function, or use a ClutterEffect. The “paint” signal will be removed in a future version of Clutter.

`ClutterActor::paint` has been deprecated since version 1.12 and should not be used in newly-written code.

Override the ClutterActorClass.paint virtual function, use a ClutterContent implementation, or a ClutterEffect instead of connecting to this signal.

#### Parameters

actor | the ClutterActor that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 0.8

### The `“parent-set”` signal

    void
    user_function (ClutterActor *actor,
                   ClutterActor *old_parent,
                   gpointer      user_data)

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

#### Parameters

actor | the object which received the signal |
old_parent | the previous parent of the actor, or `NULL`. | [allow-none]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.2

### The `“pick”` signal

    void
    user_function (ClutterActor *actor,
                   ClutterColor *color,
                   gpointer      user_data)

The ::pick signal is emitted each time an actor is being painted in "pick mode". The pick mode is used to identify the actor during the event handling phase, or by `clutter_stage_get_actor_at_pos()`. The actor should paint its shape using the passed `pick_color` .

Subclasses of ClutterActor should override the class signal handler and paint themselves in that function.

It is possible to connect a handler to the ::pick signal in order to set up some custom aspect of a paint in pick mode.

`ClutterActor::pick` has been deprecated since version 1.12 and should not be used in newly-written code.

Override the ClutterActorClass.pick virtual function instead.

#### Parameters

actor | the ClutterActor that received the signal |
color | the ClutterColor to be used when picking |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0

### The `“queue-redraw”` signal

    void
    user_function (ClutterActor *actor,
                   ClutterActor *origin,
                   gpointer      user_data)

The ::queue_redraw signal is emitted when `clutter_actor_queue_redraw()` is called on `origin` .

The default implementation for ClutterActor chains up to the parent actor and queues a redraw on the parent, thus "bubbling" the redraw queue up through the actor graph. The default implementation for ClutterStage queues a `clutter_stage_ensure_redraw()` in a main loop idle handler.

Note that the `origin` actor may be the stage, or a container; it does not have to be a leaf node in the actor graph.

Toolkits embedding a ClutterStage which require a redraw and relayout cycle can stop the emission of this signal using the GSignal API, redraw the UI and then call `clutter_stage_ensure_redraw()` themselves, like:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19

    static void
    on_redraw_complete (gpointer data)
    {
      ClutterStage *stage = data;

      // execute the Clutter drawing pipeline
      clutter_stage_ensure_redraw (stage);
    }

    static void
    on_stage_queue_redraw (ClutterStage *stage)
    {
      // this prevents the default handler to run
      g_signal_stop_emission_by_name (stage, "queue-redraw");

      // queue a redraw with the host toolkit and call
      // a function when the redraw has been completed
      queue_a_redraw (G_CALLBACK (on_redraw_complete), stage);
    }

Note: This signal is emitted before the Clutter paint pipeline is executed. If you want to know when the pipeline has been completed you should use `clutter_threads_add_repaint_func()` or `clutter_threads_add_repaint_func_full()`.

#### Parameters

actor | the actor we're bubbling the redraw request through |
origin | the actor which initiated the redraw request |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 1.0

### The `“queue-relayout”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

The ::queue_layout signal is emitted when `clutter_actor_queue_relayout()` is called on an actor.

The default implementation for ClutterActor chains up to the parent actor and queues a relayout on the parent, thus "bubbling" the relayout queue up through the actor graph.

The main purpose of this signal is to allow relayout to be propagated properly in the presence of ClutterClone actors. Applications will not normally need to connect to this signal.

#### Parameters

actor | the actor being queued for relayout |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 1.2

### The `“realize”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

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

`ClutterActor::realize` has been deprecated since version 1.16 and should not be used in newly-written code.

The signal should not be used in newly written code

#### Parameters

actor | the ClutterActor that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.8

### The `“scroll-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

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

#### Parameters

actor | the actor which received the event |
event | a ClutterScrollEvent. | [type ClutterScrollEvent]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` if the event has been handled by the actor, or `FALSE` to continue the emission.

Flags: Run Last

Since: 0.6

### The `“show”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

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

#### Parameters

actor | the object which received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

Since: 0.2

### The `“touch-event”` signal

    gboolean
    user_function (ClutterActor *actor,
                   ClutterEvent *event,
                   gpointer      user_data)

The ::touch-event signal is emitted each time a touch begin/end/update/cancel event.

#### Parameters

actor | a ClutterActor |
event | a ClutterEvent |
user_data | user data set when the signal handler was connected. |

#### Returns

`CLUTTER_EVENT_STOP` if the event has been handled by the actor, or `CLUTTER_EVENT_PROPAGATE` to continue the emission.

Flags: Run Last

Since: 1.12

### The `“transition-stopped”` signal

    void
    user_function (ClutterActor *actor,
                   gchar        *name,
                   gboolean      is_finished,
                   gpointer      user_data)

The ::transition-stopped signal is emitted once a transition is stopped; a transition is stopped once it reached its total duration (including eventual repeats), it has been stopped using `clutter_timeline_stop()`, or it has been removed from the transitions applied on `actor` , using `clutter_actor_remove_transition()`.

#### Parameters

actor | a ClutterActor |
name | the name of the transition |
is_finished | whether the transition was finished, or stopped |
user_data | user data set when the signal handler was connected. |

Flags: No Hooks

Since: 1.12

### The `“transitions-completed”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

The ::transitions-completed signal is emitted once all transitions involving `actor` are complete.

#### Parameters

actor | a ClutterActor |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.10

### The `“unrealize”` signal

    void
    user_function (ClutterActor *actor,
                   gpointer      user_data)

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

`ClutterActor::unrealize` has been deprecated since version 1.16 and should not be used in newly-written code.

The signal should not be used in newly written code

#### Parameters

actor | the ClutterActor that received the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 0.8