cookbook: Added layout introduction and "stacking actors" recipe

Expanded the layout introduction and added a recipe about
stacking actors using ClutterBinLayout, with two examples.

doc/cookbook/Makefile.am

@@ -37,6 +37,7 @@ IMAGE_FILES = \
 	images/actors-opacity-container-affects-opacity.png \
 	images/text-shadow.png \
 	images/textures-sub-texture.png \
+	images/layouts-stacking-diff-actor-sizes.png \
 	$(NULL)
 VIDEO_FILES = \
 	videos/animations-fading-out.ogv \

doc/cookbook/examples/.gitignore

@@ -3,3 +3,5 @@
 /textures-reflection
 /textures-split-go
 /textures-sub-texture
+/layouts-stacking
+/layouts-stacking-diff-sized-actors

doc/cookbook/examples/Makefile.am

@@ -8,6 +8,8 @@ noinst_PROGRAMS = \
 	textures-reflection	\
 	textures-split-go	\
 	textures-sub-texture	\
+	layouts-stacking \
+	layouts-stacking-diff-sized-actors	\
 	$(NULL)
 
 INCLUDES = \
@@ -29,8 +31,10 @@ AM_CFLAGS = \
 
 AM_LDFLAGS = $(CLUTTER_LIBS)
 
-animations_rotating_SOURCES   = animations-rotating.c
-text_shadow_SOURCES           = text-shadow.c
-textures_reflection_SOURCES   = textures-reflection.c
-textures_split_go_SOURCES     = textures-split-go.c
-textures_sub_texture_SOURCES  = textures-sub-texture.c
+animations_rotating_SOURCES                = animations-rotating.c
+text_shadow_SOURCES                        = text-shadow.c
+textures_reflection_SOURCES                = textures-reflection.c
+textures_split_go_SOURCES                  = textures-split-go.c
+textures_sub_texture_SOURCES               = textures-sub-texture.c
+layouts_stacking_SOURCES                   = layouts-stacking.c
+layouts_stacking_diff_sized_actors_SOURCES = layouts-stacking-diff-sized-actors.c

doc/cookbook/examples/layouts-stacking-diff-sized-actors.c

@@ -0,0 +1,78 @@
+#include <clutter/clutter.h>
+
+static const ClutterColor dark_grey = { 0x66, 0x66, 0x66, 0xff };
+static const ClutterColor light_grey = { 0xcc, 0xcc, 0xcc, 0xff };
+
+int
+main (int argc, char *argv[])
+{
+  ClutterActor *stage;
+  ClutterLayoutManager *layout;
+  ClutterActor *box;
+  ClutterActor *rect1, *rect2;
+  guint align_x, align_y, diff_x, diff_y;
+
+  clutter_init (&argc, &argv);
+
+  stage = clutter_stage_get_default ();
+  clutter_actor_set_size (stage, 400, 400);
+
+  layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_START,
+                                   CLUTTER_BIN_ALIGNMENT_START);
+
+  box = clutter_box_new (layout);
+
+  rect1 = clutter_rectangle_new_with_color (&dark_grey);
+  clutter_actor_set_size (rect1, 400, 200);
+
+  rect2 = clutter_rectangle_new_with_color (&light_grey);
+  clutter_actor_set_size (rect2, 200, 400);
+
+  clutter_container_add (CLUTTER_CONTAINER (box),
+                         rect1,
+                         rect2,
+                         NULL);
+
+  /*
+   * 2 = CLUTTER_BIN_ALIGNMENT_START
+   * 3 = CLUTTER_BIN_ALIGNMENT_END
+   * 4 = CLUTTER_BIN_ALIGNMENT_CENTER
+   */
+  for (align_x = 2; align_x < 5; align_x++)
+    {
+      for (align_y = 2; align_y < 5; align_y++)
+        {
+          diff_x = align_x - 1;
+          if (align_x == 3)
+            diff_x = 3;
+          else if (align_x == 4)
+            diff_x = 2;
+
+          diff_y = align_y - 1;
+          if (align_y == 3)
+            diff_y = 3;
+          else if (align_y == 4)
+            diff_y = 2;
+
+          ClutterColor *color = clutter_color_new (255 - diff_x * 50,
+                                                   100 + diff_y * 50,
+                                                   0,
+                                                   255);
+          ClutterActor *rect = clutter_rectangle_new_with_color (color);
+          clutter_actor_set_size (rect, 100, 100);
+          clutter_bin_layout_set_alignment (CLUTTER_BIN_LAYOUT (layout),
+                                            rect,
+                                            align_x,
+                                            align_y);
+          clutter_container_add_actor (CLUTTER_CONTAINER (box), rect);
+        }
+    }
+
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), box);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  return 0;
+}

