Clutter Reference Manual: ClutterActor

## ClutterActor ClutterActor — The basic element of the scene graph |

## Synopsis

    #define             CLUTTER_ACTOR_SET_FLAGS             (a,
                                                             f)
    #define             CLUTTER_ACTOR_UNSET_FLAGS           (a,
                                                             f)
    #define             CLUTTER_ACTOR_IS_MAPPED             (a)
    #define             CLUTTER_ACTOR_IS_REALIZED           (a)
    #define             CLUTTER_ACTOR_IS_VISIBLE            (a)
    #define             CLUTTER_ACTOR_IS_REACTIVE           (a)

    enum                ClutterActorFlags;
    enum                ClutterRequestMode;
    #define             CLUTTER_CALLBACK                    (f)
    void                (*ClutterCallback)                  (ClutterActor *actor,
                                                             gpointer data);
                        ClutterActor;
    struct              ClutterActorClass;
    ClutterActor *      clutter_actor_new                   (void);
    void                clutter_actor_set_flags             (ClutterActor *self,
                                                             ClutterActorFlags flags);
    void                clutter_actor_unset_flags           (ClutterActor *self,
                                                             ClutterActorFlags flags);
    ClutterActorFlags   clutter_actor_get_flags             (ClutterActor *self);
    void                clutter_actor_set_name              (ClutterActor *self,
                                                             const gchar *name);
    const gchar *       clutter_actor_get_name              (ClutterActor *self);
    guint32             clutter_actor_get_gid               (ClutterActor *self);

    void                clutter_actor_show                  (ClutterActor *self);
    void                clutter_actor_show_all              (ClutterActor *self);
    void                clutter_actor_hide                  (ClutterActor *self);
    void                clutter_actor_hide_all              (ClutterActor *self);
    void                clutter_actor_realize               (ClutterActor *self);
    void                clutter_actor_unrealize             (ClutterActor *self);
    void                clutter_actor_paint                 (ClutterActor *self);
    void                clutter_actor_continue_paint        (ClutterActor *self);
    void                clutter_actor_queue_redraw          (ClutterActor *self);
    void                clutter_actor_queue_redraw_with_clip
                                                            (ClutterActor *self,
                                                             const cairo_rectangle_int_t *clip);
    void                clutter_actor_queue_relayout        (ClutterActor *self);
    void                clutter_actor_destroy               (ClutterActor *self);
    gboolean            clutter_actor_event                 (ClutterActor *actor,
                                                             const ClutterEvent *event,
                                                             gboolean capture);
    gboolean            clutter_actor_should_pick_paint     (ClutterActor *self);
    void                clutter_actor_map                   (ClutterActor *self);
    void                clutter_actor_unmap                 (ClutterActor *self);
    gboolean            clutter_actor_has_overlaps          (ClutterActor *self);
    gboolean            clutter_actor_has_mapped_clones     (ClutterActor *self);

    enum                ClutterAllocationFlags;
    void                clutter_actor_allocate              (ClutterActor *self,
                                                             const ClutterActorBox *box,
                                                             ClutterAllocationFlags flags);
    void                clutter_actor_allocate_preferred_size
                                                            (ClutterActor *self,
                                                             ClutterAllocationFlags flags);
    void                clutter_actor_allocate_available_size
                                                            (ClutterActor *self,
                                                             gfloat x,
                                                             gfloat y,
                                                             gfloat available_width,
                                                             gfloat available_height,
                                                             ClutterAllocationFlags flags);
    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);
    void                clutter_actor_set_allocation        (ClutterActor *self,
                                                             const ClutterActorBox *box,
                                                             ClutterAllocationFlags flags);
    void                clutter_actor_get_allocation_box    (ClutterActor *self,
                                                             ClutterActorBox *box);
    void                clutter_actor_get_allocation_geometry
                                                            (ClutterActor *self,
                                                             ClutterGeometry *geom);
    void                clutter_actor_get_allocation_vertices
                                                            (ClutterActor *self,
                                                             ClutterActor *ancestor,
                                                             ClutterVertex verts[]);
    void                clutter_actor_get_preferred_size    (ClutterActor *self,
                                                             gfloat *min_width_p,
                                                             gfloat *min_height_p,
                                                             gfloat *natural_width_p,
                                                             gfloat *natural_height_p);
    void                clutter_actor_get_preferred_width   (ClutterActor *self,
                                                             gfloat for_height,
                                                             gfloat *min_width_p,
                                                             gfloat *natural_width_p);
    void                clutter_actor_get_preferred_height  (ClutterActor *self,
                                                             gfloat for_width,
                                                             gfloat *min_height_p,
                                                             gfloat *natural_height_p);
    void                clutter_actor_set_fixed_position_set
                                                            (ClutterActor *self,
                                                             gboolean is_set);
    gboolean            clutter_actor_get_fixed_position_set
                                                            (ClutterActor *self);
    void                clutter_actor_set_request_mode      (ClutterActor *self,
                                                             ClutterRequestMode mode);
    ClutterRequestMode  clutter_actor_get_request_mode      (ClutterActor *self);
    gboolean            clutter_actor_has_allocation        (ClutterActor *self);
    enum                ClutterActorAlign;
    void                clutter_actor_set_x_align           (ClutterActor *self,
                                                             ClutterActorAlign x_align);
    ClutterActorAlign   clutter_actor_get_x_align           (ClutterActor *self);
    void                clutter_actor_set_y_align           (ClutterActor *self,
                                                             ClutterActorAlign y_align);
    ClutterActorAlign   clutter_actor_get_y_align           (ClutterActor *self);
    struct              ClutterMargin;
    ClutterMargin *     clutter_margin_copy                 (const ClutterMargin *margin_);
    void                clutter_margin_free                 (ClutterMargin *margin_);
    ClutterMargin *     clutter_margin_new                  (void);
    void                clutter_actor_set_margin            (ClutterActor *self,
                                                             const ClutterMargin *margin);
    void                clutter_actor_get_margin            (ClutterActor *self,
                                                             ClutterMargin *margin);
    void                clutter_actor_set_margin_top        (ClutterActor *self,
                                                             gfloat margin);
    gfloat              clutter_actor_get_margin_top        (ClutterActor *self);
    void                clutter_actor_set_margin_right      (ClutterActor *self,
                                                             gfloat margin);
    gfloat              clutter_actor_get_margin_right      (ClutterActor *self);
    void                clutter_actor_set_margin_bottom     (ClutterActor *self,
                                                             gfloat margin);
    gfloat              clutter_actor_get_margin_bottom     (ClutterActor *self);
    void                clutter_actor_set_margin_left       (ClutterActor *self,
                                                             gfloat margin);
    gfloat              clutter_actor_get_margin_left       (ClutterActor *self);
    void                clutter_actor_set_x_expand          (ClutterActor *self,
                                                             gboolean expand);
    gboolean            clutter_actor_get_x_expand          (ClutterActor *self);
    void                clutter_actor_set_y_expand          (ClutterActor *self,
                                                             gboolean expand);
    gboolean            clutter_actor_get_y_expand          (ClutterActor *self);
    gboolean            clutter_actor_needs_expand          (ClutterActor *self,
                                                             ClutterOrientation orientation);
    void                clutter_actor_set_layout_manager    (ClutterActor *self,
                                                             ClutterLayoutManager *manager);
    ClutterLayoutManager * clutter_actor_get_layout_manager (ClutterActor *self);
    void                clutter_actor_set_background_color  (ClutterActor *self,
                                                             const ClutterColor *color);
    void                clutter_actor_get_background_color  (ClutterActor *self,
                                                             ClutterColor *color);

    void                clutter_actor_set_geometry          (ClutterActor *self,
                                                             const ClutterGeometry *geometry);
    void                clutter_actor_get_geometry          (ClutterActor *self,
                                                             ClutterGeometry *geometry);
    void                clutter_actor_set_size              (ClutterActor *self,
                                                             gfloat width,
                                                             gfloat height);
    void                clutter_actor_get_size              (ClutterActor *self,
                                                             gfloat *width,
                                                             gfloat *height);
    void                clutter_actor_set_position          (ClutterActor *self,
                                                             gfloat x,
                                                             gfloat y);
    void                clutter_actor_get_position          (ClutterActor *self,
                                                             gfloat *x,
                                                             gfloat *y);
    void                clutter_actor_set_width             (ClutterActor *self,
                                                             gfloat width);
    gfloat              clutter_actor_get_width             (ClutterActor *self);
    void                clutter_actor_set_height            (ClutterActor *self,
                                                             gfloat height);
    gfloat              clutter_actor_get_height            (ClutterActor *self);
    void                clutter_actor_set_x                 (ClutterActor *self,
                                                             gfloat x);
    gfloat              clutter_actor_get_x                 (ClutterActor *self);
    void                clutter_actor_set_y                 (ClutterActor *self,
                                                             gfloat y);
    gfloat              clutter_actor_get_y                 (ClutterActor *self);
    void                clutter_actor_move_by               (ClutterActor *self,
                                                             gfloat dx,
                                                             gfloat dy);

    void                clutter_actor_set_z_position        (ClutterActor *self,
                                                             gfloat z_position);
    gfloat              clutter_actor_get_z_position        (ClutterActor *self);
    void                clutter_actor_set_pivot_point       (ClutterActor *self,
                                                             gfloat pivot_x,
                                                             gfloat pivot_y);
    void                clutter_actor_get_pivot_point       (ClutterActor *self,
                                                             gfloat *pivot_x,
                                                             gfloat *pivot_y);
    void                clutter_actor_set_pivot_point_z     (ClutterActor *self,
                                                             gfloat pivot_z);
    gfloat              clutter_actor_get_pivot_point_z     (ClutterActor *self);
    void                clutter_actor_set_scale             (ClutterActor *self,
                                                             gdouble scale_x,
                                                             gdouble scale_y);
    void                clutter_actor_get_scale             (ClutterActor *self,
                                                             gdouble *scale_x,
                                                             gdouble *scale_y);
    void                clutter_actor_set_scale_z           (ClutterActor *self,
                                                             gdouble scale_z);
    gdouble             clutter_actor_get_scale_z           (ClutterActor *self);
    gboolean            clutter_actor_is_scaled             (ClutterActor *self);
    void                clutter_actor_set_rotation_angle    (ClutterActor *self,
                                                             ClutterRotateAxis axis,
                                                             gdouble angle);
    gdouble             clutter_actor_get_rotation_angle    (ClutterActor *self,
                                                             ClutterRotateAxis axis);
    gboolean            clutter_actor_is_rotated            (ClutterActor *self);
    void                clutter_actor_set_translation       (ClutterActor *self,
                                                             gfloat translate_x,
                                                             gfloat translate_y,
                                                             gfloat translate_z);
    void                clutter_actor_get_translation       (ClutterActor *self,
                                                             gfloat *translate_x,
                                                             gfloat *translate_y,
                                                             gfloat *translate_z);
    void                clutter_actor_set_transform         (ClutterActor *self,
                                                             const ClutterMatrix *transform);
    void                clutter_actor_get_transform         (ClutterActor *self,
                                                             ClutterMatrix *transform);
    void                clutter_actor_set_child_transform   (ClutterActor *self,
                                                             const ClutterMatrix *transform);
    void                clutter_actor_get_child_transform   (ClutterActor *self,
                                                             ClutterMatrix *transform);
    void                clutter_actor_apply_transform_to_point
                                                            (ClutterActor *self,
                                                             const ClutterVertex *point,
                                                             ClutterVertex *vertex);
    gboolean            clutter_actor_transform_stage_point (ClutterActor *self,
                                                             gfloat x,
                                                             gfloat y,
                                                             gfloat *x_out,
                                                             gfloat *y_out);
    void                clutter_actor_apply_relative_transform_to_point
                                                            (ClutterActor *self,
                                                             ClutterActor *ancestor,
                                                             const ClutterVertex *point,
                                                             ClutterVertex *vertex);
    void                clutter_actor_get_transformed_position
                                                            (ClutterActor *self,
                                                             gfloat *x,
                                                             gfloat *y);
    void                clutter_actor_get_transformed_size  (ClutterActor *self,
                                                             gfloat *width,
                                                             gfloat *height);
    guint8              clutter_actor_get_paint_opacity     (ClutterActor *self);
    gboolean            clutter_actor_get_paint_visibility  (ClutterActor *self);
    void                clutter_actor_get_abs_allocation_vertices
                                                            (ClutterActor *self,
                                                             ClutterVertex verts[]);
    const ClutterPaintVolume * clutter_actor_get_paint_volume
                                                            (ClutterActor *self);
    gboolean            clutter_actor_get_paint_box         (ClutterActor *self,
                                                             ClutterActorBox *box);
    const ClutterPaintVolume * clutter_actor_get_transformed_paint_volume
                                                            (ClutterActor *self,
                                                             ClutterActor *relative_to_ancestor);
    const ClutterPaintVolume * clutter_actor_get_default_paint_volume
                                                            (ClutterActor *self);

    void                clutter_actor_set_content           (ClutterActor *self,
                                                             ClutterContent *content);
    ClutterContent *    clutter_actor_get_content           (ClutterActor *self);
    enum                ClutterContentGravity;
    void                clutter_actor_set_content_gravity   (ClutterActor *self,
                                                             ClutterContentGravity gravity);
    ClutterContentGravity clutter_actor_get_content_gravity (ClutterActor *self);
    enum                ClutterScalingFilter;
    void                clutter_actor_set_content_scaling_filters
                                                            (ClutterActor *self,
                                                             ClutterScalingFilter min_filter,
                                                             ClutterScalingFilter mag_filter);
    void                clutter_actor_get_content_scaling_filters
                                                            (ClutterActor *self,
                                                             ClutterScalingFilter *min_filter,
                                                             ClutterScalingFilter *mag_filter);
    enum                ClutterContentRepeat;
    void                clutter_actor_set_content_repeat    (ClutterActor *self,
                                                             ClutterContentRepeat repeat);
    ClutterContentRepeat clutter_actor_get_content_repeat   (ClutterActor *self);
    void                clutter_actor_get_content_box       (ClutterActor *self,
                                                             ClutterActorBox *box);
    void                clutter_actor_set_clip              (ClutterActor *self,
                                                             gfloat xoff,
                                                             gfloat yoff,
                                                             gfloat width,
                                                             gfloat height);
    void                clutter_actor_remove_clip           (ClutterActor *self);
    gboolean            clutter_actor_has_clip              (ClutterActor *self);
    void                clutter_actor_get_clip              (ClutterActor *self,
                                                             gfloat *xoff,
                                                             gfloat *yoff,
                                                             gfloat *width,
                                                             gfloat *height);
    void                clutter_actor_set_clip_to_allocation
                                                            (ClutterActor *self,
                                                             gboolean clip_set);
    gboolean            clutter_actor_get_clip_to_allocation
                                                            (ClutterActor *self);
    void                clutter_actor_set_opacity           (ClutterActor *self,
                                                             guint8 opacity);
    guint8              clutter_actor_get_opacity           (ClutterActor *self);
    enum                ClutterOffscreenRedirect;
    void                clutter_actor_set_offscreen_redirect
                                                            (ClutterActor *self,
                                                             ClutterOffscreenRedirect redirect);
    ClutterOffscreenRedirect clutter_actor_get_offscreen_redirect
                                                            (ClutterActor *self);
    gboolean            clutter_actor_is_in_clone_paint     (ClutterActor *self);

    void                clutter_actor_add_child             (ClutterActor *self,
                                                             ClutterActor *child);
    void                clutter_actor_insert_child_above    (ClutterActor *self,
                                                             ClutterActor *child,
                                                             ClutterActor *sibling);
    void                clutter_actor_insert_child_at_index (ClutterActor *self,
                                                             ClutterActor *child,
                                                             gint index_);
    void                clutter_actor_insert_child_below    (ClutterActor *self,
                                                             ClutterActor *child,
                                                             ClutterActor *sibling);
    void                clutter_actor_replace_child         (ClutterActor *self,
                                                             ClutterActor *old_child,
                                                             ClutterActor *new_child);
    void                clutter_actor_remove_child          (ClutterActor *self,
                                                             ClutterActor *child);
    void                clutter_actor_remove_all_children   (ClutterActor *self);
    void                clutter_actor_destroy_all_children  (ClutterActor *self);
    ClutterActor *      clutter_actor_get_first_child       (ClutterActor *self);
    ClutterActor *      clutter_actor_get_next_sibling      (ClutterActor *self);
    ClutterActor *      clutter_actor_get_previous_sibling  (ClutterActor *self);
    ClutterActor *      clutter_actor_get_last_child        (ClutterActor *self);
    ClutterActor *      clutter_actor_get_child_at_index    (ClutterActor *self,
                                                             gint index_);
    GList *             clutter_actor_get_children          (ClutterActor *self);
    gint                clutter_actor_get_n_children        (ClutterActor *self);
    ClutterActor *      clutter_actor_get_parent            (ClutterActor *self);
    void                clutter_actor_set_child_above_sibling
                                                            (ClutterActor *self,
                                                             ClutterActor *child,
                                                             ClutterActor *sibling);
    void                clutter_actor_set_child_at_index    (ClutterActor *self,
                                                             ClutterActor *child,
                                                             gint index_);
    void                clutter_actor_set_child_below_sibling
                                                            (ClutterActor *self,
                                                             ClutterActor *child,
                                                             ClutterActor *sibling);
    gboolean            clutter_actor_contains              (ClutterActor *self,
                                                             ClutterActor *descendant);
    ClutterActor *      clutter_actor_get_stage             (ClutterActor *actor);
                        ClutterActorIter;
    void                clutter_actor_iter_init             (ClutterActorIter *iter,
                                                             ClutterActor *root);
    gboolean            clutter_actor_iter_is_valid         (const ClutterActorIter *iter);
    gboolean            clutter_actor_iter_next             (ClutterActorIter *iter,
                                                             ClutterActor **child);
    gboolean            clutter_actor_iter_prev             (ClutterActorIter *iter,
                                                             ClutterActor **child);
    void                clutter_actor_iter_remove           (ClutterActorIter *iter);
    void                clutter_actor_iter_destroy          (ClutterActorIter *iter);

    void                clutter_actor_save_easing_state     (ClutterActor *self);
    void                clutter_actor_restore_easing_state  (ClutterActor *self);
    void                clutter_actor_set_easing_duration   (ClutterActor *self,
                                                             guint msecs);
    guint               clutter_actor_get_easing_duration   (ClutterActor *self);
    void                clutter_actor_set_easing_mode       (ClutterActor *self,
                                                             ClutterAnimationMode mode);
    ClutterAnimationMode clutter_actor_get_easing_mode      (ClutterActor *self);
    void                clutter_actor_set_easing_delay      (ClutterActor *self,
                                                             guint msecs);
    guint               clutter_actor_get_easing_delay      (ClutterActor *self);
    ClutterTransition * clutter_actor_get_transition        (ClutterActor *self,
                                                             const char *name);
    void                clutter_actor_add_transition        (ClutterActor *self,
                                                             const char *name,
                                                             ClutterTransition *transition);
    void                clutter_actor_remove_transition     (ClutterActor *self,
                                                             const char *name);
    void                clutter_actor_remove_all_transitions
                                                            (ClutterActor *self);

    void                clutter_actor_set_reactive          (ClutterActor *actor,
                                                             gboolean reactive);
    gboolean            clutter_actor_get_reactive          (ClutterActor *actor);
    gboolean            clutter_actor_has_key_focus         (ClutterActor *self);
    void                clutter_actor_grab_key_focus        (ClutterActor *self);
    gboolean            clutter_actor_has_pointer           (ClutterActor *self);
    PangoContext *      clutter_actor_get_pango_context     (ClutterActor *self);
    PangoContext *      clutter_actor_create_pango_context  (ClutterActor *self);
    PangoLayout *       clutter_actor_create_pango_layout   (ClutterActor *self,
                                                             const gchar *text);
    void                clutter_actor_set_text_direction    (ClutterActor *self,
                                                             ClutterTextDirection text_dir);
    ClutterTextDirection clutter_actor_get_text_direction   (ClutterActor *self);
    AtkObject *         clutter_actor_get_accessible        (ClutterActor *self);

    void                clutter_actor_add_action            (ClutterActor *self,
                                                             ClutterAction *action);
    void                clutter_actor_add_action_with_name  (ClutterActor *self,
                                                             const gchar *name,
                                                             ClutterAction *action);
    void                clutter_actor_remove_action         (ClutterActor *self,
                                                             ClutterAction *action);
    void                clutter_actor_remove_action_by_name (ClutterActor *self,
                                                             const gchar *name);
    gboolean            clutter_actor_has_actions           (ClutterActor *self);
    GList *             clutter_actor_get_actions           (ClutterActor *self);
    ClutterAction *     clutter_actor_get_action            (ClutterActor *self,
                                                             const gchar *name);
    void                clutter_actor_clear_actions         (ClutterActor *self);
    void                clutter_actor_add_constraint        (ClutterActor *self,
                                                             ClutterConstraint *constraint);
    void                clutter_actor_add_constraint_with_name
                                                            (ClutterActor *self,
                                                             const gchar *name,
                                                             ClutterConstraint *constraint);
    void                clutter_actor_remove_constraint     (ClutterActor *self,
                                                             ClutterConstraint *constraint);
    void                clutter_actor_remove_constraint_by_name
                                                            (ClutterActor *self,
                                                             const gchar *name);
    gboolean            clutter_actor_has_constraints       (ClutterActor *self);
    GList *             clutter_actor_get_constraints       (ClutterActor *self);
    ClutterConstraint * clutter_actor_get_constraint        (ClutterActor *self,
                                                             const gchar *name);
    void                clutter_actor_clear_constraints     (ClutterActor *self);
    void                clutter_actor_add_effect            (ClutterActor *self,
                                                             ClutterEffect *effect);
    void                clutter_actor_add_effect_with_name  (ClutterActor *self,
                                                             const gchar *name,
                                                             ClutterEffect *effect);
    void                clutter_actor_remove_effect         (ClutterActor *self,
                                                             ClutterEffect *effect);
    void                clutter_actor_remove_effect_by_name (ClutterActor *self,
                                                             const gchar *name);
    gboolean            clutter_actor_has_effects           (ClutterActor *self);
    GList *             clutter_actor_get_effects           (ClutterActor *self);
    ClutterEffect *     clutter_actor_get_effect            (ClutterActor *self,
                                                             const gchar *name);
    void                clutter_actor_clear_effects         (ClutterActor *self);

    void                clutter_actor_set_scale_full        (ClutterActor *self,
                                                             gdouble scale_x,
                                                             gdouble scale_y,
                                                             gfloat center_x,
                                                             gfloat center_y);
    void                clutter_actor_set_scale_with_gravity
                                                            (ClutterActor *self,
                                                             gdouble scale_x,
                                                             gdouble scale_y,
                                                             ClutterGravity gravity);
    void                clutter_actor_get_scale_center      (ClutterActor *self,
                                                             gfloat *center_x,
                                                             gfloat *center_y);
    ClutterGravity      clutter_actor_get_scale_gravity     (ClutterActor *self);
    void                clutter_actor_set_depth             (ClutterActor *self,
                                                             gfloat depth);
    gfloat              clutter_actor_get_depth             (ClutterActor *self);
    void                clutter_actor_push_internal         (ClutterActor *self);
    void                clutter_actor_pop_internal          (ClutterActor *self);
    void                clutter_actor_set_parent            (ClutterActor *self,
                                                             ClutterActor *parent);
    void                clutter_actor_reparent              (ClutterActor *self,
                                                             ClutterActor *new_parent);
    void                clutter_actor_unparent              (ClutterActor *self);
    void                clutter_actor_raise                 (ClutterActor *self,
                                                             ClutterActor *below);
    void                clutter_actor_lower                 (ClutterActor *self,
                                                             ClutterActor *above);
    void                clutter_actor_raise_top             (ClutterActor *self);
    void                clutter_actor_lower_bottom          (ClutterActor *self);
    gboolean            clutter_actor_set_shader            (ClutterActor *self,
                                                             ClutterShader *shader);
    ClutterShader *     clutter_actor_get_shader            (ClutterActor *self);
    void                clutter_actor_set_shader_param      (ClutterActor *self,
                                                             const gchar *param,
                                                             const GValue *value);
    void                clutter_actor_set_shader_param_float
                                                            (ClutterActor *self,
                                                             const gchar *param,
                                                             gfloat value);
    void                clutter_actor_set_shader_param_int  (ClutterActor *self,
                                                             const gchar *param,
                                                             gint value);
    void                clutter_actor_set_anchor_point      (ClutterActor *self,
                                                             gfloat anchor_x,
                                                             gfloat anchor_y);
    void                clutter_actor_get_anchor_point      (ClutterActor *self,
                                                             gfloat *anchor_x,
                                                             gfloat *anchor_y);
    void                clutter_actor_set_anchor_point_from_gravity
                                                            (ClutterActor *self,
                                                             ClutterGravity gravity);
    ClutterGravity      clutter_actor_get_anchor_point_gravity
                                                            (ClutterActor *self);
    void                clutter_actor_move_anchor_point     (ClutterActor *self,
                                                             gfloat anchor_x,
                                                             gfloat anchor_y);
    void                clutter_actor_move_anchor_point_from_gravity
                                                            (ClutterActor *self,
                                                             ClutterGravity gravity);
    void                clutter_actor_set_rotation          (ClutterActor *self,
                                                             ClutterRotateAxis axis,
                                                             gdouble angle,
                                                             gfloat x,
                                                             gfloat y,
                                                             gfloat z);
    gdouble             clutter_actor_get_rotation          (ClutterActor *self,
                                                             ClutterRotateAxis axis,
                                                             gfloat *x,
                                                             gfloat *y,
                                                             gfloat *z);
    void                clutter_actor_set_z_rotation_from_gravity
                                                            (ClutterActor *self,
                                                             gdouble angle,
                                                             ClutterGravity gravity);
    ClutterGravity      clutter_actor_get_z_rotation_gravity
                                                            (ClutterActor *self);
    void                clutter_actor_get_transformation_matrix
                                                            (ClutterActor *self,
                                                             ClutterMatrix *matrix);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----ClutterActor
                   +----ClutterBox
                   +----ClutterTexture
                   +----ClutterClone
                   +----ClutterGroup
                   +----ClutterRectangle
                   +----ClutterScrollActor
                   +----ClutterText

