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

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

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│
          │   ││ ││  │
          └───┘└─┘└──┘

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 width keeps 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 with at_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.

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.

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 stays 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)))
;
}

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

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
;
}

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
;
}