From 9ea6ab76fb09891dd1c1380c4e163aaf656c507c Mon Sep 17 00:00:00 2001 From: Neil Roberts Date: Fri, 23 Jan 2009 17:25:43 +0000 Subject: [PATCH] Fix gtk-doc reference since the anchor point changes The documentation has been updated to reflect the fact that the anchor point will move when the actor changes size if it was specified using a gravity value. The new functions for setting the scale center and z rotation gravity are also documented. --- clutter/clutter-actor.c | 154 +++++++++++++++++++-- doc/reference/clutter/clutter-sections.txt | 15 +- 2 files changed, 148 insertions(+), 21 deletions(-) diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c index 5a79e5791..cce705195 100644 --- a/clutter/clutter-actor.c +++ b/clutter/clutter-actor.c @@ -57,13 +57,13 @@ * 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, - * Negative translation by anchor point x, - * y, * Rotation around z axis, * Rotation around y axis, * Rotation around x axis, - * Translation by actor depth (z), + * 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). @@ -5085,8 +5085,9 @@ clutter_actor_get_yu (ClutterActor *self) * @scale_x: double factor to scale actor by horizontally. * @scale_y: double factor to scale actor by vertically. * - * Scales an actor with the given factors. The scaling is always - * relative to the anchor point. + * Scales an actor with the given factors. The scaling is relative to + * the scale center and the anchor point. The scale center is + * unchanged by this function and defaults to 0,0. * * Since: 0.2 */ @@ -5114,6 +5115,20 @@ clutter_actor_set_scale (ClutterActor *self, g_object_unref (self); } +/** + * clutter_actor_set_scale_full: + * @self: A #ClutterActor + * @scale_x: double factor to scale actor by horizontally. + * @scale_y: double factor to scale actor by vertically. + * @center_x: X coordinate of the center of the scale. + * @center_y: Y coordinate of the center of the scale + * + * Scales an actor with the given factors around the given center + * point. The center point is specified in pixels relative to the + * anchor point (usually the top left corner of the actor). + * + * Since: 1.0 + */ void clutter_actor_set_scale_full (ClutterActor *self, gdouble scale_x, @@ -5128,6 +5143,23 @@ clutter_actor_set_scale_full (ClutterActor *self, CLUTTER_UNITS_FROM_DEVICE (center_y)); } +/** + * clutter_actor_set_scale_fullu: + * @self: A #ClutterActor + * @scale_x: double factor to scale actor by horizontally. + * @scale_y: double factor to scale actor by vertically. + * @center_x: X coordinate of the center of the scale. + * @center_y: Y coordinate of the center of the scale + * + * %ClutterUnit version of clutter_actor_set_scale_full(). + * + * Scales an actor with the given factors around the given center + * point. The center point is specified in + * %ClutterUnits relative to the anchor point (usually + * the top left corner of the actor). + * + * Since: 1.0 + */ void clutter_actor_set_scale_fullu (ClutterActor *self, gdouble scale_x, @@ -5157,6 +5189,22 @@ clutter_actor_set_scale_fullu (ClutterActor *self, g_object_unref (self); } +/** + * clutter_actor_set_scale_with_gravity: + * @self: A #ClutterActor + * @scale_x: double factor to scale actor by horizontally. + * @scale_y: double factor to scale actor by vertically. + * @gravity: the location of the scale center expressed as a compass + * direction. + * + * Scales an actor with the given factors around the given + * center point. The center point is specified as one of the compass + * directions in #ClutterGravity. For example, setting it to north + * will cause the top of the actor to remain unchanged and the rest of + * the actor to expand left, right and downwards. + * + * Since: 1.0 + */ void clutter_actor_set_scale_with_gravity (ClutterActor *self, gdouble scale_x, @@ -5213,6 +5261,19 @@ clutter_actor_get_scale (ClutterActor *self, *scale_y = CLUTTER_FIXED_TO_FLOAT (self->priv->scale_y); } +/** + * clutter_actor_get_scale_center: + * @self: A #ClutterActor + * @center_x: Location to store the X position of the scale center, or %NULL. + * @center_y: Location to store the Y position of the scale center, or %NULL. + * + * Retrieves the scale center coordinate in pixels relative to the top + * left corner of the actor. If the scale center was specified using a + * #ClutterGravity this will calculate the pixel offset using the + * current size of the actor. + * + * Since: 1.0 + */ void clutter_actor_get_scale_center (ClutterActor *self, gint *center_x, @@ -5230,6 +5291,21 @@ clutter_actor_get_scale_center (ClutterActor *self, *center_y = CLUTTER_UNITS_TO_DEVICE (yu); } +/** + * clutter_actor_get_scale_centeru: + * @self: A #ClutterActor + * @center_x: Location to store the X position of the scale center, or %NULL. + * @center_y: Location to store the Y position of the scale center, or %NULL. + * + * ClutterUnits version of clutter_actor_get_scale_center(). + * + * Retrieves the scale center coordinate in units relative to the top + * left corner of the actor. If the scale center was specified using a + * #ClutterGravity this will calculate the unit offset using the + * current size of the actor. + * + * Since: 1.0 + */ void clutter_actor_get_scale_centeru (ClutterActor *self, ClutterUnit *center_x, @@ -5241,6 +5317,18 @@ clutter_actor_get_scale_centeru (ClutterActor *self, center_x, center_y, NULL); } +/** + * clutter_actor_get_scale_gravity: + * @self: A #ClutterActor + * + * Retrieves the scale center as a compass direction. If the scale + * center was specified in pixels or units this will return + * %CLUTTER_GRAVITY_NONE. + * + * Return value: the scale gravity + * + * Since: 1.0 + */ ClutterGravity clutter_actor_get_scale_gravity (ClutterActor *self) { @@ -5571,6 +5659,20 @@ clutter_actor_set_rotation (ClutterActor *self, CLUTTER_UNITS_FROM_DEVICE (z)); } +/** + * clutter_actor_set_z_rotation_from_gravity: + * @self: a #ClutterActor + * @angle: the angle of rotation + * @gravity: the center point of the rotation + * + * Sets the rotation angle of @self around the Z axis using the center + * point specified as a compass point. For example to rotate such that + * the center of the actor remains static you can use + * %CLUTTER_GRAVITY_CENTER. If the actor changes size the center point + * will move accordingly. + * + * Since: 1.0 + */ void clutter_actor_set_z_rotation_from_gravity (ClutterActor *self, gdouble angle, @@ -5695,6 +5797,18 @@ clutter_actor_get_rotation (ClutterActor *self, return angle; } +/** + * clutter_actor_get_z_rotation_gravity: + * @self: A #ClutterActor + * + * Retrieves the center for the rotation around the Z axis as a + * compass direction. If the center was specified in pixels or units + * this will return %CLUTTER_GRAVITY_NONE. + * + * Return value: the Z rotation center + * + * Since: 1.0 + */ ClutterGravity clutter_actor_get_z_rotation_gravity (ClutterActor *self) { @@ -6526,6 +6640,16 @@ clutter_actor_set_anchor_pointu (ClutterActor *self, clutter_actor_queue_redraw (self); } +/** + * clutter_actor_get_anchor_point_gravity: + * @self: a #ClutterActor + * + * Retrieves the anchor position expressed as a #ClutterGravity. If + * the anchor point was specified using pixels or units this will + * return %CLUTTER_GRAVITY_NONE. + * + * Since: 1.0 + */ ClutterGravity clutter_actor_get_anchor_point_gravity (ClutterActor *self) { @@ -6610,11 +6734,11 @@ clutter_actor_get_anchor_pointu (ClutterActor *self, * actor postion so that its relative position within its parent remains * unchanged. * - * Note that the anchor is still stored as a point and the gravity - * value is forgotten. For example, if you set the anchor point to - * %CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, - * the anchor point will not move to the bottom right and will now be - * in the center of the actor. + * Since version 1.0 the anchor point will be stored as a gravity so + * that if the actor changes size then the anchor point will move. For + * example, if you set the anchor point to %CLUTTER_GRAVITY_SOUTH_EAST + * and later double the size of the actor, the anchor point will move + * to the bottom right. * * Since: 0.6 */ @@ -6653,11 +6777,11 @@ clutter_actor_move_anchor_point_from_gravity (ClutterActor *self, * Sets an anchor point on the actor, based on the given gravity (this is a * convenience function wrapping clutter_actor_set_anchor_point()). * - * Note that the anchor is still stored as a point and the gravity - * value is forgotten. For example, if you set the anchor point to - * %CLUTTER_GRAVITY_SOUTH_EAST and later double the size of the actor, - * the anchor point will not move to the bottom right and will now be - * in the center of the actor. + * Since version 1.0 the anchor point will be stored as a gravity so + * that if the actor changes size then the anchor point will move. For + * example, if you set the anchor point to %CLUTTER_GRAVITY_SOUTH_EAST + * and later double the size of the actor, the anchor point will move + * to the bottom right. * * Since: 0.6 */ diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index 8720e2023..e753b953c 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -352,7 +352,9 @@ clutter_actor_set_y clutter_actor_get_y clutter_actor_move_by clutter_actor_set_rotation +clutter_actor_set_z_rotation_from_gravity clutter_actor_get_rotation +clutter_actor_get_z_rotation_gravity clutter_actor_is_rotated clutter_actor_set_opacity clutter_actor_get_opacity @@ -381,7 +383,11 @@ clutter_actor_get_stage clutter_actor_set_depth clutter_actor_get_depth clutter_actor_set_scale +clutter_actor_set_scale_full +clutter_actor_set_scale_with_gravity clutter_actor_get_scale +clutter_actor_get_scale_center +clutter_actor_get_scale_gravity clutter_actor_is_scaled clutter_actor_apply_transform_to_point clutter_actor_transform_stage_point @@ -400,6 +406,7 @@ clutter_actor_box_get_from_vertices clutter_actor_set_anchor_point clutter_actor_get_anchor_point clutter_actor_set_anchor_point_from_gravity +clutter_actor_get_anchor_point_gravity clutter_actor_move_anchor_point clutter_actor_move_anchor_point_from_gravity @@ -427,6 +434,8 @@ clutter_actor_set_positionu clutter_actor_get_positionu clutter_actor_set_sizeu clutter_actor_get_sizeu +clutter_actor_set_scale_fullu +clutter_actor_get_scale_centeru clutter_actor_set_anchor_pointu clutter_actor_get_anchor_pointu clutter_actor_move_anchor_pointu @@ -438,12 +447,6 @@ clutter_actor_move_byu clutter_actor_get_transformed_positionu clutter_actor_get_transformed_sizeu - -clutter_actor_set_scalex -clutter_actor_get_scalex -clutter_actor_set_rotationx -clutter_actor_get_rotationx - clutter_actor_grab_key_focus clutter_actor_get_pango_context