## Implemented Interfaces

ClutterActor implements ClutterContainer, ClutterScriptable, ClutterAnimatable and AtkImplementorIface.

## Properties

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

## Signals

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

## 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";

2. translation by the actor's "depth";

3. scaling by the "scale-x" and "scale-y" factors;

4. rotation around the "rotation-angle-x" and "rotation-center-x";

5. rotation around the "rotation-angle-y" and "rotation-center-y";

6. rotation around the "rotation-angle-z" and "rotation-center-z";

7. negative translation by the "anchor-x" and "anchor-y" 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.

    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
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    #include <stdlib.h>
    #include <clutter/clutter.h>

    #define SIZE    128

    static gboolean
    animate_color (ClutterActor *actor,
                   ClutterEvent *event)
    {
      static gboolean toggled = TRUE;
      const ClutterColor *end_color;

      if (toggled)
        end_color = CLUTTER_COLOR_Blue;
      else
        end_color = CLUTTER_COLOR_Red;

      clutter_actor_save_easing_state (actor);
      clutter_actor_set_easing_duration (actor, 500);
      clutter_actor_set_easing_mode (actor, CLUTTER_LINEAR);
      clutter_actor_set_background_color (actor, end_color);
      clutter_actor_restore_easing_state (actor);

      toggled = !toggled;

      return CLUTTER_EVENT_STOP;
    }

    static gboolean
    on_crossing (ClutterActor *actor,
                 ClutterEvent *event)
    {
      gboolean is_enter = clutter_event_type (event) == CLUTTER_ENTER;
      float zpos;

      if (is_enter)
        zpos = -250.0;
      else
        zpos = 0.0;

      clutter_actor_save_easing_state (actor);
      clutter_actor_set_easing_duration (actor, 500);
      clutter_actor_set_easing_mode (actor, CLUTTER_EASE_OUT_BOUNCE);
      clutter_actor_set_z_position (actor, zpos);
      clutter_actor_restore_easing_state (actor);

      return CLUTTER_EVENT_STOP;
    }

    static void
    on_transition_stopped (ClutterActor *actor,
                           const gchar  *transition_name,
                           gboolean      is_finished)
    {
      clutter_actor_save_easing_state (actor);
      clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 0.0f);
      clutter_actor_restore_easing_state (actor);

      /* disconnect so we don't get multiple notifications */
      g_signal_handlers_disconnect_by_func (actor,
                                            on_transition_stopped,
                                            NULL);
    }

    static gboolean
    animate_rotation (ClutterActor *actor,
                      ClutterEvent *event)
    {
      clutter_actor_save_easing_state (actor);
      clutter_actor_set_easing_duration (actor, 1000);

      clutter_actor_set_rotation_angle (actor, CLUTTER_Y_AXIS, 360.0);

      clutter_actor_restore_easing_state (actor);

      /* get a notification when the rotation-angle-y transition ends */
      g_signal_connect (actor,
                        "transition-stopped::rotation-angle-y",
                        G_CALLBACK (on_transition_stopped),
                        NULL);

      return CLUTTER_EVENT_STOP;
    }

    int
    main (int argc, char *argv[])
    {
      ClutterActor *stage, *vase;
      ClutterActor *flowers[3];

      if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
        return EXIT_FAILURE;

      stage = clutter_stage_new ();
      g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
      clutter_stage_set_title (CLUTTER_STAGE (stage), "Three Flowers in a Vase");
      clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);

      /* there are three flowers in a vase */
      vase = clutter_actor_new ();
      clutter_actor_set_name (vase, "vase");
      clutter_actor_set_layout_manager (vase, clutter_box_layout_new ());
      clutter_actor_set_background_color (vase, CLUTTER_COLOR_LightSkyBlue);
      clutter_actor_add_constraint (vase, clutter_align_constraint_new (stage, CLUTTER_ALIGN_BOTH, 0.5));
      clutter_actor_add_child (stage, vase);

      flowers[0] = clutter_actor_new ();
      clutter_actor_set_name (flowers[0], "flower.1");
      clutter_actor_set_size (flowers[0], SIZE, SIZE);
      clutter_actor_set_margin_left (flowers[0], 12);
      clutter_actor_set_background_color (flowers[0], CLUTTER_COLOR_Red);
      clutter_actor_set_reactive (flowers[0], TRUE);
      clutter_actor_add_child (vase, flowers[0]);
      g_signal_connect (flowers[0], "button-press-event",
                        G_CALLBACK (animate_color),
                        NULL);

      flowers[1] = clutter_actor_new ();
      clutter_actor_set_name (flowers[1], "flower.2");
      clutter_actor_set_size (flowers[1], SIZE, SIZE);
      clutter_actor_set_margin_top (flowers[1], 12);
      clutter_actor_set_margin_left (flowers[1], 6);
      clutter_actor_set_margin_right (flowers[1], 6);
      clutter_actor_set_margin_bottom (flowers[1], 12);
      clutter_actor_set_background_color (flowers[1], CLUTTER_COLOR_Yellow);
      clutter_actor_set_reactive (flowers[1], TRUE);
      clutter_actor_add_child (vase, flowers[1]);
      g_signal_connect (flowers[1], "enter-event",
                        G_CALLBACK (on_crossing),
                        NULL);
      g_signal_connect (flowers[1], "leave-event",
                        G_CALLBACK (on_crossing),
                        NULL);

      /* the third one is green */
      flowers[2] = clutter_actor_new ();
      clutter_actor_set_name (flowers[2], "flower.3");
      clutter_actor_set_size (flowers[2], SIZE, SIZE);
      clutter_actor_set_margin_right (flowers[2], 12);
      clutter_actor_set_background_color (flowers[2], CLUTTER_COLOR_Green);
      clutter_actor_set_pivot_point (flowers[2], 0.5f, 0.0f);
      clutter_actor_set_reactive (flowers[2], TRUE);
      clutter_actor_add_child (vase, flowers[2]);
      g_signal_connect (flowers[2], "button-press-event",
                        G_CALLBACK (animate_rotation),
                        NULL);

      clutter_actor_show (stage);

      clutter_main ();

      return EXIT_SUCCESS;
    }

