From 15ef549207b188e7e201a21a77386c3268a1cb53 Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Wed, 14 Apr 2010 23:34:38 +0100 Subject: [PATCH] docs: Clean up ClutterActor's long description The Actor's long description is a bit cluttered; it contains a section on the actor's box semantics, on the transformation order and on the event handling. We should use tags to divide the Actor's description into logically separated sections. We should also add a section about the custom Scriptable properties that ClutterActor defines, and the special handling of unit-based properties. --- clutter/clutter-actor.c | 204 +++++++++++++++++++++++----------------- 1 file changed, 116 insertions(+), 88 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 87b2d573e..d7d4b0bf2 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -36,97 +36,125 @@ * 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: + * + * Actor bounding box and transformations + * Any actor's 2D surface is contained inside its bounding box, + * as described by the #ClutterActorBox structure: + *
+ * 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 GL 'modelview' transform matrix for the actor is constructed + * from the actor settings by the following order of operations: + * + * Translation by actor x, y coords, + * Translation by actor depth (z), + * Scaling by scale_x, scale_y, + * Rotation around z axis, + * Rotation around y axis, + * Rotation around x axis, + * Negative translation by anchor point x, + * y, + * 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 manipulated 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. + * * - *
- * Bounding box of an Actor - * - *
+ * + * Event Handling + * Clutter actors are also able to receive input events and react to + * them. Events are handled in the following ways: + * + * Actors emit pointer events if set reactive, see + * clutter_actor_set_reactive() + * The stage is always reactive + * Events are handled by connecting signal handlers to + * the numerous event signal types. + * 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 + * Keyboard events are emitted if actor has focus, see + * clutter_stage_set_key_focus() + * 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. + * 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"). + * + * Pointer events will 'pass through' non reactive + * overlapping actors. + * + *
+ * Event flow in Clutter + * + *
+ * Every '?' box in the diagram above is an entry point for + * application code. + * * - * 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. + * + * Implementing a ClutterActor + * For implementing a new custom actor class, please read the corresponding + * section of the API reference. + * * - * The 'modelview' transform matrix for the actor is constructed from - * the actor settings by the following order of operations: - * - * Translation by actor x, y coords, - * Translation by actor depth (z), - * Scaling by scale_x, scale_y, - * Rotation around z axis, - * Rotation around y axis, - * Rotation around x axis, - * Negative translation by anchor point x, - * y, - * 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 manipulated 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: - * - * - * Actors emit pointer events if set reactive, see - * clutter_actor_set_reactive() - * The stage is always reactive - * Events are handled by connecting signal handlers to - * the numerous event signal types. - * 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 - * Keyboard events are emitted if actor has focus, see - * clutter_stage_set_key_focus() - * 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. - * 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"). - * - * Pointer events will 'pass through' non reactive - * overlapping actors. - * - * - *
- * 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. + * + * ClutterActor custom properties for #ClutterScript + * #ClutterActor defines a custom "rotation" property which + * allows a short-hand description of the rotations to be applied + * to an actor. + * The syntax of the "rotation" property is the following: + * + * + * "rotation" : [ + * { "<axis>" : [ <angle>, [ <center> ] ] } + * ] + * + * + * where the axis is the name of an enumeration + * value of type #ClutterRotateAxis and angle is a + * floating point value representing the rotation angle on the given axis, + * in degrees. + * The center array is optional, and if present + * it must contain the center of rotation as described by two coordinates: + * Y and Z for "x-axis"; X and Z for "y-axis"; and X and Y for + * "z-axis". + * #ClutterActor will also parse every positional and dimensional + * property defined as a string through clutter_units_from_string(); you + * should read the documentation for the #ClutterUnits parser format for + * the valid units and syntax. + * */ /**