diff --git a/clutter/clutter-bin-layout.c b/clutter/clutter-bin-layout.c
index 956e3467f..7c1c55ff1 100644
--- a/clutter/clutter-bin-layout.c
+++ b/clutter/clutter-bin-layout.c
@@ -29,6 +29,50 @@
* #ClutterBinLayout is a layout manager which implements the following
* policy:
*
+ *
+ * the preferred size is the maximum preferred size
+ * between all the children of the container using the
+ * layout;
+ * each child is allocated in "layers", on on top
+ * of the other;
+ * for each layer there are horizontal and vertical
+ * alignment policies.
+ *
+ *
+ *
+ * How to pack actors inside a BinLayout
+ * The following code shows how to build a composite actor with
+ * a texture and a background, and add controls overlayed on top. The
+ * background is set to fill the whole allocation, whilst the texture
+ * is centered; there is a control in the top right corner and a label
+ * in the bottom, filling out the whole allocated width.
+ *
+ * ClutterLayoutManager *manager;
+ * ClutterActor *box;
+ *
+ * /* create the layout first */
+ * layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_CENTER,
+ * CLUTTER_BIN_ALIGNMENT_CENTER);
+ * box = clutter_box_new (layout); /* then the container */
+ *
+ * /* we can use the layout object to add actors */
+ * clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), background,
+ * CLUTTER_BIN_ALIGNMENT_FILL,
+ * CLUTTER_BIN_ALIGNMENT_FILL);
+ * clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), icon,
+ * CLUTTER_BIN_ALIGNMENT_CENTER,
+ * CLUTTER_BIN_ALIGNMENT_CENTER);
+ *
+ * /* align to the bottom left */
+ * clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), label,
+ * CLUTTER_BIN_ALIGNMENT_START,
+ * CLUTTER_BIN_ALIGNMENT_END);
+ * /* align to the top right */
+ * clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout), button,
+ * CLUTTER_BIN_ALIGNMENT_END,
+ * CLUTTER_BIN_ALIGNMENT_START);
+ *
+ *
*
* #ClutterBinLayout is available since Clutter 1.2
*/
@@ -95,7 +139,6 @@ G_DEFINE_TYPE (ClutterBinLayout,
clutter_bin_layout,
CLUTTER_TYPE_LAYOUT_MANAGER);
-
/*
* ClutterBinLayer
*/
@@ -509,16 +552,16 @@ clutter_bin_layout_set_property (GObject *gobject,
const GValue *value,
GParamSpec *pspec)
{
+ ClutterBinLayout *layout = CLUTTER_BIN_LAYOUT (gobject);
+
switch (prop_id)
{
case PROP_X_ALIGN:
- set_x_align (CLUTTER_BIN_LAYOUT (gobject),
- g_value_get_enum (value));
+ set_x_align (layout, g_value_get_enum (value));
break;
case PROP_Y_ALIGN:
- set_y_align (CLUTTER_BIN_LAYOUT (gobject),
- g_value_get_enum (value));
+ set_y_align (layout, g_value_get_enum (value));
break;
default:
@@ -569,8 +612,8 @@ clutter_bin_layout_class_init (ClutterBinLayoutClass *klass)
/**
* ClutterBinLayout:x-align:
*
- * The horizontal alignment policy for actors managed by the
- * #ClutterBinLayout
+ * The default horizontal alignment policy for actors managed
+ * by the #ClutterBinLayout
*
* Since: 1.2
*/
@@ -586,8 +629,8 @@ clutter_bin_layout_class_init (ClutterBinLayoutClass *klass)
/**
* ClutterBinLayout:y-align:
*
- * The vertical alignment policy for actors managed by the
- * #ClutterBinLayout
+ * The default vertical alignment policy for actors managed
+ * by the #ClutterBinLayout
*
* Since: 1.2
*/
@@ -670,16 +713,24 @@ clutter_bin_layout_set_alignment (ClutterBinLayout *self,
ClutterBinLayoutPrivate *priv;
ClutterLayoutManager *manager;
ClutterLayoutMeta *meta;
- ClutterBinLayer *layer;
g_return_if_fail (CLUTTER_IS_BIN_LAYOUT (self));
+ g_return_if_fail (child == NULL || CLUTTER_IS_ACTOR (child));
priv = self->priv;
- if (child == NULL || priv->container == NULL)
+ if (priv->container == NULL)
{
- set_x_align (self, x_align);
- set_y_align (self, y_align);
+ if (child == NULL)
+ {
+ set_x_align (self, x_align);
+ set_y_align (self, y_align);
+ }
+ else
+ g_warning ("The layout of type '%s' must be associated to "
+ "a ClutterContainer before setting the alignment "
+ "on its children",
+ G_OBJECT_TYPE_NAME (self));
return;
}
@@ -688,12 +739,10 @@ clutter_bin_layout_set_alignment (ClutterBinLayout *self,
meta = clutter_layout_manager_get_child_meta (manager,
priv->container,
child);
- g_return_if_fail (CLUTTER_IS_BIN_LAYER (meta));
+ g_assert (CLUTTER_IS_BIN_LAYER (meta));
- layer = CLUTTER_BIN_LAYER (meta);
-
- set_layer_x_align (layer, x_align);
- set_layer_y_align (layer, y_align);
+ set_layer_x_align (CLUTTER_BIN_LAYER (meta), x_align);
+ set_layer_y_align (CLUTTER_BIN_LAYER (meta), y_align);
}
/**
@@ -728,13 +777,21 @@ clutter_bin_layout_get_alignment (ClutterBinLayout *self,
priv = self->priv;
- if (child == NULL || priv->container == NULL)
+ if (priv->container == NULL)
{
- if (x_align)
- *x_align = priv->x_align;
+ if (child == NULL)
+ {
+ if (x_align)
+ *x_align = priv->x_align;
- if (y_align)
- *y_align = priv->y_align;
+ if (y_align)
+ *y_align = priv->y_align;
+ }
+ else
+ g_warning ("The layout of type '%s' must be associated to "
+ "a ClutterContainer before getting the alignment "
+ "of its children",
+ G_OBJECT_TYPE_NAME (self));
return;
}
@@ -743,7 +800,7 @@ clutter_bin_layout_get_alignment (ClutterBinLayout *self,
meta = clutter_layout_manager_get_child_meta (manager,
priv->container,
child);
- g_return_if_fail (CLUTTER_IS_BIN_LAYER (meta));
+ g_assert (CLUTTER_IS_BIN_LAYER (meta));
layer = CLUTTER_BIN_LAYER (meta);
@@ -765,8 +822,9 @@ clutter_bin_layout_get_alignment (ClutterBinLayout *self,
* sets the alignment policies for it
*
* This function is equivalent to clutter_container_add_actor()
- * and clutter_layout_manager_get_child_meta() but it does not
- * require the #ClutterContainer
+ * and clutter_layout_manager_child_set_property() but it does not
+ * require a pointer to the #ClutterContainer associated to the
+ * #ClutterBinLayout
*
* Since: 1.2
*/
@@ -776,10 +834,9 @@ clutter_bin_layout_add (ClutterBinLayout *self,
ClutterBinAlignment x_align,
ClutterBinAlignment y_align)
{
- ClutterBinLayer *layer;
- ClutterLayoutMeta *meta;
- ClutterLayoutManager *manager;
ClutterBinLayoutPrivate *priv;
+ ClutterLayoutManager *manager;
+ ClutterLayoutMeta *meta;
g_return_if_fail (CLUTTER_IS_BIN_LAYOUT (self));
g_return_if_fail (CLUTTER_IS_ACTOR (child));
@@ -802,7 +859,6 @@ clutter_bin_layout_add (ClutterBinLayout *self,
child);
g_assert (CLUTTER_IS_BIN_LAYER (meta));
- layer = CLUTTER_BIN_LAYER (meta);
- set_layer_x_align (layer, x_align);
- set_layer_y_align (layer, y_align);
+ set_layer_x_align (CLUTTER_BIN_LAYER (meta), x_align);
+ set_layer_y_align (CLUTTER_BIN_LAYER (meta), y_align);
}
diff --git a/clutter/clutter-bin-layout.h b/clutter/clutter-bin-layout.h
index 0ce9587ae..169af0774 100644
--- a/clutter/clutter-bin-layout.h
+++ b/clutter/clutter-bin-layout.h
@@ -1,3 +1,27 @@
+/*
+ * Clutter.
+ *
+ * An OpenGL based 'interactive canvas' library.
+ *
+ * Copyright (C) 2009 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 .
+ *
+ * Author:
+ * Emmanuele Bassi
+ */
+
#if !defined(__CLUTTER_H_INSIDE__) && !defined(CLUTTER_COMPILATION)
#error "Only can be included directly."
#endif