Figure 1. Actors

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

Setting the Content property. A ClutterContent is a delegate object that takes over the painting operation of one, or more actors. The ClutterContent painting will be performed on top of the "background-color" of the actor, and before calling 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);

Overriding the paint_node virtual function. 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
    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);
    }

Overriding the paint virtual function. The `ClutterActorClass.paint()` virtual function is invoked when the "paint" signal is emitted, and after the other signal handlers have been invoked. Overriding the paint virtual function gives total control to the paint sequence of the actor itself, including the children of the actor, if any.

### Warning

It is strongly discouraged to override the `ClutterActorClass.paint()` virtual function, as well as connecting to the "paint" signal. These hooks into the paint sequence are considered legacy, and will be removed when the Clutter API changes.

### 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, along with other event signals if needed, is emitted; this phase is also called the bubble phase. At any point of the signal emission, signal handlers can stop the propagation through the scene graph by returning `CLUTTER_EVENT_STOP`; otherwise, they can continue the propagation by returning `CLUTTER_EVENT_PROPAGATE`.

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

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

### Note

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
    /* assume that the actor is currently positioned at (100, 100) */
    clutter_actor_save_easing_state (actor);
    clutter_actor_set_position (actor, 500, 500);
    clutter_actor_restore_easing_state (actor);

