diff --git a/doc/cookbook/clutter-cookbook.xml b/doc/cookbook/clutter-cookbook.xml
index 4bcbd18d4..bd3a0d1f7 100644
--- a/doc/cookbook/clutter-cookbook.xml
+++ b/doc/cookbook/clutter-cookbook.xml
@@ -127,36 +127,148 @@
Actors
- the author of the epigraph
- a short epigraph
+ Edmon Gween, actor, on his deathbed
+ An actor's a guy who if you ain't talkin' about him, ain't
+ listening.
Introduction
- introduction
+ 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 is either the parent of another actor or a
+ child of another actor.
+
+ 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.
+
- A problem involving actors
+ Knowing when an actor position or size change
Problem
- Description of the problem
+ 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.
Solution
- The solution of the problem, with the source code
+ 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 detailt for
+ the notify signal:
+
+
+
+g_signal_connect (actor, "notify::allocation",
+ 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);
+
+
Discussion
- Discussion of the solution, with eventual mentions of
- possible alternatives
+ 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;
+
+ g_object_get (gobject, pspec->name, &x_value, NULL);
+
+ 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 (GObject *gobject,
+ GParamSpec *pspec,
+ gpointer user_data)
+{
+ ClutterActor *actor = CLUTTER_ACTOR (gobject);
+
+ g_print ("The bounding box is now: (%d, %d) (%d x %d)\n",
+ clutter_actor_get_x (actor),
+ clutter_actor_get_y (actor),
+ clutter_actor_get_width (actor),
+ clutter_actor_get_height (actor));
+}
+
+
+
+ All actors will update these properties when their size
+ or position change.
+
+ 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.
+