doc/cookbook/examples/layouts-stacking.c

@@ -0,0 +1,80 @@
+/*
+ * Display multiple rotated copies of an image on top of each other
+ *
+ * Invoke with the path to a file to load a custom image
+ */
+#include <clutter/clutter.h>
+
+#define STAGE_SIDE 512
+
+static const ClutterColor box_color = { 0x33, 0x33, 0x55, 0xff };
+
+int
+main (int argc, char *argv[])
+{
+  gchar *filename = TESTS_DATA_DIR "/redhand.png";
+
+  if (argc > 1)
+    filename = argv[1];
+
+  ClutterLayoutManager *layout;
+  ClutterActor *box;
+  ClutterActor *stage;
+  ClutterActor *texture;
+  CoglHandle *cogl_texture;
+  GError *error = NULL;
+  gfloat width;
+
+  clutter_init (&argc, &argv);
+
+  stage = clutter_stage_get_default ();
+  clutter_actor_set_size (stage, STAGE_SIDE, STAGE_SIDE);
+
+  layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_CENTER,
+                                   CLUTTER_BIN_ALIGNMENT_CENTER);
+
+  box = clutter_box_new (layout);
+  clutter_box_set_color (CLUTTER_BOX (box), &box_color);
+
+  texture = clutter_texture_new_from_file (filename, &error);
+
+  if (error != NULL)
+    g_error ("Error loading file %s; message was:\n%s",
+             filename,
+             error->message);
+
+  /*
+   * get a reference to the underlying Cogl texture
+   * for copying onto each Clutter texture placed into the layout
+   */
+  cogl_texture = clutter_texture_get_cogl_texture (CLUTTER_TEXTURE (texture));
+
+  /*
+   * add gradually turning and shrinking textures,
+   * smallest one last; each actor ends up on top
+   * of the one added just before it
+   */
+  for (width = STAGE_SIDE * 0.75; width >= STAGE_SIDE * 0.0625; width -= STAGE_SIDE * 0.0625)
+    {
+      ClutterActor *texture_copy = clutter_texture_new ();
+      clutter_texture_set_cogl_texture (CLUTTER_TEXTURE (texture_copy),
+                                        cogl_texture);
+      clutter_texture_set_keep_aspect_ratio (CLUTTER_TEXTURE (texture_copy),
+                                             TRUE);
+      clutter_actor_set_z_rotation_from_gravity (texture_copy,
+                                                 (gfloat)(width * 0.5) - (STAGE_SIDE * 0.03125),
+                                                 CLUTTER_GRAVITY_CENTER);
+      clutter_actor_set_width (texture_copy, width);
+      clutter_container_add_actor (CLUTTER_CONTAINER (box), texture_copy);
+    }
+
+  clutter_actor_add_constraint (box, clutter_align_constraint_new (stage, CLUTTER_ALIGN_X_AXIS, 0.5));
+  clutter_actor_add_constraint (box, clutter_align_constraint_new (stage, CLUTTER_ALIGN_Y_AXIS, 0.5));
+  clutter_container_add_actor (CLUTTER_CONTAINER (stage), box);
+
+  clutter_actor_show (stage);
+
+  clutter_main ();
+
+  return 0;
+}

doc/cookbook/layouts.xml

@@ -7,8 +7,10 @@
   <title>Layout management</title>
 
   <epigraph>
-    <attribution>who</attribution>
-    <para>what they said</para>
+    <attribution>Abigail Adams, wife of John Adams, in a letter to John
+    Thaxter (1778-09-29)</attribution>
+    <para>If we do not lay out ourselves in the service of mankind,
+    whom should we serve?</para>
   </epigraph>
 
   <section id="layouts-introduction">
