cookbook: Add initial skeleton for box layout recipe
Created recipe and first draft content for recipe about ClutterBoxLayout.
This commit is contained in:
Elliot Smith
Emmanuele Bassi
parent
6c244c0549
commit
77aacd185d
@ -807,4 +807,268 @@ clutter_actor_raise_top (text);
|
||||
|
||||
</section>
|
||||
|
||||
<section id="layouts-box">
|
||||
<title>Arranging actors in a single row or column</title>
|
||||
|
||||
<section>
|
||||
<title>Problem</title>
|
||||
|
||||
<para>You want to layout several actors in a single row
|
||||
or column.</para>
|
||||
|
||||
<para>Example use cases:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Creating an application menu.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Showing message subject lines as a list in an
|
||||
email client.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Solution</title>
|
||||
|
||||
<para>Create a <type>ClutterBox</type> with a
|
||||
<type>ClutterBoxLayout</type> as its layout manager.</para>
|
||||
|
||||
<para>A <type>ClutterBoxLayout</type> can hold a single row or
|
||||
column of <type>ClutterActors</type>, and has configurable spacing,
|
||||
actor alignments, and expand and fill options.</para>
|
||||
|
||||
<informalexample>
|
||||
<programlisting>
|
||||
???
|
||||
</programlisting>
|
||||
</informalexample>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Discussion</title>
|
||||
|
||||
<para><type>ClutterBoxLayout</type> is not a reflowing layout:
|
||||
that is, if the layout's container changes size, the actors inside
|
||||
aren't automatically repositioned to fill the available area.
|
||||
If you want that behaviour, use <type>ClutterFlowLayout</type>
|
||||
instead.</para>
|
||||
|
||||
<para>If you want the container to be resizable, but still want
|
||||
access to the actors inside it if they go outside its clip area,
|
||||
you can provide another way to get to them. For example, you
|
||||
could put the container inside a scrollable area, so the
|
||||
container's actors can be scrolled to if they go out of sight.</para>
|
||||
|
||||
<section>
|
||||
<title>Layout properties</title>
|
||||
|
||||
<para><type>ClutterBoxLayout</type> is very flexible, with
|
||||
several properties which influence the appearance of the
|
||||
layout and its children. As with other layouts, these properties
|
||||
are either applicable to the layout itself, or to individual
|
||||
children of the layout.</para>
|
||||
|
||||
<para>As most of these properties are documented in the API reference,
|
||||
they aren't covered in much detail here. However, below is a brief
|
||||
overview of the properties available, as well as details of properties
|
||||
particular to <type>ClutterBoxLayout</type>.</para>
|
||||
|
||||
<para>The main issue you may face when applying these properties
|
||||
is understanding how they interact. As this is harder to describe
|
||||
than to show, you can run the <link linkend="???">second example</link>
|
||||
below to toggle and tweak the various properties.</para>
|
||||
|
||||
<note>
|
||||
<para>The second example sets child properties (fill, alignment,
|
||||
expand) on all children of the layout when those properties are
|
||||
changed. If you want to see the effect of setting these to
|
||||
different values for <emphasis>each</emphasis> child, you
|
||||
will have to experiment yourself.</para>
|
||||
</note>
|
||||
|
||||
<section>
|
||||
<title><type>ClutterBoxLayout</type> properties</title>
|
||||
|
||||
<para><type>ClutterBoxLayout</type> has the following properties
|
||||
which affect the appearance of all children inside the container.</para>
|
||||
|
||||
<note>
|
||||
<para>Animation properties are covered separately
|
||||
<link linkend="???">later</link>.</para>
|
||||
</note>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title><varname>vertical</varname>; set with
|
||||
<function>clutter_box_layout_set_vertical()</function></title>
|
||||
|
||||
<para>Set to <constant>TRUE</constant> to lay out
|
||||
child actors in a column; if <constant>FALSE</constant>
|
||||
(the default), actors are laid out horizontally.</para>
|
||||
</formalpara>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title><varname>homogeneous</varname>; set with
|
||||
<function>clutter_box_layout_set_homogeneous()</function></title>
|
||||
|
||||
<para>Set to <constant>TRUE</constant> to allocate all
|
||||
child actors the same amount of space in the row or column
|
||||
(depending on the setting for <varname>vertical</varname>).
|
||||
This overrides per-actor <varname>expand</varname> settings
|
||||
and preferred sizes for child actors. The default value for
|
||||
this property is <constant>FALSE</constant>.</para>
|
||||
</formalpara>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title><varname>spacing</varname>; set with
|
||||
<function>clutter_box_layout_set_spacing()</function></title>
|
||||
|
||||
<para>Sets the number of pixels to place between actors
|
||||
in the layout.</para>
|
||||
<para>Note that if you increase spacing too much, actors
|
||||
may go outside the edges of the layout's container (if
|
||||
the container has a fixed size).</para>
|
||||
</formalpara>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<formalpara>
|
||||
<title><varname>pack-start</varname>; set with
|
||||
<function>clutter_box_layout_set_pack_start()</function></title>
|
||||
|
||||
<para>Set <varname>pack-start</varname> to
|
||||
<constant>TRUE</constant> to configure the layout to
|
||||
prepend actors to the row or column; the default is
|
||||
<constant>FALSE</constant>, meaning that actors are
|
||||
appended to the row or column when added.</para>
|
||||
|
||||
<para>Changing this property on a layout which already has
|
||||
actors in it will reverse the order of those actors, as
|
||||
well as changing how new actors are added to the layout.</para>
|
||||
</formalpara>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Child properties</title>
|
||||
|
||||
<para>These properties apply to individual children within
|
||||
the layout's container. Each child can have different values
|
||||
for each of these properties.</para>
|
||||
|
||||
<para>To set properties, you can use
|
||||
<function>clutter_box_layout_pack()</function> or
|
||||
<function>clutter_box_pack()</function> (if using a
|
||||
<type>ClutterBox</type>) while packing actors into the layout.
|
||||
You can also set properties later using
|
||||
<function>clutter_layout_manager_child_set()</function>
|
||||
etc. See the <link linkend="layouts-introduction">layouts
|
||||
introduction</link> for more details.</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><varname>x-fill</varname> and <varname>y-fill</varname>
|
||||
set whether an actor will fill its allocated horizontal
|
||||
or vertical space (respectively) within the layout. Setting
|
||||
these properties only has an effect where an actor is smaller
|
||||
(on the fill axis or axes) than the layout's container.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>expand</varname> sets whether an actor
|
||||
will be expanded inside the layout. If
|
||||
<varname>expand</varname> is <constant>TRUE</constant>
|
||||
and <varname>fill</varname> is <constant>TRUE</constant>
|
||||
for the orientation axis, the actor is resized to fill
|
||||
its whole allocation on that axis; if <varname>expand</varname>
|
||||
is <constant>TRUE</constant> but <varname>fill</varname>
|
||||
is <constant>FALSE</constant>, extra padding is added
|
||||
around the actor to fill the allocation.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><varname>x-align</varname> and <varname>y-align</varname>
|
||||
set how an actor is aligned within its allocation, in
|
||||
cases where it doesn't fill that allocation. In practical
|
||||
terms, these properties come into effect if a child is set
|
||||
to expand but <varname>fill</varname> is set to
|
||||
<constant>FALSE</constant> on the align axis.</para>
|
||||
|
||||
<para>For example, if <varname>expand</varname> is
|
||||
<constant>TRUE</constant> but <varname>x-fill</varname>
|
||||
is <constant>FALSE</constant>, some padding is added
|
||||
around the actor to fill its allocation. In this case,
|
||||
the <varname>x-align</varname> property can be set to
|
||||
align the actor to the left, center or right of the
|
||||
allocation; any whitespace would be redistributed around
|
||||
the actor's new position after alignment.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>These properties are only useful where you have
|
||||
actors of non-uniform sizes and/or a container which is
|
||||
either wider or taller (or both) than one or more of the
|
||||
child actors it contains.</para>
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Animating changes to the layout</title>
|
||||
|
||||
<para>If actors are added to a layout, or if the layout's
|
||||
properties or its children's properties are changed, the
|
||||
appearance of the layout may also change. The
|
||||
<varname>use-animations</varname> property (set with
|
||||
<function>clutter_box_layout_set_use_animations()</function>)
|
||||
sets whether such changes to the layout are animated: if set
|
||||
to <constant>TRUE</constant>, any changes to actor
|
||||
allocations resulting from the changes (movements, resizings)
|
||||
are animated.</para>
|
||||
|
||||
<para>If this property is <constant>FALSE</constant> (the default)
|
||||
changes to other properties or addition of new actors will
|
||||
cause actors to be laid out instantaneously. For example, if
|
||||
a new actor is prepended with animations on, the new actor is
|
||||
added to the layout and the other actors shifted to make room
|
||||
for it; if animations are off, child actors jump to their new
|
||||
positions at the same instant as the new actor is added.</para>
|
||||
|
||||
<para>To change the appearance of the animations, you can use
|
||||
<function>clutter_box_layout_set_easing_mode()</function> and
|
||||
<function>clutter_box_layout_set_duration()</function> (see the
|
||||
<link linkend="animations-introduction">animations
|
||||
introduction</link> for more about easing and duration
|
||||
properties).</para>
|
||||
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Full examples</title>
|
||||
|
||||
<!--example id="layouts-box-example-1">
|
||||
<title>Creating an automatically-resizing overlay for a
|
||||
texture using <type>ClutterBindConstraint</type></title>
|
||||
<programlisting>
|
||||
<xi:include href="examples/layouts-box.c" parse="text">
|
||||
<xi:fallback>a code sample should be here... but isn't</xi:fallback>
|
||||
</xi:include>
|
||||
</programlisting>
|
||||
</example-->
|
||||
|
||||
</section>
|
||||
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user