ClutterActor

ClutterActor — Base abstract class for all visual stage actors.

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;
                    ClutterGeometry;
#define             CLUTTER_CALLBACK                    (f)
void                (*ClutterCallback)                  (ClutterActor *actor,
                                                         gpointer data);
                    ClutterActor;
                    ClutterActorClass;
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_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_queue_redraw          (ClutterActor *self);
void                clutter_actor_queue_relayout        (ClutterActor *self);
void                clutter_actor_destroy               (ClutterActor *self);
gboolean            clutter_actor_event                 (ClutterActor *actor,
                                                         ClutterEvent *event,
                                                         gboolean capture);
gboolean            clutter_actor_should_pick_paint     (ClutterActor *self);
void                clutter_actor_map                   (ClutterActor *self);
void                clutter_actor_unmap                 (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_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_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_rotation          (ClutterActor *self,
                                                         ClutterRotateAxis axis,
                                                         gdouble angle,
                                                         gfloat x,
                                                         gfloat y,
                                                         gfloat z);
void                clutter_actor_set_z_rotation_from_gravity
                                                        (ClutterActor *self,
                                                         gdouble angle,
                                                         ClutterGravity gravity);
gdouble             clutter_actor_get_rotation          (ClutterActor *self,
                                                         ClutterRotateAxis axis,
                                                         gfloat *x,
                                                         gfloat *y,
                                                         gfloat *z);
ClutterGravity      clutter_actor_get_z_rotation_gravity
                                                        (ClutterActor *self);
gboolean            clutter_actor_is_rotated            (ClutterActor *self);
void                clutter_actor_set_opacity           (ClutterActor *self,
                                                         guint8 opacity);
guint8              clutter_actor_get_opacity           (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_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_parent            (ClutterActor *self,
                                                         ClutterActor *parent);
ClutterActor *      clutter_actor_get_parent            (ClutterActor *self);
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);
ClutterActor*       clutter_actor_get_stage             (ClutterActor *actor);

void                clutter_actor_set_depth             (ClutterActor *self,
                                                         gfloat depth);
gfloat              clutter_actor_get_depth             (ClutterActor *self);
void                clutter_actor_set_scale             (ClutterActor *self,
                                                         gdouble scale_x,
                                                         gdouble scale_y);
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             (ClutterActor *self,
                                                         gdouble *scale_x,
                                                         gdouble *scale_y);
void                clutter_actor_get_scale_center      (ClutterActor *self,
                                                         gfloat *center_x,
                                                         gfloat *center_y);
ClutterGravity      clutter_actor_get_scale_gravity     (ClutterActor *self);
gboolean            clutter_actor_is_scaled             (ClutterActor *self);
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[]);
void                clutter_actor_get_transformation_matrix
                                                        (ClutterActor *self,
                                                         CoglMatrix *matrix);

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_reactive          (ClutterActor *actor,
                                                         gboolean reactive);
gboolean            clutter_actor_get_reactive          (ClutterActor *actor);
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_grab_key_focus        (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);
gboolean            clutter_actor_is_in_clone_paint     (ClutterActor *self);

                    ClutterActorBox;
ClutterActorBox *   clutter_actor_box_new               (gfloat x_1,
                                                         gfloat y_1,
                                                         gfloat x_2,
                                                         gfloat y_2);
ClutterActorBox *   clutter_actor_box_copy              (const ClutterActorBox *box);
void                clutter_actor_box_free              (ClutterActorBox *box);
gboolean            clutter_actor_box_equal             (const ClutterActorBox *box_a,
                                                         const ClutterActorBox *box_b);
gfloat              clutter_actor_box_get_x             (const ClutterActorBox *box);
gfloat              clutter_actor_box_get_y             (const ClutterActorBox *box);
gfloat              clutter_actor_box_get_width         (const ClutterActorBox *box);
gfloat              clutter_actor_box_get_height        (const ClutterActorBox *box);
void                clutter_actor_box_get_origin        (const ClutterActorBox *box,
                                                         gfloat *x,
                                                         gfloat *y);
void                clutter_actor_box_get_size          (const ClutterActorBox *box,
                                                         gfloat *width,
                                                         gfloat *height);
gfloat              clutter_actor_box_get_area          (const ClutterActorBox *box);
gboolean            clutter_actor_box_contains          (const ClutterActorBox *box,
                                                         gfloat x,
                                                         gfloat y);
void                clutter_actor_box_from_vertices     (ClutterActorBox *box,
                                                         const ClutterVertex verts[]);

                    ClutterVertex;
