2008-06-17 Emmanuele Bassi <ebassi@openedhand.com>

	* clutter/clutter-actor.h:
	* clutter/clutter-actor.c:
	(clutter_actor_allocate_preferred_size): Add more documentation
	and notes on where it's appropriate to call this function.

diff --git a/ChangeLog b/ChangeLog
index 8ef7e04..e3843bc 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2008-06-17  Emmanuele Bassi  <ebassi@openedhand.com>
+
+       * clutter/clutter-actor.h:
+       * clutter/clutter-actor.c:
+       (clutter_actor_allocate_preferred_size): Add more documentation
+       and notes on where it's appropriate to call this function.
+
 2008-06-17  Chris Lord  <chris@openedhand.com>
 
        * clutter/clutter-texture.c: (clutter_texture_get_preferred_width),

diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 97d9b9c..235e7a9 100644 (file)
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -7362,32 +7362,38 @@ clutter_actor_get_stage (ClutterActor *actor)
 
 /**
  * clutter_actor_allocate_preferred_size:
- * @actor: a #ClutterActor
- * @absolute_origin_changed:  whether the position of the parent has
+ * @self: a #ClutterActor
+ * @absolute_origin_changed: whether the position of the parent has
  *   changed in stage coordinates
  *
- * Utility call for Actor implementations that allocates the actors
- * preffered natural size.
+ * Allocates the natural size of @self.
+ *
+ * This function is a utility call for #ClutterActor implementations
+ * that allocates the actor's preferred natural size. It can be used
+ * by fixed layout managers (like #ClutterGroup) inside the
+ * ClutterActor::allocate implementation to give each child exactly
+ * how much space it requires.
+ *
+ * This function is not meant to be used by applications. It is also
+ * not meant to be used outside the implementation of the
+ * ClutterActor::allocate virtual function.
  *
  * Since: 0.8
  */
 void
-clutter_actor_allocate_preferred_size (ClutterActor *actor,
+clutter_actor_allocate_preferred_size (ClutterActor *self,
                                        gboolean      absolute_origin_changed)
 {
   ClutterUnit actor_x, actor_y;
   ClutterUnit natural_width, natural_height;
   ClutterActorBox actor_box;
 
-  g_return_if_fail (CLUTTER_IS_ACTOR (actor));
+  g_return_if_fail (CLUTTER_IS_ACTOR (self));
   
-  actor_x = clutter_actor_get_xu (actor);
-  actor_y = clutter_actor_get_yu (actor);
+  actor_x = clutter_actor_get_xu (self);
+  actor_y = clutter_actor_get_yu (self);
 
-  /* All actorren get their position and natural size (the
-   * container's allocation is flat-out ignored).
-   */
-  clutter_actor_get_preferred_size (actor,
+  clutter_actor_get_preferred_size (self,
                                     NULL, NULL,
                                     &natural_width,
                                     &natural_height);
@@ -7397,5 +7403,5 @@ clutter_actor_allocate_preferred_size (ClutterActor *actor,
   actor_box.x2 = actor_box.x1 + natural_width;
   actor_box.y2 = actor_box.y1 + natural_height;
 
-  clutter_actor_allocate (actor, &actor_box, absolute_origin_changed);
+  clutter_actor_allocate (self, &actor_box, absolute_origin_changed);
 }

diff --git a/clutter/clutter-actor.h b/clutter/clutter-actor.h
index 44a21fe..1e734b9 100644 (file)
--- a/clutter/clutter-actor.h
+++ b/clutter/clutter-actor.h
@@ -301,6 +301,8 @@ void                  clutter_actor_get_preferred_size        (ClutterActor
 void                  clutter_actor_allocate                  (ClutterActor          *self,
                                                                const ClutterActorBox *box,
                                                                gboolean               absolute_origin_changed);
+void                  clutter_actor_allocate_preferred_size   (ClutterActor          *self,
+                                                               gboolean               absolute_origin_changed);
 void                  clutter_actor_get_allocation_coords     (ClutterActor          *self,
                                                                gint                  *x_1,
                                                                gint                  *y_1,
@@ -556,9 +558,6 @@ void clutter_actor_apply_relative_transform_to_point (ClutterActor  *self,
                                                       ClutterVertex *point,
                                                       ClutterVertex *vertex);
 
-void clutter_actor_allocate_preferred_size            (ClutterActor *actor,
-                                                       gboolean      absolute_origin_changed);
-
 G_END_DECLS
 
 #endif /* _HAVE_CLUTTER_ACTOR_H */