The example above will trigger an implicit animation of the actor between its current position to a new position.It is possible to animate multiple properties of an actor at the same time, and you can animate multiple actors at the same time as well, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    /* animate the actor's opacity and depth */
    clutter_actor_save_easing_state (actor);
    clutter_actor_set_opacity (actor, 0);
    clutter_actor_set_depth (actor, -100);
    clutter_actor_restore_easing_state (actor);

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

Implicit animations use a default duration of 250 milliseconds, and a default easing mode of `CLUTTER_EASE_OUT_CUBIC`, unless you call `clutter_actor_set_easing_mode()` and `clutter_actor_set_easing_duration()` after changing the easing state of the actor.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 retrieve the ClutterTransition used by the animatable properties by using `clutter_actor_get_transition()` and using the property name as the transition name.

Explicit animations. The explicit animation model supported by Clutter requires that you create a ClutterTransition object, and 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
    24
    25
    /* 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; this will
     * start the animation.
     */
    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
    2
    3
    "rotation" : [
      { "<axis>" : [ <angle>, [ <center> ] ] }
    ]

where the axis is the name of an enumeration value of type ClutterRotateAxis and angle is a floating point value representing the rotation angle on the given axis, in degrees.

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

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 or constraint, as specified by the "name" property.

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

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

    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
    40
    41
    42
    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;
    }