ClutterVertex *     clutter_vertex_new                  (gfloat x,
                                                         gfloat y,
                                                         gfloat z);
ClutterVertex *     clutter_vertex_copy                 (const ClutterVertex *vertex);
void                clutter_vertex_free                 (ClutterVertex *vertex);
gboolean            clutter_vertex_equal                (const ClutterVertex *vertex_a,
                                                         const ClutterVertex *vertex_b);

Object Hierarchy

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

Implemented Interfaces

ClutterActor implements ClutterScriptable.

Properties

  "allocation"               ClutterActorBox*      : Read
  "anchor-gravity"           ClutterGravity        : Read / Write
  "anchor-x"                 gfloat                : Read / Write
  "anchor-y"                 gfloat                : Read / Write
  "clip"                     ClutterGeometry*      : Read / Write
  "clip-to-allocation"       gboolean              : Read / Write
  "depth"                    gfloat                : Read / Write
  "fixed-position-set"       gboolean              : Read / Write
  "fixed-x"                  gfloat                : Read / Write
  "fixed-y"                  gfloat                : Read / Write
  "has-clip"                 gboolean              : Read
  "height"                   gfloat                : Read / Write
  "mapped"                   gboolean              : Read
  "min-height"               gfloat                : Read / Write
  "min-height-set"           gboolean              : Read / Write
  "min-width"                gfloat                : Read / Write
  "min-width-set"            gboolean              : 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
  "opacity"                  guchar                : 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
  "show-on-set-parent"       gboolean              : Read / Write
  "visible"                  gboolean              : Read / Write
  "width"                    gfloat                : Read / Write
  "x"                        gfloat                : Read / Write
  "y"                        gfloat                : Read / Write

Signals

  "allocation-changed"                             : Run Last
  "button-press-event"                             : Run Last
  "button-release-event"                           : Run Last
  "captured-event"                                 : Run Last
  "destroy"                                        : Cleanup / No Recursion / 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"                                          : Run Last
  "parent-set"                                     : Run Last
  "pick"                                           : Run Last
  "queue-redraw"                                   : Run Last
  "realize"                                        : Run Last
  "scroll-event"                                   : Run Last
  "show"                                           : Run First
  "unrealize"                                      : Run Last

Description

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

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

The actors 2D surface is contained inside its bounding box, described by the ClutterActorBox structure:

Figure 1. Bounding box of an Actor

Bounding box of an Actor


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

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

  1. Translation by actor x, y coords,

  2. Translation by actor depth (z),

  3. Scaling by scale_x, scale_y,

  4. Rotation around z axis,

  5. Rotation around y axis,

  6. Rotation around x axis,

  7. Negative translation by anchor point x, y,

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

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

When accessing the position and size of an actor, the simple accessors like clutter_actor_get_width() and clutter_actor_get_x() will return a value depending on whether the actor has been explicitly sized and positioned by the developer or implicitly by the layout manager.

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

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

  1. Actors emit pointer events if set reactive, see clutter_actor_set_reactive()

  2. The stage is always reactive

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

  4. Event handlers must return TRUE if they handled the event and wish to block the event emission chain, or FALSE if the emission chain must continue

  5. Keyboard events are emitted if actor has focus, see clutter_stage_set_key_focus()

  6. Motion events (motion, enter, leave) are not emitted if clutter_set_motion_events_enabled() is called with FALSE. See clutter_set_motion_events_enabled() documentation for more information.

  7. Once emitted, an event emission chain has two phases: capture and bubble. An emitted event starts in the capture phase (see ClutterActor::captured-event) beginning at the stage and traversing every child actor until the event source actor is reached. The emission then enters the bubble phase, traversing back up the chain via parents until it reaches the stage. Any event handler can abort this chain by returning TRUE (meaning "event handled").

  8. Pointer events will 'pass through' non reactive overlapping actors.

Figure 2. Event flow in Clutter

Event flow in Clutter


Every '?' box in the diagram above is an entry point for application code.

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

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.

Means "the actor will be painted if the stage is mapped."

TRUE if the actor is visible; and all parents with possible exception of the stage are visible; and an ancestor of the actor is a toplevel.

Clutter auto-maintains the mapped flag whenever actors are reparented or shown/hidden.

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.

