From 348f5bfec8b8c0c682384001ac39b4e656b9c526 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 1 Dec 2009 10:11:33 +0000 Subject: [PATCH] cookbook: Clean up the text MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit • Remove the empty sections. • Add the description for the "overriding the paint sequence" recipe. --- doc/cookbook/clutter-cookbook.xml.in | 124 ++++++++++++++++++++++++----------- 1 file changed, 86 insertions(+), 38 deletions(-) diff --git a/doc/cookbook/clutter-cookbook.xml.in b/doc/cookbook/clutter-cookbook.xml.in index 36b2b28..868b813 100644 --- a/doc/cookbook/clutter-cookbook.xml.in +++ b/doc/cookbook/clutter-cookbook.xml.in @@ -121,12 +121,6 @@ Binaries for Microsoft Windows are also available. -
- License - - FIXME -
- @@ -148,8 +142,11 @@ 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. + 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 @@ -194,14 +191,13 @@ g_signal_connect (actor, "notify::depth", - 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: + 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, "notify::allocation", +g_signal_connect (actor, "allocation-changed", G_CALLBACK (on_allocation_changed), NULL); @@ -217,6 +213,20 @@ on_notify (GObject *gobject, 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); + + +
@@ -239,7 +249,8 @@ on_x_changed (GObject *gobject, { gint x_value = 0; - g_object_get (gobject, pspec->name, &x_value, NULL); + /* 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); } @@ -253,17 +264,18 @@ on_x_changed (GObject *gobject, void -on_allocation_changed (GObject *gobject, - GParamSpec *pspec, - gpointer user_data) +on_allocation_changed (ClutterActor *actor, + const ClutterActorBox *allocation, + ClutterAllocationFlags flags, + 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)); + 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)); } @@ -271,13 +283,13 @@ on_allocation_changed (GObject *gobject, 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. + 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.
@@ -335,14 +347,47 @@ on_paint (ClutterActor *actor,
Discussion - ... + 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.
- + +
Maintaining the aspect ratio when loading a texture
@@ -377,11 +422,13 @@ on_paint (ClutterActor *actor,
-
+ - + +--> - + +
Inverting Animations
@@ -417,9 +464,10 @@ on_paint (ClutterActor *actor, ...
-
+ - + +--> Contributing to this document -- 2.7.4