layuit 1.2.2

A UI layout library for Rust
Documentation

Layuit

A renderer-agnostic UI layout system. Layuit handles computing the size and position of various UiNodes in a UiTree. Layuit does not handle rendering, but provides tools for doing so.

Layuit provides several organizational nodes such as HStack and Margin, but allows users to create their own nodes.

Layuit also provides a helpful ui! macro to make constructing complex static trees much easier and more readable.

Core concepts

  • UiTree: Owns the UiNodes and layout information in an arena and handles computation and access.
  • UiNode: A trait implemented by all UI nodes, containing alignment and any number of children.
  • Rect: A rectangle in space, represented with f32 coordinates.
  • Alignment: An alignment primarily used for determining node placement.

Layout process

Layout runs in two passes, when UiTree::calculate_layout is called:

  1. Bottom-up: minimum size. Children are visited before their parent. Each node computes its minimum size based on its children, which is then cached.

  2. Top-down: rectangles. Starting from the root, each node computes the position and size of its immediate children. Each child then uses its restricted Rect to do the same for its children.

Provided nodes

  • HStack - Horizontal arrangement
  • VStack - Vertical arrangement
  • Overlap - Independent arrangement of children
  • Margin - Adds padding to a child
  • Minimum - Creates a minimum size constraint for precise control
  • Spacer - A leaf node with configurable empty space
  • Clip - Allows a child to outgrow the node with the assumption that the renderer will clip it, and enables a scroll offset to be applied if the child is larger.
  • Hider - Allows a child's visibility to be controlled. An invisible node has no minimum size and should not be attempted to be rendered.
  • Selector - Selects a single child node to be visible at a time.
  • AspectRatio - Maintains a horizontal:vertical ratio
  • HSplit - Horizontal split between two children
  • VSplit - Vertical split between two children
  • Percent - Maintains a percentage of space for a child
  • HEqual - Horizontal arrangement with each child getting equal space
  • VEqual - Vertical arrangement with each child getting equal space
  • Grid - 2D grid of children
  • Clamp - Constrains a child to a maximum size.

External dependencies

  • thunderdome - Used publicly to provide indexing into UiTrees.
  • indexmap - Used privately to provide a stable ordering of children in multi-child nodes.