## Details

### CLUTTER_ACTOR_SET_FLAGS()

    #define CLUTTER_ACTOR_SET_FLAGS(a,f)    (((ClutterActor*)(a))->flags |= (f))

Sets the given flags on a ClutterActor

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

### CLUTTER_ACTOR_UNSET_FLAGS()

    #define CLUTTER_ACTOR_UNSET_FLAGS(a,f)  (((ClutterActor*)(a))->flags &= ~(f))

Unsets the given flags on a ClutterActor

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

### CLUTTER_ACTOR_IS_MAPPED()

    #define CLUTTER_ACTOR_IS_MAPPED(a)      ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_MAPPED) != FALSE)

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.

`a` : | a ClutterActor

Since 0.2

### CLUTTER_ACTOR_IS_REALIZED()

    #define CLUTTER_ACTOR_IS_REALIZED(a)    ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_REALIZED) != FALSE)

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.

`a` : | a ClutterActor

Since 0.2

### CLUTTER_ACTOR_IS_VISIBLE()

    #define CLUTTER_ACTOR_IS_VISIBLE(a)     ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_VISIBLE) != FALSE)

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

`a` : | a ClutterActor

Since 0.2

### CLUTTER_ACTOR_IS_REACTIVE()

    #define CLUTTER_ACTOR_IS_REACTIVE(a)    ((((ClutterActor*)(a))->flags & CLUTTER_ACTOR_REACTIVE) != FALSE)

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

Only reactive actors will receive event-related signals.

`a` : | a ClutterActor

Since 0.6

### enum ClutterActorFlags

    typedef enum {
     /*< prefix=CLUTTER_ACTOR >*/
      CLUTTER_ACTOR_MAPPED    = 1 << 1,
      CLUTTER_ACTOR_REALIZED  = 1 << 2,
      CLUTTER_ACTOR_REACTIVE  = 1 << 3,
      CLUTTER_ACTOR_VISIBLE   = 1 << 4,
      CLUTTER_ACTOR_NO_LAYOUT = 1 << 5
    } ClutterActorFlags;

Flags used to signal the state of an actor.

`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

    typedef enum {
     /*< prefix=CLUTTER_REQUEST >*/
      CLUTTER_REQUEST_HEIGHT_FOR_WIDTH,
      CLUTTER_REQUEST_WIDTH_FOR_HEIGHT
    } ClutterRequestMode;

Specifies the type of requests for a ClutterActor.

`CLUTTER_REQUEST_HEIGHT_FOR_WIDTH` | Height for width requests
`CLUTTER_REQUEST_WIDTH_FOR_HEIGHT` | Width for height requests

Since 0.8

### CLUTTER_CALLBACK()

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

Convenience macro to cast a function to ClutterCallback

`f` : | a function

### ClutterCallback ()

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

Generic callback

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

### ClutterActor

    typedef struct {
      guint32 flags;
    } ClutterActor;

Base class for actors.

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.

`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"

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

`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

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

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

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

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

### Warning

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

Retrieves the unique id for `self`.

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

`self` : | A ClutterActor

### clutter_actor_show_all ()

    void                clutter_actor_show_all              (ClutterActor *self);

### Warning

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

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

`self` : | A ClutterActor

### clutter_actor_hide_all ()

    void                clutter_actor_hide_all              (ClutterActor *self);

### Warning

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

`self` : | a ClutterActor

Since 0.2

### clutter_actor_realize ()

    void                clutter_actor_realize               (ClutterActor *self);

### Warning

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

`self` : | A ClutterActor

### clutter_actor_unrealize ()

    void                clutter_actor_unrealize             (ClutterActor *self);

### Warning

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

`self` : | A ClutterActor

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

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

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

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

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

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

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

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

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

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

### Note

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.

`self` : | A ClutterActor

Since 1.0

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

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

`self` : | a ClutterActor
Returns : | whether the actor has any mapped clones.

Since 1.16

### enum ClutterAllocationFlags

    typedef enum {
      CLUTTER_ALLOCATION_NONE         = 0,
      CLUTTER_ABSOLUTE_ORIGIN_CHANGED = 1 << 1,
      CLUTTER_DELEGATE_LAYOUT         = 1 << 2
    } ClutterAllocationFlags;

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

`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

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

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

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

    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.

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

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

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

