Layout¶
Silica computes layout in containers: child widgets do not need to know their absolute coordinates; the container writes position and size into its children in Update every frame. Three concepts are enough to lay out the vast majority of UIs: layout direction, size rules, and margins and padding.
Containers and directions¶
Only Container (and the ForEach and ScrollView that derive from it) can lay out child widgets. Panel is a solid color block that can only carry Part decorations and cannot hold child widgets.
The layout property of Container accepts:
| Value | Meaning |
|---|---|
vertical, column, v |
Arrange top to bottom; child widths are stretched by default |
horizontal, row, h |
Arrange left to right; child heights are stretched by default |
absolute, none |
No layout; child widgets use their own x / y |
The default is absolute layout
The default layout of a Container is absolute. If you forget layout: vertical;, all child widgets pile up in the top-left corner. ForEach is the exception: it defaults to vertical.
Container {
layout: vertical;
width: 280;
height: 160;
padding: 10;
Label { text: "First line"; height: 16; }
Label { text: "Second line"; height: 16; }
}
Size rules¶
Along the layout direction¶
- A child widget's main axis size is decided by the widget itself:
heightin a vertical layout,widthin a horizontal one. - If the container's own main axis size is
0, it is computed automatically from the total content length after layout (padding and trailing margins included).
Perpendicular to the layout direction¶
- If a child widget's cross axis size is
0, it is stretched to the content width/height of the container. - A container's own cross axis size is not computed automatically; set it explicitly, or let its parent container stretch it.
So the usual pattern is: in a vertical container write width: 0; to let the parent decide the width, and write a fixed height or 0 to decide whether it grows with its content.
// Fill the parent container's width, height follows the content
Container {
layout: vertical;
width: 0;
height: 0;
padding: 8;
}
Widget default sizes¶
- When a
Labelhas height0: in normal mode the height is14 * font-size; withwrapenabled the default height is 3 lines. Button,Checkbox,Slider,TextBoxandDropdowneach have their own default when no height is specified.Imagehas no intrinsic size; give it an explicitwidth/height, otherwise it is invisible.
Padding¶
padding is the inset a container leaves on all four sides. The content area starts at (x + padding, y + padding), and cross axis stretching is also based on the content area:
Container {
layout: vertical;
width: 200;
height: 100;
padding: 12;
background: #171B1F;
Label { text: "12 from the border"; height: 16; }
}
padding applies to all child widgets and is computed only inside the container; it does not change the meaning of the container's own width / height: width: 200 includes the 12 of padding on each side, so the content width is 176.
Margins¶
The margin family controls the spacing between child widgets:
| Property | Effect |
|---|---|
margin |
Default spacing in the trailing direction: bottom in a vertical layout, right in a horizontal one |
margin-top |
Spacing placed before the child widget in a vertical layout |
margin-left |
Spacing placed before the child widget in a horizontal layout |
margin-bottom |
Spacing placed after the child widget in a vertical layout; uses margin when unset |
margin-right |
Spacing placed after the child widget in a horizontal layout; uses margin when unset |
margin only applies in the trailing direction
In a vertical layout margin: 8 is only equivalent to margin-bottom: 8; it does not add spacing above. To move the first child widget further from the top of the container, use padding, or write margin-top: 8 on that child.
Spacing between adjacent child widgets adds up: the previous widget's margin-bottom and the next widget's margin-top both take up space, with no collapsing.
Container {
layout: vertical;
width: 240;
padding: 8;
Label { text: "Title"; height: 16; margin-bottom: 6; }
Label { text: "Description"; height: 12; font-size: 0.7; }
Button { text: "OK"; width: 80; height: 22; margin-top: 10; }
}
Hiding and disabling¶
- A widget with
visible: falseis not drawn, does not take part in layout, takes no space, and cannot be clicked. - A widget with
disabled: truestill takes part in layout and drawing, but ignores pointer, wheel and keyboard input; when a container is disabled, the whole subtree becomes non-interactive. How much a disabled widget is dimmed by default is controlled bydisabled-opacity. - Both can be bound:
visible: @show_hint;,disabled: @locked;.
Stacking and click order¶
z-order (aliases z, layer, z-index) decides the drawing order and click priority of sibling widgets:
- Higher values are drawn later and also receive clicks first.
- Equal values follow insertion order; nodes written later are on top.
- The
layerproperty ofPartmeans something else (whether the decoration layer sits above or below the widget); do not mix it up withz-order.
Container {
layout: absolute;
width: 200;
height: 120;
Panel { x: 10; y: 10; width: 120; height: 80; background: #2A3036; }
Panel {
x: 60; y: 40; width: 120; height: 80;
background: #3C8446;
z-order: 10; // Drawn above the previous panel
}
}
Absolute layout¶
With layout: absolute the container does not move its child widgets; each child uses its own x / y. This suits floating buttons, badges and stacked cards.
x/yare coordinates relative to the top-left corner of the container's content area (when the container haspadding, they start from the content area).- When an ancestor uses a vertical or horizontal layout, the
x/yof child widgets are overridden, so absolute positioning must live inside anabsolutecontainer. - An absolute layout container does not compute its own size from its child widgets; set the width and height explicitly.
No clipping and clipping¶
Ordinary containers do not clip their child widgets: the parts that overflow the container are still drawn and may also be clicked. When you need clipping, use ScrollView, which only draws and hit-tests content inside the viewport.
If you really need to confine content to a box, redesign the sizes first; do not rely on the bounds of an ordinary container.
Layout and animation¶
transform: scale(...) in a keyframe is a pure render transform; it does not change layout or the click area. It scales around the center of the widget, which suits visual effects such as pulses and emphasis; do not let clickable targets depend on the scaled visual bounds.
The smooth slider (smooth) and ScrollView scrolling likewise only change what is drawn; layout sizes stay stable.
Troubleshooting checklist¶
| Symptom | Usual cause |
|---|---|
| All child widgets pile up in the top-left corner | The container has no layout, and the default is absolute |
| Child widgets have width 0 and are invisible | There is no parent container to stretch them on the cross axis; give the child an explicit width |
| The container height is 0 | A vertical container with height: 0 should grow automatically; check whether all child widgets are visible: false |
| The first widget sticks to the top edge | margin does not apply in the leading direction; use padding or margin-top |
| Clicks land in the wrong place | The host passes something other than GUI coordinates, or they are not converted for the GUI scale |
| Overflowing content can still be clicked | Ordinary containers do not clip; use ScrollView |