@@ -19,8 +21,8 @@
     specifically, layouts are managed by associating a parent with a
     <type>ClutterLayoutManager</type>; the parent is usually either a
     composite <type>ClutterActor</type> (composed of several
-    <type>ClutterActor</type>s) or a <type>ClutterContainer</type>
-    (containing child <type>ClutterActor</type>s). The
+    <type>ClutterActors</type>) or a <type>ClutterContainer</type>
+    (containing child <type>ClutterActors</type>). The
     <type>ClutterLayoutManager</type> then manages:</para>
 
     <orderedlist>
@@ -35,7 +37,19 @@
       </listitem>
     </orderedlist>
 
-    <para>The following sections give a brief overview of how layout
+    <note>
+      <para>To make this more concrete, imagine you have a sheet of
+      paper and some coloured squares to place on it. Someone stands
+      next to you telling you how big the piece of paper should be,
+      how big the squares should be, and where to put each square on the
+      piece of paper.</para>
+      <para>The sheet of paper is analogous to the container or
+      composite actor; the squares are analogous to the child
+      <type>ClutterActors</type>; and the person giving you instructions
+      is analogous to the layout manager.</para>
+    </note>
+
+    <para>The following sections give an overview of how layout
     management works in Clutter.</para>
 
     <section>
@@ -80,6 +94,13 @@
       how to make use of the different layout manager
       implementations.</para>
 
+      <note>
+        <para>It is not possible to use a layout manager with an arbitrary
+        <type>ClutterContainer</type>: you must use a <type>ClutterActor</type>
+        subclass which can delegate its layout to a layout manager (either
+        use <type>ClutterBox</type> or write your own).</para>
+      </note>
+
     </section>
 
     <section id="layouts-introduction-manager-types">
@@ -93,7 +114,7 @@
           <para><type>ClutterFixedLayout</type> arranges actors
           at fixed positions on the stage. No alignment options are
           available, so you have to manually compute and manage the
-          coordinates (or use <type>ClutterConstraint</type>s) which
+          coordinates (or use <type>ClutterConstraints</type>) which
           will align actors how you want them.</para>
         </listitem>
         <listitem>
@@ -122,7 +143,7 @@
 
     </section>
 
-    <section>
+    <section id="layouts-introduction-layout-properties">
       <title>Layout properties</title>
 
       <para>How actors are sized and positioned inside a container
@@ -161,7 +182,9 @@
           <formalpara>
             <title>Alignment</title>
             <para>How an actor aligns to the container's axes, e.g.
-            aligned to the container's left, right, or center.</para>
+            aligned to the container's left, right, or center. For some
+            layouts (like <type>ClutterBinLayout</type>) alignment
+            is also used to set expand and fill properties.</para>
           </formalpara>
         </listitem>
         <listitem>
@@ -276,6 +299,292 @@
 
     </section>
 
