Layout
The widgets that arrange other widgets belong to GTK, and libadwaita only styles them — the frame’s 1px border is the single rule upstream writes for any of the containers below. This page grows with the ones the gallery covers: the separator, the frame, the aspect frame, the centre box, the grid, the fixed, the overlay, the revealer, the paned and the expander.
Separator
Section titled “Separator”A one-pixel rule between two groups of widgets. Its orientation is the one a
box has: a horizontal separator runs across, a vertical one runs down, so put it
in a box that runs the other way. Add the .spacer style class when you want the
distance without the line, a 12px gap that draws nothing.
A one-pixel border with a label embedded in its top edge. GTK keeps the label
a widget of its own, sized to its own text and placed across the frame, which is
what label-xalign says: 0 at the start, 0.5 centred, 1 at the end. The
frame clips its child, so it is also the way to round a child’s corners — at the
price of cutting its shadows off.
Aspect Frame
Section titled “Aspect Frame”One child, given a shape and a place. ratio is its width over its height and
xalign / yalign say where it sits in the space left over. The fourth
property is the one to know about: obey-child is true by default, and at
that default the frame takes the ratio from the child itself and ignores ratio
entirely — so a declared ratio only bites once you set obey-child="false".
Center Box
Section titled “Center Box”Three children, pinned to the start, the centre and the end, with
whatever space is left over going to whichever of them can grow — give the centre
child hexpand and it takes that space; the three labels below sit at their own
size and the gaps go between them. The property
worth knowing is shrink-center-last: on by default, it shrinks the start and
end children first and only then the centre; off, the centre gives up its space
first. baseline-position moves the whole row in the extra space a taller
window leaves.
A table of cells, each sized by what is in it, filled row by row: a child
written without a position of its own goes in the first free cell, which is what
Gtk.Builder writes too. column-spacing and row-spacing are the gaps
between the lines, and column-homogeneous / row-homogeneous make every
line the same. A vertical grid fills the rows first instead of the columns.
Children at pixel positions, which is the whole of the widget: it declares no
property of its own, and gtk_fixed_put() is the entire API. Nothing reflows, so
a child keeps its position however its siblings move. In markup the position is
the child’s own CSS offset; in Gtk.Builder every child lands at 0, 0, which is
why the call is spelled out in the code rather than the template.
Overlay
Section titled “Overlay”Other widgets, stacked on top of one main child. set_child takes the widget
the overlay sizes itself to; add_overlay stacks widgets over it. Where a
stacked child lands is decided by its own halign and valign — that is all
gtk_overlay_get_child_position reads — so an overlay child with neither fills
the overlay, and one with an alignment keeps its natural size at that edge. GTK
adds .left / .right / .top / .bottom to an edge-aligned overlay child, so a
theme can round the corners of a badge that hangs off one.
Revealer
Section titled “Revealer”Shows and hides one child with an animation. Transition type is one of fourteen
nicks — slide-down is the default — and it is not only an opacity change: a slide
scales the box along one axis while allocating the child at its unscaled size,
and a swing folds it in with sin (π · pos / 2). Transition duration is in
milliseconds, and 0 skips the animation.
Two children either side of a divider the user drags. With both children resizable
and no position set, GTK divides the paned in proportion to the two size
requests rather than in half, so a narrow first child gets a narrow first pane.
Position in pixels overrides that, and -1 hands the choice back to the size
requests. resize-* and shrink-* all default to true, so an author turns one off
by writing false. Wide handle gives the divider the stronger separation
libadwaita draws for it.
Expander
Section titled “Expander”A title the user clicks to reveal the child below it. Label makes a GtkLabel
of its own, and use-underline turns a leading _ into a mnemonic that
Alt+that character activates. The disclosure arrow is a separate node and
:checked is set on that node, which is what libadwaita’s glyph swap keys on.
Resize toplevel asks the window to grow with the disclosure.
Related
Section titled “Related”- Buttons: the button, the toggle button and the menu button.
- Controls: the entry and the drop down, two more GTK widgets the Adwaita stylesheet paints.
- Adwaita Layout: header bars, clamps and toolbar views, the layout widgets libadwaita adds.
- Adwaita Storybook: the same widgets in a live component browser you can poke at.