### Note

Do not call any of the clutter_actor_get_allocation_*() family of functions inside the implementation of the `get_preferred_width()` or `get_preferred_height()` virtual functions.

`self` : | A 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);

### Warning

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

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

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

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

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

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

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

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

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

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

`self` : | a ClutterActor
Returns : | `TRUE` if the actor has an up-to-date allocation

Since 1.4

### enum ClutterActorAlign

    typedef enum {
      CLUTTER_ACTOR_ALIGN_FILL,
      CLUTTER_ACTOR_ALIGN_START,
      CLUTTER_ACTOR_ALIGN_CENTER,
      CLUTTER_ACTOR_ALIGN_END
    } 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`.

`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

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

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

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

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

`self` : | a ClutterActor
Returns : | the vertical alignment policy.

Since 1.10

### struct ClutterMargin

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

A representation of the components of a margin.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Warning

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

`self` : | A ClutterActor
`geometry` : | A ClutterGeometry

### clutter_actor_get_geometry ()

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

### Warning

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### Note

This function can be computationally intensive.

### Note

This function only works when the allocation is up-to-date, i.e. inside of `paint()`.

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

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

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

### Note

When the actor (or one of its ancestors) is rotated around the X or Y axis, it no longer appears as on the stage as a rectangle, but as a generic quadrangle; in that case this function returns the size of the smallest rectangle that encapsulates the entire quad. Please note that in this case no assumptions can be made about the relative position of this envelope to the absolute position of the actor, as returned by `clutter_actor_get_transformed_position()`; if you need this information, you need to use `clutter_actor_get_abs_allocation_vertices()` to get the coords of the actual quadrangle.

`self` : | A 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.

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

`self` : | A ClutterActor
Returns : | `TRUE` if the actor is visibile and will be painted.

Since 0.8.4

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

`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 ``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 ``get_paint_volume()`` ensure their volume has a depth of 0. (This will be true so long as you don't call `clutter_paint_volume_set_depth()`.)

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

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

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

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

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

`self` : | a ClutterActor
Returns : | a pointer to the ClutterContent instance, or `NULL` if none was set. [transfer none]

Since 1.10

### enum ClutterContentGravity

    typedef enum {
      CLUTTER_CONTENT_GRAVITY_TOP_LEFT,
      CLUTTER_CONTENT_GRAVITY_TOP,
      CLUTTER_CONTENT_GRAVITY_TOP_RIGHT,

      CLUTTER_CONTENT_GRAVITY_LEFT,
      CLUTTER_CONTENT_GRAVITY_CENTER,
      CLUTTER_CONTENT_GRAVITY_RIGHT,

      CLUTTER_CONTENT_GRAVITY_BOTTOM_LEFT,
      CLUTTER_CONTENT_GRAVITY_BOTTOM,
      CLUTTER_CONTENT_GRAVITY_BOTTOM_RIGHT,

      CLUTTER_CONTENT_GRAVITY_RESIZE_FILL,
      CLUTTER_CONTENT_GRAVITY_RESIZE_ASPECT
    } ClutterContentGravity;

Controls the alignment of the ClutterContent inside a ClutterActor.

`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

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

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

`self` : | a ClutterActor
Returns : | the content gravity

Since 1.10

### enum ClutterScalingFilter

    typedef enum {
      CLUTTER_SCALING_FILTER_LINEAR,
      CLUTTER_SCALING_FILTER_NEAREST,
      CLUTTER_SCALING_FILTER_TRILINEAR
    } ClutterScalingFilter;

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

`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

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

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

`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

### enum ClutterContentRepeat

    typedef enum {
      CLUTTER_REPEAT_NONE   = 0,
      CLUTTER_REPEAT_X_AXIS = 1 << 0,
      CLUTTER_REPEAT_Y_AXIS = 1 << 1,
      CLUTTER_REPEAT_BOTH   = CLUTTER_REPEAT_X_AXIS | CLUTTER_REPEAT_Y_AXIS
    } ClutterContentRepeat;

Content repeat modes.

`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

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

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

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

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

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

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

`self` : | a ClutterActor
Returns : | `TRUE` if the actor has a clip area set.

Since 0.1.1

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

`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

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

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

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

`self` : | a ClutterActor
Returns : | the opacity of the actor

### enum ClutterOffscreenRedirect

    typedef enum {
     /*< prefix=CLUTTER_OFFSCREEN_REDIRECT >*/
      CLUTTER_OFFSCREEN_REDIRECT_AUTOMATIC_FOR_OPACITY = 1<<0,
      CLUTTER_OFFSCREEN_REDIRECT_ALWAYS = 1<<1
    } ClutterOffscreenRedirect;

Possible flags to pass to `clutter_actor_set_offscreen_redirect()`.

`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

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

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

`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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`actor` : | a ClutterActor
Returns : | the stage containing the actor, or `NULL`. [transfer none][type Clutter.Stage]

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

### 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 */
      }

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

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

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

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

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

`iter` : | a ClutterActorIter

Since 1.10

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`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

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

`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

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

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

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

`self` : | a ClutterActor
`text` : | (allow-none) the text to set on the PangoLayout, or `NULL`
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

`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

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

`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

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

`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

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

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

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

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

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

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

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

`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

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

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

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

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

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

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

`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 effectss applied to `self`

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

`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

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

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

`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

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

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

`self` : | A ClutterActor
Returns : | the scale gravity

Since 1.0

### clutter_actor_set_depth ()

    void                clutter_actor_set_depth             (ClutterActor *self,
                                                             gfloat depth);

### Warning

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

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

### clutter_actor_get_depth ()

    gfloat              clutter_actor_get_depth             (ClutterActor *self);

### Warning

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

`self` : | a ClutterActor
Returns : | the depth of the actor

### clutter_actor_push_internal ()

    void                clutter_actor_push_internal         (ClutterActor *self);

### Warning

`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
    26
    27
    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.

`self` : | a ClutterActor

Since 1.2

### clutter_actor_pop_internal ()

    void                clutter_actor_pop_internal          (ClutterActor *self);

### Warning

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

`self` : | a ClutterActor

Since 1.2

### clutter_actor_set_parent ()

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

### Warning

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

`self` : | A ClutterActor
`parent` : | A new ClutterActor parent

### clutter_actor_reparent ()

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

### Warning

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

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

Since 0.2

### clutter_actor_unparent ()

    void                clutter_actor_unparent              (ClutterActor *self);

### Warning

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

`self` : | a ClutterActor

Since 0.1.1

### clutter_actor_raise ()

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

### Warning

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

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

### clutter_actor_lower ()

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

### Warning

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

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

### clutter_actor_raise_top ()

    void                clutter_actor_raise_top             (ClutterActor *self);

### Warning

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

`self` : | A ClutterActor

### clutter_actor_lower_bottom ()

    void                clutter_actor_lower_bottom          (ClutterActor *self);

### Warning

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

`self` : | A ClutterActor

### clutter_actor_set_shader ()

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

### Warning

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

### Note

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

`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" instead.

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.

`self` : | a ClutterActor
`gravity` : | ClutterGravity.

Since 0.6

### clutter_actor_get_anchor_point_gravity ()

    ClutterGravity      clutter_actor_get_anchor_point_gravity
                                                            (ClutterActor *self);

### Warning

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

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

### Warning

`clutter_actor_move_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 the actor, and adjusts the actor postion so that the relative position of the actor toward its parent remains the same.

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

### Warning

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

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

Since 1.0

## Property Details

### The `"actions"` property

      "actions"                  ClutterAction*        : Write

Adds a ClutterAction to the actor

Since 1.4

### The `"allocation"` property

      "allocation"               ClutterActorBox*      : Read

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

Since 0.8

### The `"anchor-gravity"` property

      "anchor-gravity"           ClutterGravity        : Read / Write