+    <section id="layouts-introduction-not-using-layout-managers">
+      <title>Not using layout managers</title>
+
+      <para>It is perfectly possible to arrange <type>ClutterActors</type>
+      without using layout managers; however, you may have to do
+      more of your own calculations about actor sizes and positions.</para>
+
+      <para>There are two (not mutually-exclusive) approaches you can
+      take to do this, described below.</para>
+
+      <section>
+        <title>Manual positioning and alignment</title>
+
+        <para>This basically means using the <type>ClutterActor</type>
+        bounding box mechanism (see the <type>ClutterActor</type>
+        documentation for details) to set actor sizes and positions.
+        This is the approach you will see in a lot of older Clutter
+        code (written before layout managers were available).</para>
+
+        <para>This approach is simplest where the UI is relatively static
+        and is composed of a few known actors. It will work in larger,
+        more complex scenarios, but in those sorts of cases it is better
+        to make use of layout managers and constraints (see below) instead.</para>
+      </section>
+
+      <section>
+        <title>Using <type>ClutterConstraint</type></title>
+
+        <para>Constraints provide mechanisms for:</para>
+
+        <itemizedlist>
+          <listitem>
+            <para>Aligning actors with each other
+            (<type>ClutterAlignConstraint</type>). For example, you
+            can align the top, bottom or center of one actor with the
+            top, bottom or center of another (on the <code>y</code>
+            axis). Similarly, you can align one actor to another
+            on the <code>x</code> axis.</para>
+          </listitem>
+          <listitem>
+            <para>Binding properties of one actor to those of
+            another. For example, you could ensure that two actors
+            always remain the same width; or you could specify
+            that two actors always have the same <code>x</code>
+            coordinate. In both these cases and others, you can
+            specify that the properties should be the same, or the same
+            +/- some offset.</para>
+          </listitem>
+        </itemizedlist>
+
+        <note>
+          <para><type>ClutterConstraints</type> can be used in combination
+          with some layout managers, but you need to be careful that
+          constraints don't fight with the layout manager policies.
+          Unpredictable results could ensue.</para>
+        </note>
+
+      </section>
+
+    </section>
+
+  </section>
+
+  <section id="layouts-stacking">
+    <title>Stacking actors on top of each other</title>
+
+    <section>
+      <title>Problem</title>
+
+      <para>You want to lay out several actors so that they are in
+      layers on top of each other (e.g. to create a button widget
+      composed from a rectangle with text on top of it).</para>
+    </section>
+
+    <section id="layouts-stacking-solution">
+      <title>Solution</title>
+
+      <para>The most flexible approach is to use a <type>ClutterBinLayout</type>
+      associated with a <type>ClutterBox</type>:</para>
+
+      <informalexample>
+        <programlisting>
+<![CDATA[
+/* define some colors */
+const ClutterColor background_color = { 0xaa, 0x99, 0x00, 0xff };
+const ClutterColor text_color = { 0xff, 0xff, 0xff, 0xff };
+
+ClutterLayoutManager *layout;
+ClutterActor *box;
+ClutterActor *background;
+ClutterActor *text;
+
+/*
+ * create a layout, setting the default x and y alignment;
+ * actors fill the whole allocation of the layout's container
+ * by default
+ */
+layout = clutter_bin_layout_new (CLUTTER_BIN_ALIGNMENT_FILL,
+                                 CLUTTER_BIN_ALIGNMENT_FILL);
+
+/* create the box whose children the layout will manage */
+box = clutter_box_new (layout);
+
+/*
+ * fill doesn't have much effect here
+ * unless the container has height and/or width
+ */
+clutter_actor_set_size (box, 100, 30);
+
+/*
+ * background for the button; could equally be a texture
+ * with an image loaded into it or any other ClutterActor
+ */
+background = clutter_rectangle_new_with_color (&background_color);
+
+/*
+ * add the background to the container;
+ * as it should use the default alignment, it can be added
+ * direct to the container, rather than via the layout
+ */
+clutter_container_add_actor (CLUTTER_CONTAINER (box), background);
+
+/* text for the button */
+text = clutter_text_new_full ("Sans 15px", "Click me", &text_color);
+
+/*
+ * the text requires a different alignment from the background
+ * (centered on the box)
+ * so we add it via the layout so the default
+ * alignment can be overridden
+ */
+clutter_bin_layout_add (CLUTTER_BIN_LAYOUT (layout),
+                        text,
+                        CLUTTER_BIN_ALIGNMENT_CENTER,
+                        CLUTTER_BIN_ALIGNMENT_CENTER);
+
+/*
+ * ensure the actors are arranged in the correct depth order;
+ * in this case, the text is on top
+ * (NB this is not strictly necesary here as text is added after
+ * background)
+ */
+clutter_actor_raise_top (text);
+]]>
+        </programlisting>
+      </informalexample>
+    </section>
+
+    <section>
+      <title>Discussion</title>
+
+      <para>This section covers some other aspects of using a
+      <type>ClutterBinLayout</type>.</para>
+
+      <section>
+        <title>Setting and changing alignment</title>
+
+        <para>Alignment is the only
+        <link linkend="layouts-introduction-layout-properties">layout
+        property</link> available for <type>ClutterBinLayout</type>. Each
+        actor can have a different setting for its alignment in one or both
+        of the <code>x</code> or <code>y</code> axes. However, as shown in the
+        solution above, alignment can also be used to expand an actor to
+        fill the container (<constant>CLUTTER_BIN_ALIGNMENT_FILL</constant>)
+        in one or both axes.</para>
+
+        <para>Setting alignment does not have any effect if the container
+        is the same size as all of the actors inside it: in this case,
+        every alignment produces the same layout. But if the container
+        associated with the layout is larger than the actor being aligned,
+        alignment will have an effect; see
+        <link linkend="layouts-stacking-size-requisitioning">this
+        section</link> for more details.</para>
+
+        <para>Changing an actor's alignment after it has been added
+        to a <type>ClutterBinLayout</type> may make the actor "jump"
+        (without animation) to a new position and/or change its size.
+        The exception is changing from some other alignment to
+        <constant>CLUTTER_BIN_ALIGNMENT_FIXED</constant>:
+        in this case, the actor will retain the position and size it
+        had before its alignment was fixed.</para>
+      </section>
+
+      <section id="layouts-stacking-size-requisitioning">
+        <title>Size requisitioning</title>
+
+        <para>A container with a <type>ClutterBinLayout</type> will by
+        default request the width of the widest actor in it, and the
+        height of the tallest. If you add actors smaller than those
+        dimensions, they will be aligned inside the container according
+        to the layout's policies. Here's an example where a
+        <type>ClutterBinLayout</type> requests a size to encompass the
+        tallest (light grey rectangle) and widest (dark grey rectangle)
+        actors inside it, with other actors aligned within
+        those bounds:</para>
+
+        <screenshot>
+          <mediaobject>
+            <imageobject>
+              <imagedata format="PNG"
+                         fileref="images/layouts-stacking-diff-actor-sizes.png" />
+            </imageobject>
+            <alt>
+              <para>Size requisition in a <type>ClutterBinLayout</type></para>
+            </alt>
+          </mediaobject>
+        </screenshot>
+
+        <note>
+          <para>The screenshot also shows the 9 possible combinations
+          of start, center and end alignments on the <code>x</code> and
+          <code>y</code> axes. See
+          <link linkend="layouts-stacking-example-1">the sample
+          code</link> for more details.</para>
+        </note>
+
+        <para>The white space is the stage visible behind the
+        <type>ClutterBox</type> holding the coloured rectangles.
+        Notice that the layout is the width of the widest actor
+        within it and the height of the tallest.</para>
+
+        <para>You can also manually set a size on the container associated
+        with a layout to override the automatically-computed size
+        requisition.</para>
+
+      </section>
+
+      <section>
+        <title>Depth ordering</title>
+
+        <para>Another important consideration is the
+        <emphasis>depth ordering</emphasis> of actors inside a
+        <type>ClutterBinLayout</type>. By default, the depth ordering
+        mirrors the order in which actors are added to the layout: the
+        earlier an actor is added, the lower down in the depth order it
+        is. If this isn't what you want, you can fix the depth ordering using
+        <function>clutter_actor_raise()</function>,
+        <function>clutter_actor_lower()</function> and their relatives.</para>
+      </section>
+
+      <section>
+        <title>Other ways to stack actors</title>
+
+        <para><type>ClutterBinLayout</type> makes it simple to lay out
+        large numbers of actors in a stack and align them to the
+        container; see <link linkend="layouts-stacking-example-2">the
+        example below</link> which shows layering of many actors on
+        top of each other.</para>
+
+        <para>However, if you have a small number of actors and you
+        need some simple alignment, an alternative is to use
+        manual positioning inside a <type>ClutterFixedLayout</type>
+        (or even a <type>ClutterGroup</type>), possibly combined with
+        <type>ClutterConstraints</type> to align actors with each other
+        and bind their widths and heights together. See
+        <link linkend="layouts-introduction-not-using-layout-managers">this
+        section</link> for more details.</para>
+      </section>
+
+    </section>
+
+    <section>
+      <title>Full examples</title>
+
+      <example id="layouts-stacking-example-1">
+        <title><type>ClutterBinLayout</type>, with actors in 9
+        combinations of start, center and end alignment combinations</title>
+        <programlisting>
+<xi:include href="examples/layouts-stacking-diff-sized-actors.c" parse="text">
+  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
+
+      <example id="layouts-stacking-example-2">
+        <title>Layering multiple textures on top of each other
+        inside a <type>ClutterBinLayout</type></title>
+        <programlisting>
+<xi:include href="examples/layouts-stacking.c" parse="text">
+  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
+
+    </section>
+
   </section>
 
 </chapter>