Whether GL resources such as textures are allocated; 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. The stage is required so the actor knows the correct GL context and window system resources to use.

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.

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
{
  CLUTTER_ACTOR_MAPPED   = 1 << 1,
  CLUTTER_ACTOR_REALIZED = 1 << 2,
  CLUTTER_ACTOR_REACTIVE = 1 << 3,
  CLUTTER_ACTOR_VISIBLE  = 1 << 4
} 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

enum ClutterRequestMode

typedef enum {
  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


ClutterGeometry

typedef struct {
  gint   x;
  gint   y;
  guint  width;
  guint  height;
} ClutterGeometry;

The rectangle containing an actor's bounding box, measured in pixels.

gint x;

X coordinate of the top left corner of an actor

gint y;

Y coordinate of the top left corner of an actor

guint width;

width of an actor

guint height;

height of an actor

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

ClutterActor

typedef struct {
  guint32 flags;
} ClutterActor;

Base class for actors.

guint32 flags;

ClutterActorFlags

ClutterActorClass

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

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

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

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

  /* transformations */
  void (* apply_transform)      (ClutterActor           *actor,
                                 CoglMatrix             *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);
} ClutterActorClass;

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

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

realize ()

virtual function, used to allocate resources for the actor; it should chain up to the parent's implementation

unrealize ()

virtual function, used to deallocate resources allocated in ::realize; it should chain up to the parent's implementation

map ()

virtual function for containers and composite actors, to map their children; it must chain up to the parent's implementation

unmap ()

virtual function for containers and composite actors, to unmap their children; it must chain up to the parent's implementation

paint ()

virtual function, used to paint the actor

parent_set ()

signal class handler for the "parent-set"

destroy ()

signal class handler for "destroy"

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

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 "focus-in"

key_focus_out ()

signal class closure for "focus-out"

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

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

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

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

Realization means the actor is now tied to a specific rendering context (that is, a specific toplevel stage).

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

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