### Warning

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

The anchor point expressed as a ClutterGravity

### Warning

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.

Default value: CLUTTER_GRAVITY_NONE

Since 1.0

### The `"anchor-x"` property

      "anchor-x"                 gfloat                : Read / Write

### Warning

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

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

### Warning

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.

Default value: 0

Since 0.8

### The `"anchor-y"` property

      "anchor-y"                 gfloat                : Read / Write

### Warning

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

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

### Warning

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.

Default value: 0

Since 0.8

### The `"background-color"` property

      "background-color"         ClutterColor*         : Read / Write

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

The "background-color" property is animatable.

Since 1.10

### The `"background-color-set"` property

      "background-color-set"     gboolean              : Read

Whether the "background-color" property has been set.

Default value: FALSE

Since 1.10

### The `"child-transform"` property

      "child-transform"          ClutterMatrix*        : Read / Write

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.

Since 1.12

### The `"child-transform-set"` property

      "child-transform-set"      gboolean              : Read

Whether the "child-transform" property is set.

Default value: FALSE

Since 1.12

### The `"clip"` property

      "clip"                     ClutterGeometry*      : Read / Write

### Warning

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

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

### The `"clip-rect"` property

      "clip-rect"                ClutterRect*          : Read / Write

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.

Since 1.12

### The `"clip-to-allocation"` property

      "clip-to-allocation"       gboolean              : Read / Write

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

Default value: FALSE

Since 1.0

### The `"constraints"` property

      "constraints"              ClutterConstraint*    : Write

Adds a ClutterConstraint to the actor

Since 1.4

### The `"content"` property

      "content"                  ClutterContent*       : Read / Write

The ClutterContent implementation that controls the content of the actor.

Since 1.10

### The `"content-box"` property

      "content-box"              ClutterActorBox*      : Read

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.

Since 1.10

### The `"content-gravity"` property

      "content-gravity"          ClutterContentGravity  : Read / Write

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.

Default value: CLUTTER_CONTENT_GRAVITY_RESIZE_FILL

Since 1.10

### The `"content-repeat"` property

      "content-repeat"           ClutterContentRepeat  : Read / Write

The repeat policy for the actor's "content".

Since 1.12

### The `"depth"` property

      "depth"                    gfloat                : Read / Write

### Warning

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

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.

Default value: 0

Since 0.6

### The `"effect"` property

      "effect"                   ClutterEffect*        : Write

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

Since 1.4

### The `"first-child"` property

      "first-child"              ClutterActor*         : Read

The actor's first child.

Since 1.10

### The `"fixed-position-set"` property

      "fixed-position-set"       gboolean              : Read / Write

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

Default value: FALSE

Since 0.8

### The `"fixed-x"` property

      "fixed-x"                  gfloat                : Read / Write

The fixed X position of the actor in pixels.

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

Default value: 0

Since 0.8

### The `"fixed-y"` property

      "fixed-y"                  gfloat                : Read / Write

The fixed Y position of the actor in pixels.

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

Default value: 0

Since 0.8

### The `"has-clip"` property

      "has-clip"                 gboolean              : Read

Whether the actor has the "clip" property set or not

Default value: FALSE

### The `"has-pointer"` property

      "has-pointer"              gboolean              : Read

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

Default value: FALSE

Since 1.2

### The `"height"` property

      "height"                   gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

### The `"last-child"` property

      "last-child"               ClutterActor*         : Read

The actor's last child.

Since 1.10

### The `"layout-manager"` property

      "layout-manager"           ClutterLayoutManager*  : Read / Write

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

Since 1.10

### The `"magnification-filter"` property

      "magnification-filter"     ClutterScalingFilter  : Read / Write

The filter used when increasing the size of the content.

Default value: CLUTTER_SCALING_FILTER_LINEAR

### The `"mapped"` property

      "mapped"                   gboolean              : Read

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

Default value: FALSE

Since 1.0

### The `"margin-bottom"` property

      "margin-bottom"            gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 1.10

### The `"margin-left"` property

      "margin-left"              gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 1.10

### The `"margin-right"` property

      "margin-right"             gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 1.10

### The `"margin-top"` property

      "margin-top"               gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 1.10

### The `"min-height"` property

      "min-height"               gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 0.8

### The `"min-height-set"` property

      "min-height-set"           gboolean              : Read / Write

This flag controls whether the "min-height" property is used

Default value: FALSE

Since 0.8

### The `"min-width"` property

      "min-width"                gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

Since 0.8

### The `"min-width-set"` property

      "min-width-set"            gboolean              : Read / Write

This flag controls whether the "min-width" property is used

Default value: FALSE

Since 0.8

### The `"minification-filter"` property

      "minification-filter"      ClutterScalingFilter  : Read / Write

The filter used when reducing the size of the content.

Default value: CLUTTER_SCALING_FILTER_LINEAR

### The `"name"` property

      "name"                     gchar*                : Read / Write

The name of the actor

Default value: NULL

Since 0.2

### The `"natural-height"` property

      "natural-height"           gfloat                : Read / Write

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

Allowed values: >= 0

Default value: 0

Since 0.8

### The `"natural-height-set"` property

      "natural-height-set"       gboolean              : Read / Write

This flag controls whether the "natural-height" property is used

Default value: FALSE

Since 0.8

### The `"natural-width"` property

      "natural-width"            gfloat                : Read / Write

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

Allowed values: >= 0

Default value: 0

Since 0.8

### The `"natural-width-set"` property

      "natural-width-set"        gboolean              : Read / Write

This flag controls whether the "natural-width" property is used

Default value: FALSE

Since 0.8

### The `"offscreen-redirect"` property

      "offscreen-redirect"       ClutterOffscreenRedirect  : Read / Write

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.

Since 1.8

### The `"opacity"` property

      "opacity"                  guint                 : Read / Write

Opacity of an actor, between 0 (fully transparent) and 255 (fully opaque)

The "opacity" property is animatable.

Allowed values: <= 255

Default value: 255

### The `"pivot-point"` property

      "pivot-point"              ClutterPoint*         : Read / Write

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.

Since 1.12

### The `"pivot-point-z"` property

      "pivot-point-z"            gfloat                : Read / Write

The Z component of the "pivot-point", expressed as a value along the Z axis.

The "pivot-point-z" property is animatable.

Default value: 0

Since 1.12

### The `"position"` property

      "position"                 ClutterPoint*         : Read / Write

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.

Since 1.12

### The `"reactive"` property

      "reactive"                 gboolean              : Read / Write

Whether the actor is reactive to events or not

Only reactive actors will emit event-related signals

Default value: FALSE

Since 0.6

### The `"realized"` property

      "realized"                 gboolean              : Read

Whether the actor has been realized

Default value: FALSE

Since 1.0

### The `"request-mode"` property

      "request-mode"             ClutterRequestMode    : Read / Write

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
    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
      {
        clutter_actor_get_preferred_height (child, -1,
                                            &min_height,
                                            &natural_height);
        clutter_actor_get_preferred_width (child, natural_height,
                                           &min_width,
                                           &natural_width);
      }

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.

Default value: CLUTTER_REQUEST_HEIGHT_FOR_WIDTH

Since 0.8

### The `"rotation-angle-x"` property

      "rotation-angle-x"         gdouble               : Read / Write

The rotation angle on the X axis.

The "rotation-angle-x" property is animatable.

Default value: 0

Since 0.6

### The `"rotation-angle-y"` property

      "rotation-angle-y"         gdouble               : Read / Write

The rotation angle on the Y axis

The "rotation-angle-y" property is animatable.

Default value: 0

Since 0.6

### The `"rotation-angle-z"` property

      "rotation-angle-z"         gdouble               : Read / Write

The rotation angle on the Z axis

The "rotation-angle-z" property is animatable.

Default value: 0

Since 0.6

### The `"rotation-center-x"` property

      "rotation-center-x"        ClutterVertex*        : Read / Write

