From 13df7d579d1afa8a693240f5715b897dc9e4bbad Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Thu, 12 Jun 2008 16:34:50 +0000 Subject: [PATCH] 2008-06-12 Emmanuele Bassi * clutter/clutter-actor.c: Add more clarifications on the size and position accessors and the distinction between transformed and untransformed actor box inside the actor's description. --- ChangeLog | 7 +++++++ clutter/clutter-actor.c | 27 +++++++++++++++++++++++++-- 2 files changed, 32 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index 5c9c106f9..f557188e7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2008-06-12 Emmanuele Bassi + + * clutter/clutter-actor.c: Add more clarifications on the + size and position accessors and the distinction between + transformed and untransformed actor box inside the actor's + description. + 2008-06-12 Emmanuele Bassi * clutter/clutter-actor.c: Clarify the documentation of the diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 682c5da37..438a397f7 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -40,6 +40,13 @@ * * * + * 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), the transformations applied by its + * containers, the transformations applied to the containers themselves and, + * finally, the perspective transformations applied to the #ClutterStage. + * * The OpenGL modelview matrix for the actor is constructed from * the actor settings by the following order of operations: * @@ -51,13 +58,29 @@ * Rotation around y axis, * Rotation around x axis, * Translation by actor depth (z), - * Clip stencil is applied (not an operation on the matrix - * as such, but done as part of the transform set up). + * Clip stencil is applied (this is not an operation on + * the matrix as such, but it is done as part of the transform set + * up). * * * The position of any children is referenced from the top-left corner of * the parent, not the parent's anchor point. * + * 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. + * + * 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. + * * Events are handled in the following ways: * * Actors emit pointer events if set reactive, see