Edmon Gween, actor, on his deathbed An actor's a guy who if you ain't talkin' about him, ain't listening.

When building a User Interface with Clutter, the visible part of the UI — that is, what is displayed on the screen — is commonly referred to as "the scene graph". Like every graph, a scene graph is composed by nodes. Every node on the Clutter scene graph is an actor. Every actor has a single relationship with the others: it can be the parent of another actor, or a child of another actor. The Stage is an actor that can have children but cannot have any parent. Actors have different attributes: a position, a size, a scale factor, a rotation angle on each axis (relative to a specific center on the normal plane for that axis), an opacity factor. The scene graph is not fixed: it can be changed, not only by adding or removing actors, but also by changing the parent-child relationship: it is possible, for instance, to move an entire section of the scene graph from one parent actor to another.

You want to know when the position or the size, or both, of an actor change, for instance to update an unrelated actor or some internal state.

You can use the notify signal, detailed with the coordinate or the dimension you want to know has changed: g_signal_connect (actor, "notify::x", G_CALLBACK (on_x_changed), NULL); g_signal_connect (actor, "notify::height", G_CALLBACK (on_height_changed), NULL); g_signal_connect (actor, "notify::depth", G_CALLBACK (on_depth_changed), NULL); If you want to know if any of the coordinates or dimensions of an actor have been changed, except for depth, you can use the allocation-changed signal: g_signal_connect (actor, "allocation-changed", G_CALLBACK (on_allocation_changed), NULL); The signature for the handler of the "notify" signal is: void on_notify (GObject *gobject, GParamSpec *pspec, gpointer user_data); While the signature for the handler of the "allocation-changed" signal is: void on_allocation_changed (ClutterActor *actor, const ClutterActorBox *allocation, ClutterAllocationFlags flags, gpointer user_data);

Any change the position and size of an actor will cause a change in the allocation of the actor itself. This will update the values of the :x, :y, :width and :height properties as well. The first technique allows a greater deal of granularity, allowing you to know what exactly changed. Inside the callback for the signal you can query the value of the property: void on_x_changed (GObject *gobject, GParamSpec *pspec, gpointer user_data) { gint x_value = 0; /* Round the X coordinate to the nearest pixel */ x_value = floorf (clutter_actor_get_x (CLUTTER_ACTOR (gobject))) + 0.5; g_print ("The new X coordinate is '%d' pixels\n", x_value); } The second technique is more indicated if you want to get notification that any of the positional or dimensional attributes changed, except for the depth: void on_allocation_changed (ClutterActor *actor, const ClutterActorBox *allocation, ClutterAllocationFlags flags, gpointer user_data) { g_print ("The bounding box is now: (%.2f, %.2f) (%.2f x %.2f)\n", clutter_actor_box_get_x (allocation), clutter_actor_box_get_y (allocation), clutter_actor_box_get_width (allocation), clutter_actor_box_get_height (allocation)); } All actors will update these properties when their size or position change. Note that the Stage, on the other hand, will not notify on position changes, so it is not possible to use the :x and :y properties to know that the platform-specific window embedding the stage has been moved — if the platform supports a windowing system. In order to achieve that you will have to use backend-specific API to extract the surface used by the Stage and then platform-specific API to retrieve its coordinates.

You want to override the way an actor paints itself without creating a subclass.

You can use the paint signal to invoke a callback that will be executed before the actor's paint implementation: g_signal_connect (actor, "paint", G_CALLBACK (on_paint), NULL); You can paint something after the actor's paint implementation by using the g_signal_connect_after() function instead of g_signal_connect(): g_signal_connect_after (actor, "paint", G_CALLBACK (on_paint_after), NULL); The signature for the handler of the "paint" signal is: void on_paint (ClutterActor *actor, gpointer user_data);

The paint cycle in Clutter works its way recursively from the Stage through every child. Whenever an Actor is going to be painted it will be positioned in a new frame of reference according to the list of transformations (scaling, rotation and additional traslations). After that, the "paint" signal will be emitted. The "paint" signal is defined as run-last, that is the signal handlers connected to it using g_signal_connetc() will be called first; then the default handler defined by the Actor's sub-class will be called; finally, all the signal handlers connected to the signal using g_signal_connect_after() will be called. This allows pre- and post-default paint handlers, and it also allows completely overriding the way an Actor draws itself by default; for instance: void on_paint (ClutterActor *actor) { do_my_paint (actor); g_signal_stop_emission_by_name (actor, "paint"); } The code above will prevent the default paint implementation of the actor from running.