Unrealization means the actor is now independent of any specific rendering context (is not attached to a specific toplevel 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 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.

If you were using clutter_actor_unrealize() to re-realize to create your resources in a different way, then use _clutter_actor_rerealize() (inside Clutter) or just call your code that recreates your resources directly (outside Clutter).

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 will emit the "paint" signal.

self :

A ClutterActor

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

self :

A ClutterActor

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,
                                                         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 is allowed in only one case: you are implementing the "map" virtual function in an actor and you need to map the children of that actor. It is not necessary to call this if you implement ClutterContainer because the default implementation will automatically map children of containers.

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 is allowed in only one case: you are implementing the "unmap" virtual function in an actor and you need to unmap the children of that actor. It is not necessary to call this if you implement ClutterContainer because the default implementation will automatically unmap children of containers.

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

self :

A ClutterActor

Since 1.0


enum ClutterAllocationFlags

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

Flags passed to the ""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

Since 1.0


clutter_actor_allocate ()

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

Called by the parent of an actor to assign the actor its size. Should never be called by applications (except when implementing a container or layout manager).

Actors can know from their allocation box whether they have moved with respect to their parent actor. The flags parameter describes additional information about the allocation, for instance whether the parent has moved with respect to the stage, for example because a grandparent's origin has moved.

self :

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

This function is not meant to be used by applications. It is also not meant to be used outside the implementation of the ClutterActor::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:

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

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 :

allow-none. allow-none.

verts :

out) (array fixed-size=4. out. array fixed-size=4.

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 :

out) (allow-none. out. allow-none.

min_height_p :

out) (allow-none. out. allow-none.

natural_width_p :

out) (allow-none. out. allow-none.

natural_height_p :

out) (allow-none. 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 :

out) (allow-none. out. allow-none.

natural_width_p :

out) (allow-none. 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 :

out) (allow-none. out. allow-none.

natural_height_p :

out) (allow-none. 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_geometry ()

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

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

self :

A ClutterActor

geometry :

A ClutterGeometry

clutter_actor_get_geometry ()

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

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

self :

A ClutterActor

geometry :

A location to store actors ClutterGeometry. out.

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.

This function sets both the minimum and natural size of the actor.

self :

A ClutterActor

width :

Requested new width for the actor, in pixels

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.

This function sets both the minimum and natural size of the actor.

self :

A ClutterActor

height :

Requested new height for the actor, in pixels

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.

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.

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

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

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

Sets the rotation angle of self around the given axis.

The rotation center coordinates used depend on the value of axis:

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

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

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

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

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

ClutterGravity      clutter_actor_get_z_rotation_gravity
                                                        (ClutterActor *self);

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

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

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

Retrieves the unique id for self.

self :

A ClutterActor

Returns :

Globally unique value for this object instance.

Since 0.6


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 :

out) (allow-none. out. allow-none.

yoff :

out) (allow-none. out. allow-none.

width :

out) (allow-none. out. allow-none.

height :

out) (allow-none. out. allow-none.

Since 0.6


clutter_actor_set_parent ()

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

Sets the parent of self to parent. The opposite function is clutter_actor_unparent().

This function should not be used by applications, but by custom container actor subclasses.

self :

A ClutterActor

parent :

A new ClutterActor parent

clutter_actor_get_parent ()

ClutterActor *      clutter_actor_get_parent            (ClutterActor *self);

Retrieves the parent of self.

self :

A ClutterActor

Returns :

transfer none. transfer none.

clutter_actor_reparent ()

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

This function resets the parent actor of self. It is logically equivalent to calling clutter_actor_unparent() and clutter_actor_set_parent(), but more efficiently implemented, ensures the child is not finalized when unparented, and emits the parent-set signal only one time.

self :

a ClutterActor

new_parent :

the new ClutterActor parent

Since 0.2


clutter_actor_unparent ()

void                clutter_actor_unparent              (ClutterActor *self);

Removes the parent of self.

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

self :

a ClutterActor

Since 0.1.1


clutter_actor_raise ()

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

Puts self above below.

Both actors must have the same parent.

This function is the equivalent of clutter_container_raise_child().

self :

A ClutterActor

below :

A ClutterActor to raise above.. allow-none.

clutter_actor_lower ()

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

Puts self below above.

Both actors must have the same parent.

This function is the equivalent of clutter_container_lower_child().

self :

A ClutterActor

above :

A ClutterActor to lower below. allow-none.

clutter_actor_raise_top ()

void                clutter_actor_raise_top             (ClutterActor *self);

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

Lowers self to the bottom.

This function calls clutter_actor_lower() internally.

self :

A ClutterActor

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.

Since 0.8


clutter_actor_set_depth ()

void                clutter_actor_set_depth             (ClutterActor *self,
                                                         gfloat depth);

Sets the Z coordinate of self to depth.

The unit used by depth is dependant on the perspective setup. See also clutter_stage_set_perspective().

self :

a ClutterActor

depth :

Z co-ord

clutter_actor_get_depth ()

gfloat              clutter_actor_get_depth             (ClutterActor *self);

Retrieves the depth of self.

self :

a ClutterActor

Returns :

the depth of the actor

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 scaling is relative to the scale center and the anchor point. The scale center is unchanged by this function and defaults to 0,0.

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

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

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

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

center_y :

Y coordinate of the center of the scale

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

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.

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

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

Retrieves an actors scale factors.

self :

A ClutterActor

scale_x :

out) (allow-none. out. allow-none.

scale_y :

out) (allow-none. out. allow-none.

Since 0.2


clutter_actor_get_scale_center ()

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

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 :

out) (allow-none. out. allow-none.

center_y :

out) (allow-none. out. allow-none.

Since 1.0


clutter_actor_get_scale_gravity ()

ClutterGravity      clutter_actor_get_scale_gravity     (ClutterActor *self);

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

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

allow-none. allow-none.

point :

A point as ClutterVertex

vertex :

The translated ClutterVertex

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 :

out) (array fixed-size=4. out. array fixed-size=4.

Since 0.4


clutter_actor_get_transformation_matrix ()

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

Retrieves the transformations applied to self

self :

a ClutterActor

matrix :

the return location for a CoglMatrix. out.

Since 1.0


clutter_actor_set_anchor_point ()

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

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

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

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

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

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

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_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_set_shader ()

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

Sets the ClutterShader to be used when rendering self.

If shader is NULL it will unset any currently set shader for the actor.

self :

a ClutterActor

shader :

a ClutterShader or NULL to unset the shader.. allow-none.

Returns :

TRUE if the shader was successfully applied

Since 0.6


clutter_actor_get_shader ()

ClutterShader *     clutter_actor_get_shader            (ClutterActor *self);

Queries the currently set ClutterShader on self.

self :

a ClutterActor

Returns :

transfer none. transfer none.

Since 0.6


clutter_actor_set_shader_param ()

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

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

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

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

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

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

Since 1.0


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


ClutterActorBox

typedef struct {
  gfloat x1;
  gfloat y1;

  gfloat x2;
  gfloat y2;
} ClutterActorBox;

Bounding box of an actor. The coordinates of the top left and right bottom corners of an actor. The coordinates of the two points are expressed in pixels with sub-pixel precision

gfloat x1;

X coordinate of the top left corner

gfloat y1;

Y coordinate of the top left corner

gfloat x2;

X coordinate of the bottom right corner

gfloat y2;

Y coordinate of the bottom right corner

clutter_actor_box_new ()

ClutterActorBox *   clutter_actor_box_new               (gfloat x_1,
                                                         gfloat y_1,
                                                         gfloat x_2,
                                                         gfloat y_2);

Allocates a new ClutterActorBox using the passed coordinates for the top left and bottom right points

x_1 :

X coordinate of the top left point

y_1 :

Y coordinate of the top left point

x_2 :

X coordinate of the bottom right point

y_2 :

Y coordinate of the bottom right point

Returns :

the newly allocated ClutterActorBox. Use clutter_actor_box_free() to free the resources

Since 1.0


clutter_actor_box_copy ()

ClutterActorBox *   clutter_actor_box_copy              (const ClutterActorBox *box);

Copies box

box :

a ClutterActorBox

Returns :

a newly allocated copy of ClutterActorBox. Use clutter_actor_box_free() to free the allocated resources

Since 1.0


clutter_actor_box_free ()

void                clutter_actor_box_free              (ClutterActorBox *box);

Frees a ClutterActorBox allocated using clutter_actor_box_new() or clutter_actor_box_copy()

box :

a ClutterActorBox

Since 1.0


clutter_actor_box_equal ()

gboolean            clutter_actor_box_equal             (const ClutterActorBox *box_a,
                                                         const ClutterActorBox *box_b);

Checks box_a and box_b for equality

box_a :

a ClutterActorBox

box_b :

a ClutterActorBox

Returns :

TRUE if the passed ClutterActorBox are equal

Since 1.0


clutter_actor_box_get_x ()

gfloat              clutter_actor_box_get_x             (const ClutterActorBox *box);

Retrieves the X coordinate of the origin of box

box :

a ClutterActorBox

Returns :

the X coordinate of the origin

Since 1.0


clutter_actor_box_get_y ()

gfloat              clutter_actor_box_get_y             (const ClutterActorBox *box);

Retrieves the Y coordinate of the origin of box

box :

a ClutterActorBox

Returns :

the Y coordinate of the origin

Since 1.0


clutter_actor_box_get_width ()

gfloat              clutter_actor_box_get_width         (const ClutterActorBox *box);

Retrieves the width of the box

box :

a ClutterActorBox

Returns :

the width of the box

Since 1.0


clutter_actor_box_get_height ()

gfloat              clutter_actor_box_get_height        (const ClutterActorBox *box);

Retrieves the height of the box

box :

a ClutterActorBox

Returns :

the height of the box

Since 1.0


clutter_actor_box_get_origin ()

void                clutter_actor_box_get_origin        (const ClutterActorBox *box,
                                                         gfloat *x,
                                                         gfloat *y);

Retrieves the origin of box

box :

a ClutterActorBox

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 1.0


clutter_actor_box_get_size ()

void                clutter_actor_box_get_size          (const ClutterActorBox *box,
                                                         gfloat *width,
                                                         gfloat *height);

Retrieves the size of box

box :

a ClutterActorBox

width :

return location for the width, or NULL. out. allow-none.

height :

return location for the height, or NULL. out. allow-none.

Since 1.0


clutter_actor_box_get_area ()

gfloat              clutter_actor_box_get_area          (const ClutterActorBox *box);

Retrieves the area of box

box :

a ClutterActorBox

Returns :

the area of a ClutterActorBox, in pixels

Since 1.0


clutter_actor_box_contains ()

gboolean            clutter_actor_box_contains          (const ClutterActorBox *box,
                                                         gfloat x,
                                                         gfloat y);

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

box :

a ClutterActorBox

x :

X coordinate of the point

y :

Y coordinate of the point

Returns :

TRUE if the point is contained by the ClutterActorBox

Since 1.0


clutter_actor_box_from_vertices ()

void                clutter_actor_box_from_vertices     (ClutterActorBox *box,
                                                         const ClutterVertex verts[]);

Calculates the bounding box represented by the four vertices; for details of the vertex array see clutter_actor_get_abs_allocation_vertices().

box :

a ClutterActorBox

verts :

array of four ClutterVertex. array fixed-size=4.

Since 1.0


ClutterVertex

typedef struct {
  gfloat x;
  gfloat y;
  gfloat z;
} ClutterVertex;

Vertex of an actor in 3D space, expressed in pixels

gfloat x;

X coordinate of the vertex

gfloat y;

Y coordinate of the vertex

gfloat z;

Z coordinate of the vertex

Since 0.4


clutter_vertex_new ()

ClutterVertex *     clutter_vertex_new                  (gfloat x,
                                                         gfloat y,
                                                         gfloat z);

Creates a new ClutterVertex for the point in 3D space identified by the 3 coordinates x, y, z

x :

X coordinate

y :

Y coordinate

z :

Z coordinate

Returns :

the newly allocate ClutterVertex. Use clutter_vertex_free() to free the resources

Since 1.0


clutter_vertex_copy ()

ClutterVertex *     clutter_vertex_copy                 (const ClutterVertex *vertex);

Copies vertex

vertex :

a ClutterVertex

Returns :

a newly allocated copy of ClutterVertex. Use clutter_vertex_free() to free the allocated resources

Since 1.0


clutter_vertex_free ()

void                clutter_vertex_free                 (ClutterVertex *vertex);

Frees a ClutterVertex allocated using clutter_vertex_copy()

vertex :

a ClutterVertex

Since 1.0


clutter_vertex_equal ()

gboolean            clutter_vertex_equal                (const ClutterVertex *vertex_a,
                                                         const ClutterVertex *vertex_b);

Compares vertex_a and vertex_b for equality

vertex_a :

a ClutterVertex

vertex_b :

a ClutterVertex

Returns :

TRUE if the passed ClutterVertex are equal

Since 1.0

Property Details

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

The anchor point expressed as a ClutterGravity

Default value: CLUTTER_GRAVITY_NONE

Since 1.0


The "anchor-x" property

  "anchor-x"                 gfloat                : Read / Write

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

Default value: 0

Since 0.8


The "anchor-y" property

  "anchor-y"                 gfloat                : Read / Write

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

Default value: 0

Since 0.8


The "clip" property

  "clip"                     ClutterGeometry*      : Read / Write

The clip region for the actor, in actor-relative coordinates

Every part of the actor outside the clip region will not be painted


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 "depth" property

  "depth"                    gfloat                : Read / Write

The position of the actor on the Z axis

Default value: 0

Since 0.6


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

Allowed values: >= 0

Default value: 0


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 "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 "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 "opacity" property

  "opacity"                  guchar                : Read / Write

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

Default value: 255


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:

  ClutterRequestMode mode;
  gfloat natural_width, min_width;
  gfloat natural_height, min_height;
  g_object_get (G_OBJECT (child), "request-mode", &mode, NULL);
  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

Default value: 0

Since 0.6


The "rotation-angle-y" property

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

The rotation angle on the Y axis

Default value: 0

Since 0.6


The "rotation-angle-z" property

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

The rotation angle on the Z axis

Default value: 0

Since 0.6


The "rotation-center-x" property

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

The rotation center on the X axis.

Since 0.6


The "rotation-center-y" property

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

The rotation center on the Y axis.

Since 0.6


The "rotation-center-z" property

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

The rotation center on the Z axis.

Since 0.6


The "rotation-center-z-gravity" property

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

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

The horizontal center point for scaling

Default value: 0

Since 1.0


The "scale-center-y" property

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

The vertical center point for scaling

Default value: 0

Since 1.0


The "scale-gravity" property

  "scale-gravity"            ClutterGravity        : Read / Write

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

Allowed values: >= 0

Default value: 1

Since 0.6


The "scale-y" property

  "scale-y"                  gdouble               : Read / Write

The vertical scale of the actor

Allowed values: >= 0

Default value: 1

Since 0.6


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

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.

Default value: 0


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.

Default value: 0

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

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

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)      : Cleanup / No Recursion / No Hooks

The ::destroy signal is emitted when an actor is destroyed, either by direct invocation of clutter_actor_destroy() or when the ClutterGroup that contains the actor is destroyed.

actor :

the object which received 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

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 ::focus-in signal is emitted when actor recieves 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

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

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

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

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)      : Run Last

The ::paint signal is emitted each time an actor is being painted.

Subclasses of ClutterActor should override the class signal handler and paint themselves in that function.

It is possible to connect a handler to the ::paint signal in order to set up some custom aspect of a paint.

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

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

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)      : Run Last

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_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_redraw() themselves, like:

  static void
  on_redraw_complete (void)
  {
    /* execute the Clutter drawing pipeline */
    clutter_redraw ();
  }

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

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 "realize" signal

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

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

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 "unrealize" signal

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

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