ZStack

ZStack — a layout container that layers children on top of each other.

Public functions

ZStack

Detailed description

The container sizes itself to the maximum width and maximum height across all children, measured at an unspecified proposal so background rects do not inflate the size. Height additionally takes a width-bounded query when the parent bound the width, so a wrapping child reports the height it will really occupy rather than a single line; see layout_response for why that query is width-only. Each child is then offered the full container bounds and positioned according to the container-level Alignment (default: CENTER); individual children can override alignment via WidgetTree::set_alignment.

The primary use-cases are layered UIs — a background RectWidget beneath a TextWidget, a floating badge over a button icon — and card-like compositions where a paint layer and a content layer share the same bounds. Children that expand to fill their proposal (e.g. RectWidget) fill the full ZStack area; children with fixed intrinsic sizes are positioned by alignment.

Every layer is offered the stack's full size, so a widget that answers proposal.resolve(0.0, 0.0) fills the whole stack. Being on top, it takes every press over the stack even with no handler, which is correct occlusion. An invisible helper layer (a frame-tick driver, say) should be .hit_transparent(true) or answer Size::ZERO.

Propagates shrink weight and minimum size when any child opts in, so wrapping a shrinkable single-line label in a ZStack stays shrinkable.

#![allow(unused)]
fn main() {
use teksilo_widgets::primitives::{ZStack, TextWidget};
use teksilo_widgets::RectWidget;
use teksilo_i18n::lit;
use teksilo_tokens::SurfaceRole;
let _card = ZStack::new()
    .child(RectWidget::new().background(SurfaceRole::Raised))
    .child(TextWidget::new(lit!("Hello")));
}

Density

The picture above is the widget at TargetDensity::Compact, the mouse-and-keyboard ladder. Below is the same subject on the same canvas with only the ladder changed, so what moves is the density and nothing else — where the subject no longer fits, that is what the denser targets cost it at that size. See docs/density-and-targets.md.

Touch

API reference

📖 Full rustdoc API for this module

pub struct ZStack

Import: use teksilo::widgets::ZStack;

A layout container that stacks children on top of each other. Size = max of children sizes. Children are positioned according to the container's Alignment (default: center), with per-child overrides.

#![allow(unused)]
fn main() {
pub struct ZStack { /* fields */ }
}

Methods

pub fn new() -> Self

Create an empty ZStack with center alignment.

pub fn alignment(mut self, alignment: Alignment) -> Self (default: Alignment::CENTER)

Set the alignment applied to every child that does not have a per-child override set via WidgetTree::set_alignment.

pub fn child(mut self, widget: impl teksilo_core::IntoTeksiChild) -> Self

Add an inline child widget (deferred insertion).

pub fn children( mut self, iter: impl IntoIterator<Item = impl teksilo_core::IntoTeksiChild>, ) -> Self

Add multiple inline children from an iterator.

pub fn child_opt(mut self, widget: Option<impl teksilo_core::IntoTeksiChild>) -> Self

Conditionally add a child. No-op if None.