cookbook: Added layout introduction and "stacking actors" recipe
Expanded the layout introduction and added a recipe about stacking actors using ClutterBinLayout, with two examples.
This commit is contained in:
parent
309dd1f50e
commit
eaed9c22da
@ -37,6 +37,7 @@ IMAGE_FILES = \
|
|||||||
images/actors-opacity-container-affects-opacity.png \
|
images/actors-opacity-container-affects-opacity.png \
|
||||||
images/text-shadow.png \
|
images/text-shadow.png \
|
||||||
images/textures-sub-texture.png \
|
images/textures-sub-texture.png \
|
||||||
|
images/layouts-stacking-diff-actor-sizes.png \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
VIDEO_FILES = \
|
VIDEO_FILES = \
|
||||||
videos/animations-fading-out.ogv \
|
videos/animations-fading-out.ogv \
|
||||||
|
2
doc/cookbook/examples/.gitignore
vendored
2
doc/cookbook/examples/.gitignore
vendored
@ -3,3 +3,5 @@
|
|||||||
/textures-reflection
|
/textures-reflection
|
||||||
/textures-split-go
|
/textures-split-go
|
||||||
/textures-sub-texture
|
/textures-sub-texture
|
||||||
|
/layouts-stacking
|
||||||
|
/layouts-stacking-diff-sized-actors
|
||||||
|
@ -8,6 +8,8 @@ noinst_PROGRAMS = \
|
|||||||
textures-reflection \
|
textures-reflection \
|
||||||
textures-split-go \
|
textures-split-go \
|
||||||
textures-sub-texture \
|
textures-sub-texture \
|
||||||
|
layouts-stacking \
|
||||||
|
layouts-stacking-diff-sized-actors \
|
||||||
$(NULL)
|
$(NULL)
|
||||||
|
|
||||||
INCLUDES = \
|
INCLUDES = \
|
||||||
@ -29,8 +31,10 @@ AM_CFLAGS = \
|
|||||||
|
|
||||||
AM_LDFLAGS = $(CLUTTER_LIBS)
|
AM_LDFLAGS = $(CLUTTER_LIBS)
|
||||||
|
|
||||||
animations_rotating_SOURCES = animations-rotating.c
|
animations_rotating_SOURCES = animations-rotating.c
|
||||||
text_shadow_SOURCES = text-shadow.c
|
text_shadow_SOURCES = text-shadow.c
|
||||||
textures_reflection_SOURCES = textures-reflection.c
|
textures_reflection_SOURCES = textures-reflection.c
|
||||||
textures_split_go_SOURCES = textures-split-go.c
|
textures_split_go_SOURCES = textures-split-go.c
|
||||||
textures_sub_texture_SOURCES = textures-sub-texture.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
|
||||||
|
78
doc/cookbook/examples/layouts-stacking-diff-sized-actors.c
Normal file
78
doc/cookbook/examples/layouts-stacking-diff-sized-actors.c
Normal file
@ -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;
|
||||||
|
}
|
80
doc/cookbook/examples/layouts-stacking.c
Normal file
80
doc/cookbook/examples/layouts-stacking.c
Normal file
@ -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;
|
||||||
|
}
|
BIN
doc/cookbook/images/layouts-stacking-diff-actor-sizes.png
Normal file
BIN
doc/cookbook/images/layouts-stacking-diff-actor-sizes.png
Normal file
Binary file not shown.
After Width: | Height: | Size: 1.5 KiB |
@ -7,8 +7,10 @@
|
|||||||
<title>Layout management</title>
|
<title>Layout management</title>
|
||||||
|
|
||||||
<epigraph>
|
<epigraph>
|
||||||
<attribution>who</attribution>
|
<attribution>Abigail Adams, wife of John Adams, in a letter to John
|
||||||
<para>what they said</para>
|
Thaxter (1778-09-29)</attribution>
|
||||||
|
<para>If we do not lay out ourselves in the service of mankind,
|
||||||
|
whom should we serve?</para>
|
||||||
</epigraph>
|
</epigraph>
|
||||||
|
|
||||||
<section id="layouts-introduction">
|
<section id="layouts-introduction">
|
||||||
@ -19,8 +21,8 @@
|
|||||||
specifically, layouts are managed by associating a parent with a
|
specifically, layouts are managed by associating a parent with a
|
||||||
<type>ClutterLayoutManager</type>; the parent is usually either a
|
<type>ClutterLayoutManager</type>; the parent is usually either a
|
||||||
composite <type>ClutterActor</type> (composed of several
|
composite <type>ClutterActor</type> (composed of several
|
||||||
<type>ClutterActor</type>s) or a <type>ClutterContainer</type>
|
<type>ClutterActors</type>) or a <type>ClutterContainer</type>
|
||||||
(containing child <type>ClutterActor</type>s). The
|
(containing child <type>ClutterActors</type>). The
|
||||||
<type>ClutterLayoutManager</type> then manages:</para>
|
<type>ClutterLayoutManager</type> then manages:</para>
|
||||||
|
|
||||||
<orderedlist>
|
<orderedlist>
|
||||||
@ -35,7 +37,19 @@
|
|||||||
</listitem>
|
</listitem>
|
||||||
</orderedlist>
|
</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>
|
management works in Clutter.</para>
|
||||||
|
|
||||||
<section>
|
<section>
|
||||||
@ -80,6 +94,13 @@
|
|||||||
how to make use of the different layout manager
|
how to make use of the different layout manager
|
||||||
implementations.</para>
|
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>
|
||||||
|
|
||||||
<section id="layouts-introduction-manager-types">
|
<section id="layouts-introduction-manager-types">
|
||||||
@ -93,7 +114,7 @@
|
|||||||
<para><type>ClutterFixedLayout</type> arranges actors
|
<para><type>ClutterFixedLayout</type> arranges actors
|
||||||
at fixed positions on the stage. No alignment options are
|
at fixed positions on the stage. No alignment options are
|
||||||
available, so you have to manually compute and manage the
|
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>
|
will align actors how you want them.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
@ -122,7 +143,7 @@
|
|||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section>
|
<section id="layouts-introduction-layout-properties">
|
||||||
<title>Layout properties</title>
|
<title>Layout properties</title>
|
||||||
|
|
||||||
<para>How actors are sized and positioned inside a container
|
<para>How actors are sized and positioned inside a container
|
||||||
@ -161,7 +182,9 @@
|
|||||||
<formalpara>
|
<formalpara>
|
||||||
<title>Alignment</title>
|
<title>Alignment</title>
|
||||||
<para>How an actor aligns to the container's axes, e.g.
|
<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>
|
</formalpara>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
@ -276,6 +299,292 @@
|
|||||||
|
|
||||||
</section>
|
</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>
|
</section>
|
||||||
|
|
||||||
</chapter>
|
</chapter>
|
||||||
|
Loading…
Reference in New Issue
Block a user