constraint: Rename BindConstraint:bind-axis

We're not binding an axis: we're really binding a coordinate of an actor
to the coordinate of another one.

clutter/clutter-bind-constraint.c

@@ -1,3 +1,39 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2010  Intel Corporation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *   Emmanuele Bassi <ebassi@linux.intel.com>
+ */
+
+/**
+ * SECTION:ClutterBindConstraint
+ * @Title: ClutterBindConstraint
+ * @Short_Description: A constraint binding the position of an actor
+ *
+ * #ClutterBindConstraint is a #ClutterConstraint that binds the position of
+ * the #ClutterActor to which it is applied to the the position of another
+ * #ClutterActor.
+ *
+ * #ClutterBindConstraint is available since Clutter 1.4
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -20,7 +56,7 @@ struct _ClutterBindConstraint
   ClutterConstraint parent_instance;
 
   ClutterActor *source;
-  ClutterBindAxis bind_axis;
+  ClutterBindCoordinate coordinate;
   gfloat offset;
 };
 
@@ -34,7 +70,7 @@ enum
   PROP_0,
 
   PROP_SOURCE,
-  PROP_BIND_AXIS,
+  PROP_COORDINATE,
   PROP_OFFSET
 };
 
@@ -59,17 +95,17 @@ update_actor_position (ClutterBindConstraint *bind)
   source_position.y = clutter_actor_get_y (bind->source);
   source_position.z = clutter_actor_get_depth (bind->source);
 
-  switch (bind->bind_axis)
+  switch (bind->coordinate)
     {
-    case CLUTTER_BIND_X_AXIS:
+    case CLUTTER_BIND_X:
       clutter_actor_set_x (actor, source_position.x + bind->offset);
       break;
 
-    case CLUTTER_BIND_Y_AXIS:
+    case CLUTTER_BIND_Y:
       clutter_actor_set_y (actor, source_position.y + bind->offset);
       break;
 
-    case CLUTTER_BIND_Z_AXIS:
+    case CLUTTER_BIND_Z:
       clutter_actor_set_depth (actor, source_position.z + bind->offset);
       break;
     }
@@ -125,17 +161,17 @@ _clutter_bind_constraint_set_source (ClutterBindConstraint *bind,
 }
 
 static void
-_clutter_bind_constraint_set_bind_axis (ClutterBindConstraint *bind,
+_clutter_bind_constraint_set_coordinate (ClutterBindConstraint *bind,
-                                        ClutterBindAxis        axis)
+                                         ClutterBindCoordinate  coord)
 {
-  if (bind->bind_axis == axis)
+  if (bind->coordinate == coord)
     return;
 
-  bind->bind_axis = axis;
+  bind->coordinate = coord;
 
   update_actor_position (bind);
 
-  g_object_notify (G_OBJECT (bind), "bind-axis");
+  g_object_notify (G_OBJECT (bind), "coordinate");
 }
 
 static void
@@ -166,8 +202,8 @@ clutter_bind_constraint_set_property (GObject      *gobject,
       _clutter_bind_constraint_set_source (bind, g_value_get_object (value));
       break;
 
-    case PROP_BIND_AXIS:
+    case PROP_COORDINATE:
-      _clutter_bind_constraint_set_bind_axis (bind, g_value_get_enum (value));
+      _clutter_bind_constraint_set_coordinate (bind, g_value_get_enum (value));
       break;
 
     case PROP_OFFSET:
@@ -194,8 +230,8 @@ clutter_bind_constraint_get_property (GObject    *gobject,
       g_value_set_object (value, bind->source);
       break;
 
-    case PROP_BIND_AXIS:
+    case PROP_COORDINATE:
-      g_value_set_enum (value, bind->bind_axis);
+      g_value_set_enum (value, bind->coordinate);
       break;
 
     case PROP_OFFSET:
@@ -217,6 +253,13 @@ clutter_bind_constraint_class_init (ClutterBindConstraintClass *klass)
   gobject_class->set_property = clutter_bind_constraint_set_property;
   gobject_class->get_property = clutter_bind_constraint_get_property;
 
+  /**
+   * ClutterBindConstraint:source:
+   *
+   * The #ClutterActor used as the source for the binding
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_object ("source",
                                "Source",
                                "The source of the binding",
@@ -225,15 +268,29 @@ clutter_bind_constraint_class_init (ClutterBindConstraintClass *klass)
                                G_PARAM_CONSTRUCT);
   g_object_class_install_property (gobject_class, PROP_SOURCE, pspec);
 
-  pspec = g_param_spec_enum ("bind-axis",
+  /**
-                             "Bind Axis",
+   * ClutterBindConstraint:coordinate:
-                             "The axis to bind the position from",
+   *
-                             CLUTTER_TYPE_BIND_AXIS,
+   * The coordinate to be bound
-                             CLUTTER_BIND_X_AXIS,
+   *
+   * Since: 1.4
+   */
+  pspec = g_param_spec_enum ("coordinate",
+                             "Coordinate",
+                             "The coordinate to bind",
+                             CLUTTER_TYPE_BIND_COORDINATE,
+                             CLUTTER_BIND_X,
                              CLUTTER_PARAM_READWRITE |
                              G_PARAM_CONSTRUCT);
-  g_object_class_install_property (gobject_class, PROP_BIND_AXIS, pspec);
+  g_object_class_install_property (gobject_class, PROP_COORDINATE, pspec);
 
