Table of Contents
If we do not lay out ourselves in the service of mankind, whom should we serve?
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.
Note
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.
The sheet of paper is analogous to the container or composite actor; the squares are analogous to the child ClutterActors; and the person giving you instructions is analogous to the layout manager.
The following sections give an overview of how layout management works in Clutter.
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 ClutterActor 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 ClutterActor, setting its layout manager to the one you just created.
Pack actors into the ClutterActor, 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.
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.
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. For some layouts (like ClutterBinLayout) alignment is also used to set expand and fill properties.
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.
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.
It is perfectly possible to arrange ClutterActors without using layout managers; however, you may have to do more of your own calculations about actor sizes and positions.
There are two (not mutually-exclusive) approaches you can take to do this, described below.
This basically means using the ClutterActor bounding box mechanism (see the ClutterActor 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).
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.
Constraints provide mechanisms for:
Aligning actors with each other (ClutterAlignConstraint). For example, you can align the top, bottom or center of one actor with the top, bottom or center of another (on the
yaxis). Similarly, you can align one actor to another on thexaxis.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
xcoordinate. In both these cases and others, you can specify that the properties should be the same, or the same +/- some offset.
Note
ClutterConstraints 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.