### Warning

`ClutterActor:rotation-center-x` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The rotation center on the X axis.

Since 0.6

### The `"rotation-center-y"` property

      "rotation-center-y"        ClutterVertex*        : Read / Write

### Warning

`ClutterActor:rotation-center-y` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The rotation center on the Y axis.

Since 0.6

### The `"rotation-center-z"` property

      "rotation-center-z"        ClutterVertex*        : Read / Write

### Warning

`ClutterActor:rotation-center-z` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The rotation center on the Z axis.

Since 0.6

### The `"rotation-center-z-gravity"` property

      "rotation-center-z-gravity" ClutterGravity        : Read / Write

### Warning

`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

The rotation center on the Z axis expressed as a ClutterGravity.

Default value: CLUTTER_GRAVITY_NONE

Since 1.0

### The `"scale-center-x"` property

      "scale-center-x"           gfloat                : Read / Write

### Warning

`ClutterActor:scale-center-x` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The horizontal center point for scaling

Default value: 0

Since 1.0

### The `"scale-center-y"` property

      "scale-center-y"           gfloat                : Read / Write

### Warning

`ClutterActor:scale-center-y` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The vertical center point for scaling

Default value: 0

Since 1.0

### The `"scale-gravity"` property

      "scale-gravity"            ClutterGravity        : Read / Write

### Warning

`ClutterActor:scale-gravity` has been deprecated since version 1.12 and should not be used in newly-written code. Use "pivot-point" instead

The center point for scaling expressed as a ClutterGravity

Default value: CLUTTER_GRAVITY_NONE

Since 1.0

### The `"scale-x"` property

      "scale-x"                  gdouble               : Read / Write

The horizontal scale of the actor.

The "scale-x" property is animatable.

Allowed values: >= 0

Default value: 1

Since 0.6

### The `"scale-y"` property

      "scale-y"                  gdouble               : Read / Write

The vertical scale of the actor.

The "scale-y" property is animatable.

Allowed values: >= 0

Default value: 1

Since 0.6

### The `"scale-z"` property

      "scale-z"                  gdouble               : Read / Write

The scale factor of the actor along the Z axis.

The "scale-y" property is animatable.

Allowed values: >= 0

Default value: 1

Since 1.12

### The `"show-on-set-parent"` property

      "show-on-set-parent"       gboolean              : Read / Write

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.

Default value: TRUE

Since 0.8

### The `"size"` property

      "size"                     ClutterSize*          : Read / Write

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.

Since 1.12

### The `"text-direction"` property

      "text-direction"           ClutterTextDirection  : Read / Write

The direction of the text inside a ClutterActor.

Default value: CLUTTER_TEXT_DIRECTION_LTR

Since 1.0

### The `"transform"` property

      "transform"                ClutterMatrix*        : Read / Write

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.

Since 1.12

### The `"transform-set"` property

      "transform-set"            gboolean              : Read

Whether the "transform" property is set.

Default value: FALSE

Since 1.12

### The `"translation-x"` property

      "translation-x"            gfloat                : Read / Write

An additional translation applied along the X axis, relative to the actor's "pivot-point".

The "translation-x" property is animatable.

Default value: 0

Since 1.12

### The `"translation-y"` property

      "translation-y"            gfloat                : Read / Write

An additional translation applied along the Y axis, relative to the actor's "pivot-point".

The "translation-y" property is animatable.

Default value: 0

Since 1.12

### The `"translation-z"` property

      "translation-z"            gfloat                : Read / Write

An additional translation applied along the Z axis, relative to the actor's "pivot-point".

The "translation-z" property is animatable.

Default value: 0

Since 1.12

### The `"visible"` property

      "visible"                  gboolean              : Read / Write

Whether the actor is set to be visible or not

See also "mapped"

Default value: FALSE

### The `"width"` property

      "width"                    gfloat                : Read / Write

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.

Allowed values: >= 0

Default value: 0

### The `"x"` property

      "x"                        gfloat                : Read / Write

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.

Default value: 0

### The `"x-align"` property

      "x-align"                  ClutterActorAlign     : Read / Write

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.

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since 1.10

### The `"x-expand"` property

      "x-expand"                 gboolean              : Read / Write

Whether a layout manager should assign more space to the actor on the X axis.

Default value: FALSE

Since 1.12

### The `"y"` property

      "y"                        gfloat                : Read / Write

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.

Default value: 0

### The `"y-align"` property

      "y-align"                  ClutterActorAlign     : Read / Write

The alignment of an actor on the Y axis, if the actor has been given extra space for its allocation.

Default value: CLUTTER_ACTOR_ALIGN_FILL

Since 1.10

### The `"y-expand"` property

      "y-expand"                 gboolean              : Read / Write

Whether a layout manager should assign more space to the actor on the Y axis.

Default value: FALSE

Since 1.12

### The `"z-position"` property

      "z-position"               gfloat                : Read / Write

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.

Default value: 0

Since 1.12

## Signal Details

### The `"allocation-changed"` signal

    void                user_function                      (ClutterActor          *actor,
                                                            ClutterActorBox       *box,
                                                            ClutterAllocationFlags flags,
                                                            gpointer               user_data)      : Run Last

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.

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

Since 1.0

### The `"button-press-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"button-release-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"captured-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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.

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

Since 0.6

### The `"destroy"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : No Hooks

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.

`actor` : | the ClutterActor which emitted the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.2

### The `"enter-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"hide"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run First

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

`actor` : | the object which received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.2

### The `"key-focus-in"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run Last

The ::key-focus-in signal is emitted when `actor` receives key focus.

`actor` : | the actor which now has key focus
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"key-focus-out"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run Last

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

`actor` : | the actor which now has key focus
`user_data` : | user data set when the signal handler was connected.

Since 0.6

### The `"key-press-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"key-release-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"leave-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"motion-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"paint"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : No Hooks

### Warning

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

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.

### Warning

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.

`actor` : | the ClutterActor that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"parent-set"` signal

    void                user_function                      (ClutterActor *actor,
                                                            ClutterActor *old_parent,
                                                            gpointer      user_data)       : Run Last

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

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

Since 0.2

### The `"pick"` signal

    void                user_function                      (ClutterActor *actor,
                                                            ClutterColor *color,
                                                            gpointer      user_data)      : Run Last

### Warning

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

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.

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

Since 1.0

### The `"queue-redraw"` signal

    void                user_function                      (ClutterActor *actor,
                                                            ClutterActor *origin,
                                                            gpointer      user_data)      : No Hooks

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
    20
    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 connect to the ::paint signal on the Stage with `g_signal_connect_after()`.

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

Since 1.0

### The `"queue-relayout"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : No Hooks

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 procense of ClutterClone actors. Applications will not normally need to connect to this signal.

`actor` : | the actor being queued for relayout
`user_data` : | user data set when the signal handler was connected.

Since 1.2

### The `"realize"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run Last

### Warning

`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

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

`actor` : | the ClutterActor that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.8

### The `"scroll-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

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

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

Since 0.6

### The `"show"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run First

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

`actor` : | the object which received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.2

### The `"touch-event"` signal

    gboolean            user_function                      (ClutterActor *actor,
                                                            ClutterEvent *event,
                                                            gpointer      user_data)      : Run Last

The ::touch-event signal is emitted each time a touch begin/end/update/cancel event.

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

Since 1.12

### The `"transition-stopped"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gchar        *name,
                                                            gboolean      is_finished,
                                                            gpointer      user_data)        : No Hooks

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

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

Since 1.12

### The `"transitions-completed"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run Last

The ::transitions-completed signal is emitted once all transitions involving `actor` are complete.

`actor` : | a ClutterActor
`user_data` : | user data set when the signal handler was connected.

Since 1.10

### The `"unrealize"` signal

    void                user_function                      (ClutterActor *actor,
                                                            gpointer      user_data)      : Run Last

### Warning

`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

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

`actor` : | the ClutterActor that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 0.8