+  /**
+   * ClutterBindConstraint:offset:
+   *
+   * The offset, in pixels, to be applied to the binding
+   *
+   * Since: 1.4
+   */
   pspec = g_param_spec_float ("offset",
                               "Offset",
                               "The offset in pixels to apply to the binding",
@@ -248,20 +305,33 @@ static void
 clutter_bind_constraint_init (ClutterBindConstraint *self)
 {
   self->source = NULL;
-  self->bind_axis = CLUTTER_BIND_X_AXIS;
+  self->coordinate = CLUTTER_BIND_X;
   self->offset = 0.0f;
 }
 
+/**
+ * clutter_bind_constraint_new:
+ * @source: the #ClutterActor to use as the source of the binding
+ * @coordinate: the coordinate to bind
+ * @offset: the offset to apply to the binding, in pixels
+ *
+ * Creates a new constraint, binding a #ClutterActor's position to
+ * the given @coordinate of the position of @source
+ *
+ * Return value: the newly created #ClutterBindConstraint
+ *
+ * Since: 1.4
+ */
 ClutterConstraint *
 clutter_bind_constraint_new (ClutterActor          *source,
-                             ClutterBindAxis  axis,
+                             ClutterBindCoordinate  coordinate,
                              gfloat                 offset)
 {
   g_return_val_if_fail (CLUTTER_IS_ACTOR (source), NULL);
 
   return g_object_new (CLUTTER_TYPE_BIND_CONSTRAINT,
                        "source", source,
-                       "bind-axis", axis,
+                       "coordinate", coordinate,
                        "offset", offset,
                        NULL);
 }

clutter/clutter-bind-constraint.h

@@ -1,3 +1,27 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2010  Intel Corporation.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library. If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Author:
+ *   Emmanuele Bassi <ebassi@linux.intel.com>
+ */
+
 #if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
 #error "Only <clutter/clutter.h> can be included directly."
 #endif
@@ -16,15 +40,15 @@ G_BEGIN_DECLS
 typedef struct _ClutterBindConstraint   ClutterBindConstraint;
 
 typedef enum { /*< prefix=CLUTTER_BIND >*/
-  CLUTTER_BIND_X_AXIS,
+  CLUTTER_BIND_X,
-  CLUTTER_BIND_Y_AXIS,
+  CLUTTER_BIND_Y,
-  CLUTTER_BIND_Z_AXIS
+  CLUTTER_BIND_Z
-} ClutterBindAxis;
+} ClutterBindCoordinate;
 
 GType clutter_bind_constraint_get_type (void) G_GNUC_CONST;
 
 ClutterConstraint *clutter_bind_constraint_new (ClutterActor          *source,
-                                                ClutterBindAxis  axis,
+                                                ClutterBindCoordinate  coordinate,
                                                 gfloat                 offset);
 
 G_END_DECLS

tests/interactive/test-constraints.c

@@ -21,6 +21,9 @@ on_button_release (ClutterActor *actor,
                          * -1.0f;
       gfloat right_offset = clutter_actor_get_width (right_rect) + H_PADDING;
 
+      clutter_actor_animate (center_rect, CLUTTER_LINEAR, 500,
+                             "opacity", 128,
+                             NULL);
       clutter_actor_animate (left_rect, CLUTTER_EASE_OUT_CUBIC, 500,
                              "opacity", 255,
                              "@constraints.x-bind.offset", left_offset,
@@ -32,6 +35,9 @@ on_button_release (ClutterActor *actor,
     }
   else
     {
+      clutter_actor_animate (center_rect, CLUTTER_LINEAR, 500,
+                             "opacity", 255,
+                             NULL);
       clutter_actor_animate (left_rect, CLUTTER_EASE_OUT_CUBIC, 500,
                              "opacity", 0,
                              "@constraints.x-bind.offset", 0.0f,
@@ -68,7 +74,7 @@ test_constraints_main (int argc, char *argv[])
                     G_CALLBACK (on_button_release),
                     NULL);
   clutter_rectangle_set_color (CLUTTER_RECTANGLE (rect), &rect_color);
-  clutter_actor_set_size (rect, 256, 256);
+  clutter_actor_set_size (rect, 128, 128);
   clutter_actor_set_reactive (rect, TRUE);
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
 
@@ -86,11 +92,11 @@ test_constraints_main (int argc, char *argv[])
   clutter_color_from_string (&rect_color, "#cc0000ff");
   rect = clutter_rectangle_new ();
   clutter_rectangle_set_color (CLUTTER_RECTANGLE (rect), &rect_color);
-  clutter_actor_set_size (rect, 256, 256);
+  clutter_actor_set_size (rect, 128, 128);
   clutter_actor_set_opacity (rect, 0);
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
 
-  constraint = clutter_bind_constraint_new (center_rect, CLUTTER_BIND_X_AXIS, 0.0f);
+  constraint = clutter_bind_constraint_new (center_rect, CLUTTER_BIND_X, 0.0f);
   clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "x-bind");
   clutter_actor_add_constraint (rect, constraint);
 
@@ -104,11 +110,11 @@ test_constraints_main (int argc, char *argv[])
   clutter_color_from_string (&rect_color, "#3465a4ff");
   rect = clutter_rectangle_new ();
   clutter_rectangle_set_color (CLUTTER_RECTANGLE (rect), &rect_color);
-  clutter_actor_set_size (rect, 256, 256);
+  clutter_actor_set_size (rect, 128, 128);
   clutter_actor_set_opacity (rect, 0);
   clutter_container_add_actor (CLUTTER_CONTAINER (stage), rect);
 
-  constraint = clutter_bind_constraint_new (center_rect, CLUTTER_BIND_X_AXIS, 0.0f);
+  constraint = clutter_bind_constraint_new (center_rect, CLUTTER_BIND_X, 0.0f);
   clutter_actor_meta_set_name (CLUTTER_ACTOR_META (constraint), "x-bind");
   clutter_actor_add_constraint (rect, constraint);