From 77aacd185dcdd1673e1c3fb058d93a5803febe6a Mon Sep 17 00:00:00 2001 From: Elliot Smith Date: Tue, 14 Dec 2010 18:08:28 +0000 Subject: [PATCH] cookbook: Add initial skeleton for box layout recipe Created recipe and first draft content for recipe about ClutterBoxLayout. --- doc/cookbook/layouts.xml | 264 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) diff --git a/doc/cookbook/layouts.xml b/doc/cookbook/layouts.xml index b96877fb3..f583a200d 100644 --- a/doc/cookbook/layouts.xml +++ b/doc/cookbook/layouts.xml @@ -807,4 +807,268 @@ clutter_actor_raise_top (text); +
+ Arranging actors in a single row or column + +
+ Problem + + You want to layout several actors in a single row + or column. + + Example use cases: + + + + Creating an application menu. + + + Showing message subject lines as a list in an + email client. + + +
+ +
+ Solution + + Create a ClutterBox with a + ClutterBoxLayout as its layout manager. + + A ClutterBoxLayout can hold a single row or + column of ClutterActors, and has configurable spacing, + actor alignments, and expand and fill options. + + + +??? + + +
+ +
+ Discussion + + ClutterBoxLayout 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 ClutterFlowLayout + instead. + + 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. + +
+ Layout properties + + ClutterBoxLayout 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. + + 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 ClutterBoxLayout. + + 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 second example + below to toggle and tweak the various properties. + + + 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 each child, you + will have to experiment yourself. + + +
+ <type>ClutterBoxLayout</type> properties + + ClutterBoxLayout has the following properties + which affect the appearance of all children inside the container. + + + Animation properties are covered separately + later. + + + + + + <varname>vertical</varname>; set with + <function>clutter_box_layout_set_vertical()</function> + + Set to TRUE to lay out + child actors in a column; if FALSE + (the default), actors are laid out horizontally. + + + + + + <varname>homogeneous</varname>; set with + <function>clutter_box_layout_set_homogeneous()</function> + + Set to TRUE to allocate all + child actors the same amount of space in the row or column + (depending on the setting for vertical). + This overrides per-actor expand settings + and preferred sizes for child actors. The default value for + this property is FALSE. + + + + + + <varname>spacing</varname>; set with + <function>clutter_box_layout_set_spacing()</function> + + Sets the number of pixels to place between actors + in the layout. + 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). + + + + + + <varname>pack-start</varname>; set with + <function>clutter_box_layout_set_pack_start()</function> + + Set pack-start to + TRUE to configure the layout to + prepend actors to the row or column; the default is + FALSE, meaning that actors are + appended to the row or column when added. + + 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. + + + + +
+ +
+ Child properties + + These properties apply to individual children within + the layout's container. Each child can have different values + for each of these properties. + + To set properties, you can use + clutter_box_layout_pack() or + clutter_box_pack() (if using a + ClutterBox) while packing actors into the layout. + You can also set properties later using + clutter_layout_manager_child_set() + etc. See the layouts + introduction for more details. + + + + x-fill and y-fill + 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. + + + + expand sets whether an actor + will be expanded inside the layout. If + expand is TRUE + and fill is TRUE + for the orientation axis, the actor is resized to fill + its whole allocation on that axis; if expand + is TRUE but fill + is FALSE, extra padding is added + around the actor to fill the allocation. + + + + x-align and y-align + 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 fill is set to + FALSE on the align axis. + + For example, if expand is + TRUE but x-fill + is FALSE, some padding is added + around the actor to fill its allocation. In this case, + the x-align 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. + + + + 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. + +
+ +
+ +
+ Animating changes to the layout + + 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 + use-animations property (set with + clutter_box_layout_set_use_animations()) + sets whether such changes to the layout are animated: if set + to TRUE, any changes to actor + allocations resulting from the changes (movements, resizings) + are animated. + + If this property is FALSE (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. + + To change the appearance of the animations, you can use + clutter_box_layout_set_easing_mode() and + clutter_box_layout_set_duration() (see the + animations + introduction for more about easing and duration + properties). + +
+
+ +
+ Full examples + + + +
+ +
+