mirror of
https://github.com/brl/mutter.git
synced 2024-11-30 03:50:47 -05:00
eaed9c22da
Expanded the layout introduction and added a recipe about stacking actors using ClutterBinLayout, with two examples.
591 lines
23 KiB
XML
591 lines
23 KiB
XML
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter id="layouts"
|
|
xmlns:xi="http://www.w3.org/2003/XInclude">
|
|
|
|
<title>Layout management</title>
|
|
|
|
<epigraph>
|
|
<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">
|
|
<title>Introduction</title>
|
|
|
|
<para>Layout management in Clutter controls how an actor and
|
|
children "inside" that actor are sized and positioned. More
|
|
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>ClutterActors</type>) or a <type>ClutterContainer</type>
|
|
(containing child <type>ClutterActors</type>). The
|
|
<type>ClutterLayoutManager</type> then manages:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The <emphasis>size requisition</emphasis>
|
|
(determination of the desired height and width) of the
|
|
parent.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The <emphasis>allocation</emphasis> (size and position)
|
|
assigned to each composed or child ClutterActor.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<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>
|
|
<title>Using layouts</title>
|
|
|
|
<para>Although Clutter provides plenty of flexibility in how you
|
|
can use layout management, the simplest way to get started is to
|
|
use the built-in <type>ClutterBox</type> class with one of the
|
|
provided <type>ClutterLayoutManager</type> implementations.</para>
|
|
|
|
<para>The pattern for doing this is:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Create an instance of one of the
|
|
<type>ClutterLayoutManager</type> implementations (see
|
|
<link linkend="layouts-introduction-manager-types">the
|
|
following section</link>).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Configure the layout manager's default policies
|
|
(e.g. how actors are aligned by default, whether to pack
|
|
actors horizontally or vertically, spacing between actors
|
|
in the layout).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Create a <type>ClutterBox</type>, setting its layout
|
|
manager to the one you just created.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Pack actors into the <type>ClutterBox</type>,
|
|
setting layout properties (if required) as each is added.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Modify layout properties of child actors using
|
|
<function>clutter_layout_manager_child_set()</function>
|
|
(if required).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Individual recipes in this section give more examples of
|
|
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">
|
|
<title>Types of layout manager</title>
|
|
|
|
<para>Clutter provides a range of layout managers suitable
|
|
for different use cases:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<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>ClutterConstraints</type>) which
|
|
will align actors how you want them.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><type>ClutterBinLayout</type> arranges actors in a
|
|
depth-ordered stack on top of each other, aligned to the container.
|
|
This is useful for arranging actors inside composites (e.g.
|
|
creating a button widget from a <type>ClutterTexture</type>
|
|
with a <type>ClutterText</type> on top of it).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><type>ClutterBoxLayout</type> arranges actors in a
|
|
single horizontal row or vertical column. This type of layout is
|
|
common in UI elements like toolbars and menus.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><type>ClutterFlowLayout</type> arranges actors
|
|
in reflowing columns and rows. If the container's allocation
|
|
changes, the child actors are rearranged to fit inside its
|
|
new allocation. This can be useful for arranging actors
|
|
where you're not sure how many there might be; or where
|
|
new ones are going to be added into the UI, perhaps displacing
|
|
others. An example might be a photo viewer or an
|
|
RSS feed display.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
</section>
|
|
|
|
<section id="layouts-introduction-layout-properties">
|
|
<title>Layout properties</title>
|
|
|
|
<para>How actors are sized and positioned inside a container
|
|
associated with a layout manager depends on two things:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Properties which apply to all actors added to the layout</title>
|
|
<para>There will be one setting at the layout level which can't
|
|
be overridden per actor. This includes properties like spacing
|
|
between rows and columns, whether the layout is homogenous
|
|
(each actor gets the same allocation), etc.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Properties for each actor added to the layout</title>
|
|
<para>These are properties of the relationship between the
|
|
layout, the container associated with the layout, and the
|
|
children of the container. Each layout/container/actor
|
|
combination can have different settings for each of these
|
|
properties.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>Each layout manager implementation supports a subset of the
|
|
following layout properties; different managers may have different
|
|
names or functions for setting them, but the functionality remains
|
|
the same. Individual recipes give more details about which
|
|
properties can be set for each layout manager implementation.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<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. For some
|
|
layouts (like <type>ClutterBinLayout</type>) alignment
|
|
is also used to set expand and fill properties.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Horizontal/vertical orientation</title>
|
|
<para>Whether actors are arranged in a horizontal row or
|
|
vertical column.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Homogenous rows and columns</title>
|
|
<para>Grid-like layouts (e.g. <type>ClutterFlowLayout</type>)
|
|
can be configured to have uniform rows and/or columns,
|
|
expanding to fit the largest actor they contain.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Row height and column width</title>
|
|
<para>Grid-like layouts arranged in rows and columns
|
|
can be configured with maximum and minimum row height and
|
|
column width.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Row and column spacing</title>
|
|
<para>Grid-like layouts enable you to define a space (in pixels)
|
|
between rows and columns.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Expand</title>
|
|
<para>Some layouts can be configured to minimize their size request
|
|
to fit the actors they contain (<emphasis>expand is FALSE</emphasis>);
|
|
or to increase the allocation of actors they contain so
|
|
that all available space in the layout is used
|
|
(<emphasis>expand is TRUE</emphasis>). In the latter case, you'd
|
|
also need to set a size for the container associated with
|
|
the layout, otherwise the container will just fit itself to the
|
|
actors inside it.</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Fill</title>
|
|
<para>This property only has an effect when
|
|
<emphasis>expand</emphasis> is on. The <emphasis>fill</emphasis>
|
|
setting controls whether actors are resized to fill their
|
|
allocation (<emphasis>fill is TRUE</emphasis>); or if the
|
|
space around the actor is increased (<emphasis>fill is
|
|
FALSE</emphasis>).</para>
|
|
</formalpara>
|
|
</listitem>
|
|
<listitem>
|
|
<formalpara>
|
|
<title>Pack at start/end</title>
|
|
<para>This controls whether actors at prepended or appended
|
|
to the layout.</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the orientation is vertical, prepended
|
|
actors are added to the top of the layout and appended
|
|
actors to the bottom.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If the orientation is horizontal, prepended
|
|
actors are added at the left of the layout and appended actors
|
|
on the right.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</formalpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section>
|
|
<title>Setting layout properties</title>
|
|
|
|
<para>Layout properties can be set in one or more of the following ways
|
|
(depending on the type of property and the layout manager):</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>By setting a default value for the property on the
|
|
layout manager (e.g. using
|
|
<function>clutter_bin_layout_set_alignment()</function>,
|
|
<function>clutter_box_layout_set_expand()</function>). Any
|
|
actor added to the layout gets this value for the property,
|
|
unless it is overridden for that actor.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>When adding an actor to a <type>ClutterBox</type> container
|
|
using <function>clutter_box_pack()</function>, you can set
|
|
properties on the actor which you're adding.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>When adding an actor to a layout you can use a function
|
|
which enables setting properties simultaneously (e.g.
|
|
<function>clutter_box_layout_pack()</function>,
|
|
<function>clutter_bin_layout_add()</function>).</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>By using
|
|
<function>clutter_layout_manager_child_set()</function> on
|
|
the child of a layout.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</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>
|
|
|
|
</chapter>
|