From 1a44b56b7a5b42ff26abde46c5fdea2f8e3858ff Mon Sep 17 00:00:00 2001 From: Elliot Smith Date: Tue, 3 Aug 2010 11:00:19 +0100 Subject: [PATCH] cookbook: Added layouts section and introduction --- doc/cookbook/clutter-cookbook.xml.in | 1 + doc/cookbook/layouts.xml | 281 +++++++++++++++++++++++++++++++++++ 2 files changed, 282 insertions(+) create mode 100644 doc/cookbook/layouts.xml diff --git a/doc/cookbook/clutter-cookbook.xml.in b/doc/cookbook/clutter-cookbook.xml.in index ade1935..3bd7108 100644 --- a/doc/cookbook/clutter-cookbook.xml.in +++ b/doc/cookbook/clutter-cookbook.xml.in @@ -44,6 +44,7 @@ + Contributing to this document diff --git a/doc/cookbook/layouts.xml b/doc/cookbook/layouts.xml new file mode 100644 index 0000000..7389924 --- /dev/null +++ b/doc/cookbook/layouts.xml @@ -0,0 +1,281 @@ + + + + + Layout management + + + who + what they said + + +
+ Introduction + + 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 + ClutterLayoutManager; the parent is usually either a + composite ClutterActor (composed of several + ClutterActors) or a ClutterContainer + (containing child ClutterActors). The + ClutterLayoutManager then manages: + + + + The size requisition + (determination of the desired height and width) of the + parent. + + + The allocation (size and position) + assigned to each composed or child ClutterActor. + + + + The following sections give a brief overview of how layout + management works in Clutter. + +
+ Using layouts + + 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 ClutterBox class with one of the + provided ClutterLayoutManager implementations. + + The pattern for doing this is: + + + + Create an instance of one of the + ClutterLayoutManager implementations (see + the + following section). + + + 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). + + + Create a ClutterBox, setting its layout + manager to the one you just created. + + + Pack actors into the ClutterBox, + setting layout properties (if required) as each is added. + + + Modify layout properties of child actors using + clutter_layout_manager_child_set() + (if required). + + + + Individual recipes in this section give more examples of + how to make use of the different layout manager + implementations. + +
+ +
+ Types of layout manager + + Clutter provides a range of layout managers suitable + for different use cases: + + + + ClutterFixedLayout 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 ClutterConstraints) which + will align actors how you want them. + + + ClutterBinLayout 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 ClutterTexture + with a ClutterText on top of it). + + + ClutterBoxLayout arranges actors in a + single horizontal row or vertical column. This type of layout is + common in UI elements like toolbars and menus. + + + ClutterFlowLayout 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. + + + +
+ +
+ Layout properties + + How actors are sized and positioned inside a container + associated with a layout manager depends on two things: + + + + + Properties which apply to all actors added to the layout + 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. + + + + + Properties for each actor added to the layout + 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. + + + + + 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. + + + + + Alignment + How an actor aligns to the container's axes, e.g. + aligned to the container's left, right, or center. + + + + + Horizontal/vertical orientation + Whether actors are arranged in a horizontal row or + vertical column. + + + + + Homogenous rows and columns + Grid-like layouts (e.g. ClutterFlowLayout) + can be configured to have uniform rows and/or columns, + expanding to fit the largest actor they contain. + + + + + Row height and column width + Grid-like layouts arranged in rows and columns + can be configured with maximum and minimum row height and + column width. + + + + + Row and column spacing + Grid-like layouts enable you to define a space (in pixels) + between rows and columns. + + + + + Expand + Some layouts can be configured to minimize their size request + to fit the actors they contain (expand is FALSE); + or to increase the allocation of actors they contain so + that all available space in the layout is used + (expand is TRUE). 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. + + + + + Fill + This property only has an effect when + expand is on. The fill + setting controls whether actors are resized to fill their + allocation (fill is TRUE); or if the + space around the actor is increased (fill is + FALSE). + + + + + Pack at start/end + This controls whether actors at prepended or appended + to the layout. + + + If the orientation is vertical, prepended + actors are added to the top of the layout and appended + actors to the bottom. + + + If the orientation is horizontal, prepended + actors are added at the left of the layout and appended actors + on the right. + + + + + + +
+ Setting layout properties + + Layout properties can be set in one or more of the following ways + (depending on the type of property and the layout manager): + + + + By setting a default value for the property on the + layout manager (e.g. using + clutter_bin_layout_set_alignment(), + clutter_box_layout_set_expand()). Any + actor added to the layout gets this value for the property, + unless it is overridden for that actor. + + + When adding an actor to a ClutterBox container + using clutter_box_pack(), you can set + properties on the actor which you're adding. + + + When adding an actor to a layout you can use a function + which enables setting properties simultaneously (e.g. + clutter_box_layout_pack(), + clutter_bin_layout_add()). + + + By using + clutter_layout_manager_child_set() on + the child of a layout. + + + +
+ +
+ +
+ + -- 2.7.4