Layout
Guido uses a flexbox-style layout system for arranging widgets. The Flex layout handles rows and columns with spacing and alignment options.
Basic Layout
Row (Horizontal)
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(Flex::row())
.children([
text("Left"),
text("Center"),
text("Right"),
])
;
}
Column (Vertical)
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(Flex::column())
.children([
text("Top"),
text("Middle"),
text("Bottom"),
])
;
}
Spacing
Add space between children:
// not compiled: `[...]` stands in for the children; this block is about
// the layout above them.
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(Flex::row().spacing(8.0))
.children([...])
;
}
Main Axis Alignment
Control distribution along the layout direction:
extern crate guido;
use guido::prelude::*;
fn main() {
Flex::row().main_alignment(MainAlignment::Center)
;
}
Options
| Alignment | Description |
|---|---|
Start | Pack at the beginning |
Center | Center in available space |
End | Pack at the end |
SpaceBetween | Equal space between, none at edges |
SpaceAround | Equal space around each item |
SpaceEvenly | Equal space including edges |
The three spacing alignments share out the space the flex is given. Along a
scrolled axis there is no limit and so nothing to share: the children sit
together as with Start, and the content is as long as they are.
A child that is hidden, or half a pixel or less along the flex’s direction,
keeps no space around it. When no child keeps space, SpaceAround and
SpaceEvenly centre what they hold, and SpaceBetween places what it
holds at the start.
Visual Examples
Start: [A][B][C]
Center: [A][B][C]
End: [A][B][C]
SpaceBetween: [A] [B] [C]
SpaceAround: [A] [B] [C]
SpaceEvenly: [A] [B] [C]
Cross Axis Alignment
Control alignment perpendicular to the layout direction:
extern crate guido;
use guido::prelude::*;
fn main() {
Flex::row().cross_alignment(CrossAlignment::Center)
;
}
Options
| Alignment | Description |
|---|---|
Start | Align to start of cross axis |
Center | Center on cross axis |
End | Align to end of cross axis |
Stretch | Stretch to fill cross axis |
Baseline | Line children up on the baseline of their text |
Baseline
Text of different sizes in a row does not read as one line when the tops are
aligned — a 24px label and a 12px one float at unrelated heights. Baseline
puts them on the line they are written on:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(Flex::row().spacing(8.0).cross_alignment(CrossAlignment::Baseline))
.children([
container().child(text("28").font_size(24.0)),
container().child(text("°C").font_size(12.0)),
])
;
}
A box reports no baseline of its own, so it is aligned by its bottom edge,
which is what CSS does with it. A container takes the baseline of its
content, so wrapping a text for styling does not lose the alignment. The row
is deep enough for what the alignment moves down: a label pushed down beside
a tall icon keeps its descenders inside the row. In a column there is no
shared line to sit on, and Baseline behaves as Start.
Visual Example (Row)
Start: ┌───┐┌─┐┌──┐
│ A ││B││ C│
└───┘│ │└──┘
└─┘
Center: ┌─┐
┌───┐│B│┌──┐
│ A │└─┘│ C│
└───┘ └──┘
End: ┌─┐
│B│
┌───┐└─┘┌──┐
│ A │ │ C│
└───┘ └──┘
Stretch: ┌───┐┌─┐┌──┐
│ ││ ││ │
│ A ││B││ C│
│ ││ ││ │
└───┘└─┘└──┘
One Child Aligning Itself
A child can say where it sits across the row with .align_self(..), the way
CSS’s align-self overrides align-items. A row reads the vertical half of
the alignment and a column the horizontal half; along the axis the child
stays where the row puts it. A child that aligns itself keeps its own size
across, so in a stretching row it is not stretched, and in a Baseline row
it sits where its alignment says rather than on the shared line.
extern crate guido;
use guido::prelude::*;
fn avatar() -> Container { container() }
fn main() {
container()
.height(40.0)
.layout(Flex::row().spacing(8.0))
// Stretched to the row's 40
.child(avatar())
// 12 tall, centred in the 40
.child(
container()
.width(12.0)
.height(12.0)
.corners(6.0)
.background(Color::RED)
.align_self(Alignment::CENTER),
)
;
}
Centring
center() centres the children on both axes. It is shorthand for
main_alignment(MainAlignment::Center) together with
cross_alignment(CrossAlignment::Center), and composes with the rest:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(Flex::column().spacing(4.0).center())
.children([text("Locked"), text("Type your password")])
;
}
Complete Example
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.layout(
Flex::row()
.spacing(16.0)
.main_alignment(MainAlignment::SpaceBetween)
.cross_alignment(CrossAlignment::Center)
)
.padding(20.0)
.children([
container().child(text("Left").font_size(24.0)),
container()
.layout(Flex::column().spacing(4.0))
.children([
text("Center"),
text("Items"),
]),
container().child(text("Right").font_size(24.0)),
])
;
}
Nested Layouts
Combine rows and columns for complex layouts:
extern crate guido;
use guido::prelude::*;
fn main_content() -> Container { container() }
fn sidebar() -> Container { container() }
fn main() {
container()
.layout(Flex::column().spacing(16.0))
.children([
// Header row
container()
.layout(Flex::row().main_alignment(MainAlignment::SpaceBetween))
.children([
text("Logo"),
text("Menu"),
]),
// Content row
container()
.layout(Flex::row().spacing(16.0))
.children([
sidebar(),
main_content(),
]),
// Footer row
container()
.layout(Flex::row().main_alignment(MainAlignment::Center))
.child(text("Footer")),
])
;
}
Size Constraints
Control how children size within layouts:
Fixed Size
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.width(200.0)
.height(100.0)
;
}
Minimum/Maximum
extern crate guido;
use guido::prelude::*;
fn main() {
container().width(at_least(100.0).at_most(300.0))
;
}
At Least
Request at least a certain size:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.width(at_least(200.0)) // At least 200px, can grow
;
}
A minimum is a floor, never a cap, as CSS min-width is: content wider than
200 makes the container wider. A child that takes everything it is offered —
a fill() child, or a text input — takes everything the container is offered
too, so a field meant to be a set width says so with an exact length, or
bounds it with at_least(200.0).at_most(400.0).
Fill Available Space
Make a container expand to fill all available space:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.height(fill()) // Fills available height
.width(fill()) // Fills available width
;
}
This is particularly useful for root containers that should fill their surface, or for creating layouts where children are centered within the full available space:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.height(fill())
.layout(Flex::row().center())
.child(text("Centered in available space"))
;
}
Along a scrolled axis there is no end to fill to, so fill() there is the
container’s content size. A scroller that should give it the visible area says
so with Scroll::vertical().fill_viewport(true) — see the Container chapter.
Natural Size
Every other length is cut to what the parent offers: .width(240.0) in a
parent 100 wide is 100 wide, and its content is laid out in 100. natural()
is the one that is not. The content is measured with no maximum on that axis
— a label neither wraps nor ellipsizes — and the container is that size
whatever its parent is, running past the parent’s edge. It is cut off there
only if the parent clips, with Overflow::Hidden; otherwise it paints where it
runs to. It is CSS’s max-content, SwiftUI’s fixedSize.
That is what a shape that changes size around its content wants. An island that springs from one view’s width to the next would re-wrap its label at every frame of the spring; with the content at its natural size, the clipped island uncovers and covers it instead:
extern crate guido;
use guido::prelude::*;
fn main() {
let expanded = create_signal(false);
container()
.width((move || if expanded.get() { 320.0 } else { 120.0 }).transition(SpringConfig::SNAPPY))
.height(40.0)
.corners(20.0)
.overflow(Overflow::Hidden)
.layout(ZStack::new().align(Alignment::CENTER))
.child(
container()
.width(natural())
.layout(Flex::row().spacing(8.0))
.child(text("Now playing"))
.child(text("A song with a long title")),
)
;
}
A clipping parent asks nothing of its content’s size, so the island can be
narrower than what it holds without a layout of its own. The length’s own
bounds still apply — natural().at_most(300.0) is the content’s size up to
300 — and in a row too short for its children a natural child is held at its
size, as an exact one is.
Children That Do Not Fit
When a row’s children are wider than the row, the children that can be
narrower give the room up, in proportion to their widths — CSS’s
flex-shrink. None goes below its minimum:
- a container with an exact
widthkeeps it, however deep it sits — an icon inside a padded button is not squashed by a long title beside the button - a container with a
natural()width keeps the width of what it holds - a text that ellipsizes can go down to the
…, one that wraps to its widest word, and one that does neither keeps its whole width - a container that clips (
Overflow::Hidden) or scrolls can go down to nothing, or to the minimum it declares withat_least; any other container goes no lower than what it holds, plus its padding
A child held at its minimum leaves the rest of the overflow to the others. When even the minimums do not fit, the row runs past its end, as it does when nothing in it can shrink. A row that fits is laid out at its children’s natural sizes, exactly as before. Columns follow the same rule along their height:
extern crate guido;
use guido::prelude::*;
fn header() -> Container { container().height(30.0) }
fn rows() -> Container { container() }
fn main() {
// The list takes what the header leaves, rather than the column's whole height.
container()
.height(300.0)
.layout(Flex::column())
.child(header())
.child(container().scroll(Scroll::vertical()).child(rows()))
;
}
fill() children are not part of this: they take what is left once the others
are laid out, and nothing is left when the others overflow.
Wrapping Onto New Lines
A row that runs out of room can move the children that do not fit to a new
line instead of squeezing them, as CSS flex-wrap: wrap does — what a row of
chips or tags needs when how many fit depends on their labels, the font and
the width of the panel:
extern crate guido;
use guido::prelude::*;
fn chip(label: &'static str) -> Text { text(label) }
fn main() {
container()
.width(360.0)
.layout(Flex::row().spacing(4.0).wrap(true).line_spacing(8.0))
.children(["Preset", "Seed", "Wallpaper", "Custom"].map(chip))
;
}
Each line is laid out as a row that does not wrap: a fill() child takes what
its own line leaves, the main alignment places each line on its own, and the
cross alignment works within a line, which is as tall as its tallest child.
A row with no width of its own is as wide as its longest line — or as wide as
it can be, when a line holds a fill() child or uses a spacing alignment, as
for a row that does not wrap. Lines stack from the top, line_spacing apart — the spacing between
children, unless set. A child wider than the whole row has a line to itself,
and gives room up there as described above. A column wraps the same way, into
new columns.
A scrolled row has no end to wrap at, and stays one line. wrap takes a
signal, so a row can start or stop wrapping while it is shown.
Layout Without Explicit Flex
Containers without .layout() use Flex::column():
extern crate guido;
use guido::prelude::*;
fn main() {
// Same as .layout(Flex::column())
container()
.children([
text("first"),
text("second"),
])
;
}
Stacking Children (ZStack)
ZStack places every child at the same position, stacked along the Z axis —
later children paint on top, and take the pointer first. A layer that draws
where the pointer is — a fill, a border, a blur — or listens there covers what
is beneath it, even a translucent scrim; one that only lays out its content
lets the pointer through:
extern crate guido;
use guido::prelude::*;
fn main() {
fn background() -> Container { container() }
fn content() -> Container { container() }
container()
.layout(ZStack::new())
.child(background())
.child(content()) // drawn on top
;
}
Leaders and Followers
The stack takes the size of its largest child, but a child that declares
fill() on an axis follows the stack instead of leading it: it never
contributes to that axis and is laid out against the size the other children
established.
That is how a decoration is sized to its sibling without measuring anything:
extern crate guido;
use guido::prelude::*;
fn card_content() -> Container { container() }
fn main() {
container()
.layout(ZStack::new())
// Follower: exactly as wide and tall as the card below it
.child(
container()
.width(fill())
.height(fill())
.background(Color::rgb(0.2, 0.2, 0.3))
)
// Leader: the stack is as big as this card
.child(card_content())
;
}
Without this rule the background would expand to all the available space, and sizing it to its sibling would need a WidgetRef round-trip — one frame behind, and zero on the first frame.
A hidden child leads nothing, just as it takes no space in a flex: while an overlay
beside a fill() background is hidden, the stack is sized as if it were not
there.
A child on its way out — removed from a .child(move || ..), a
.children(move || ..) or a keyed(..) list and playing the exit it declared
with exiting_to — does not hold the stack open either: it leads only an axis
that nothing staying leads. A shape that sizes to its content cross-fades
between two views and starts moving toward the new one’s size at once, rather
than when the old one has finished fading. The leaving view keeps its own size,
its place by the stack’s alignment and its paint — cut off where the shape
clips — and a leaving fill() background shrinks with the stack. With nothing
staying, the leaving view is all there is to size by, so a view removed with
nothing in its place fades out where it was.
The two axes are decided independently, which is what makes the status-bar
case work: a child with only .height(fill()) fills the bar height and still
leads the width.
extern crate guido;
use guido::prelude::*;
fn now_playing() -> Container { container() }
fn visualizer() -> Container { container() }
fn main() {
container()
.height(fill())
.layout(ZStack::new())
// Follows both axes
.child(container().width(fill()).height(fill()).child(visualizer()))
// Fills the bar height, leads the width
.child(container().height(fill()).child(now_playing()))
;
}
When every child fills an axis there is no size to follow, and the stack takes all the space it was offered on that axis — or, along a scrolled axis, where there is no end to the space, the size of its largest child.
Positioning Inside the Stack
Every child is placed by an Alignment. The stack gives one to all of its
children with ZStack::new().align(..), and a child can declare its own with
.align_self(..), the way CSS’s align-self overrides align-items. The
stack’s is the top start until it says otherwise, and a child that says
nothing takes the stack’s — so a stack nobody aligns puts every child at its
origin.
extern crate guido;
use guido::prelude::*;
fn icon_widget() -> Container { container() }
fn main() {
container()
.layout(ZStack::new().align(Alignment::CENTER))
.child(icon_widget())
// Centred over the icon, as the stack says
.child(text("3"))
// Alert dot on the icon's top-right corner, as it says itself
.child(
container()
.width(4)
.height(4)
.corners(2)
.background(Color::RED)
.align_self(Alignment::TOP_END)
)
;
}
There are nine: TOP_START, TOP_CENTER, TOP_END, CENTER_START,
CENTER, CENTER_END, BOTTOM_START, BOTTOM_CENTER and BOTTOM_END.
Start is the left and the top.
Each names a point, and the child is placed so that the point on the stack
and the same point on the child meet. .to(..) names a different point on
the child, which is how a child sits against the outside of an edge rather
than inside it, as SwiftUI’s alignment guides do:
extern crate guido;
use guido::prelude::*;
fn card() -> Container { container().width(60.0).height(60.0) }
fn main() {
container()
.layout(ZStack::new())
.child(card())
// The badge's centre on the card's top end corner, half outside it
.child(
container()
.width(16)
.height(16)
.corners(8)
.background(Color::RED)
.align_self(Alignment::TOP_END.to(Alignment::CENTER))
)
;
}
BOTTOM_START.to(TOP_START) hangs a child under the stack with their start
edges together, TOP_END.to(BOTTOM_END) stands it above with their end edges
together. It works wherever an alignment does: across a row or a column too,
where CENTER.to(TOP_CENTER) puts a child’s top on the row’s centre line.
An alignment places a child in the room the stack has left over. Every
leader is offered up to the stack’s size and held to none of it, as Flutter’s
Stack does by default, so even in a stack with an exact size a child that
sizes to its content keeps that size, and the alignment shares out the rest. A
follower that fills the stack on an axis has none there, and a plain alignment
leaves it put: a
background behind a centred label is still exactly the stack’s size. A child
larger than the stack is shared out the same way and overhangs instead —
CENTER by the same amount on both sides. A child is only larger than the
stack when it is at its natural size, since every other
length is cut to what the stack offers:
extern crate guido;
use guido::prelude::*;
fn main() {
container()
.width(100.0)
.overflow(Overflow::Hidden)
.layout(ZStack::new().align(Alignment::CENTER))
// 160 wide in a stack of 100: 30 past each side, and cut there
.child(container().width(natural()).child(container().width(160.0).height(20.0)))
;
}
Taking a Child Out of Flow
Sometimes a stack has to stay the size of one child while another comes out
of it, wider: an island with a panel that opens out of it, which must not
push the island’s neighbours away. .out_of_flow(true) takes a child out of
its parent’s flow, as CSS’s position: absolute does:
extern crate guido;
use guido::prelude::*;
fn island() -> Container { container().width(100.0).height(30.0) }
fn panel() -> Container { container().width(300.0).height(200.0) }
fn main() {
container()
.layout(ZStack::new().align(Alignment::TOP_CENTER))
// Leads: the stack is the island's size
.child(island())
// Its own size, hung under the island and centred on it
.child(
panel()
.out_of_flow(true)
.align_self(Alignment::BOTTOM_CENTER.to(Alignment::TOP_CENTER)),
)
;
}
A child out of flow is laid out, placed, drawn and answers clicks like any
other, including where it overflows its parent, but it takes no part in the
parent’s size. It is offered what the parent was offered, so a fixed width
wider than the parent keeps its width; on an axis it fill()s it takes the
parent’s size. It is placed as if it were the only child, by its own
align_self or by the parent’s alignment, and it is cut only if the parent
clips. That is worked out on every layout from the sizes as they are then, so
the panel above stays under the island while the island grows, with no
translate to keep up to date; a translate on the panel is left to carry
its own motion, a gap or a slide out.
It means the same in any layout, because the container takes the child out
before the layout sees it. In a row or a column it takes no room and no gap,
and sits where the row would put it alone — SpaceBetween at the start,
SpaceAround and SpaceEvenly in the middle, Stretch and Baseline at
the start. In a layout you write it
sits at the top start, unless the layout’s lone_child says otherwise.
API Reference
Flex Builder
Flex::row() -> Flex; // Horizontal layout
Flex::column() -> Flex // Vertical layout
.spacing(f32) -> Flex // Space between children
.main_alignment(MainAlignment) -> Flex
.cross_alignment(CrossAlignment) -> Flex
.wrap(bool) -> Flex // Move what does not fit to a new line
.line_spacing(f32) -> Flex // Space between lines; defaults to spacing
MainAlignment
extern crate guido;
use guido::prelude::*;
fn main() {
MainAlignment::Start;
MainAlignment::Center;
MainAlignment::End;
MainAlignment::SpaceBetween;
MainAlignment::SpaceAround;
MainAlignment::SpaceEvenly
;
}
CrossAlignment
extern crate guido;
use guido::prelude::*;
fn main() {
CrossAlignment::Start;
CrossAlignment::Center;
CrossAlignment::End;
CrossAlignment::Stretch
;
}
Alignment
extern crate guido;
use guido::prelude::*;
fn main() {
Alignment::TOP_START;
Alignment::TOP_CENTER;
Alignment::TOP_END;
Alignment::CENTER_START;
Alignment::CENTER;
Alignment::CENTER_END;
Alignment::BOTTOM_START;
Alignment::BOTTOM_CENTER;
Alignment::BOTTOM_END;
// The stack's point, then the child's that meets it
Alignment::BOTTOM_CENTER.to(Alignment::TOP_CENTER)
;
}
ZStack
// not compiled: a signature listing — these declarations have no bodies.
extern crate guido;
use guido::prelude::*;
fn main() {
ZStack::new() -> ZStack // Children stacked, at the top start
.align(Alignment) -> ZStack // Where every child sits
;
}