JustUI/doc/layout.md

# JustUI: Space distribution and layout

Layout is the process through which space is allocated to widgets, which are
then sized and positioned.

## Content widgets and containers

Widgets in a scene usually fulfill one of two roles:

* **Content widgets** such as labels, input fields, or menu browsers, display
  the interface and receive events. They often have no children, and do their
  own rendering.
* **Containers** such as rows and columns, stacks, or grids, organize other
  widgets so they align nicely and don't overlap. The widgets they organize are
  their children; they themselves often perform no rendering.

JustUI does not enforce this separation, and a single widget can both handle
contents and organize children. But the features are usually designed with one
of the two roles in mind.

## Layouts

Layouts are parameters that can be attached to widgets to automatically size
and position their widgets in a useful fashion. This is mostly designed for
containers. There are currently 4 types of layouts:

* **Horizontal boxes** and **vertical boxes** arrange children in a row or a
  column, respectively. Each widget gets its desired size; if there is space
  left, widgets can expand according to stretch parameters (more on that
  later).
* **Stacks** arrange all the widgets on top of each other. Only one widget is
  visible at a time. This is useful for tabbed interfaces.
* **Grids** arrange all widgets in a grid. (TODO: WIP)

A widget that does not have a layout needs to manually determine its own
desired size as well as the position its children.

## The layout process

The layout process has two phases.

1. **Size estimation.** In the first phase, each widget declares a desired
   size. This size often depends on the size of the children, so this phase
   proceeds bottom-up: first the children declare their desired sizes, then the
   parents deduce their own desired sizes, and so on.

2. **Space distribution.** In the second phase, space is distributed by the
   parents to the children. If the parents have more available space than the
   children request, extra space is distributed as well. This phase is
   top-down: first the root distributes the available space to its children,
   then these children split their shares between their own children, etc.

All of this proceeds automatically unless some widgets cannot provide a natural
size (or only a useless one), in which case the user should give a hint.

## Internals

During the first phase, the content size of each widget is evaluated by either
the layout's `csize()` function, or the polymorphic widget's `csize()`
override. Then `jwidget_msize()` adds in the geometry and stores the margin-box
size in the `w` and `h` attributes.

During the second phase, `jwidget_layout_apply()` distributes the space by
dispatching to the layout's `apply()` function, or the polymorphic widget's
`apply()` override. It proceeds recursively in a depth-first, prefix order.

## Layout control

The widget type provides a natural content size, but the user has the final say
in the size of any widget. Any widget can have a minimum and maximum size
specified, and every layout guarantees that the allocated size falls in this
range (note that limits are examined during the second phase, and the natural
content size does not need to be in the acceptable range).

Additionally, the user can provide stretch rates indicating whether the widget
can use more space horizontally and vertically. When there is space to
distribute and several widgets are competing to use it, space is allocated in
proportion to stretch rates. For instance, a widget with double the stretch
rate of its competitors will get twice as much space as them.

In certain occasions, one might want to disregard the natural content size
entirely and distribute space based only on stretch rates, for instance to
split a screen in evenly-sized columns even when the contents of the columns
have different natural sizes. In this case, one can set the columns to a fixed
width of 0 while enabling stretching-beyond-limits. Stretching beyond limits
will allow the widgets to grow despite being of fixed size, and because they
all start with the same width of 0, they will all end up with the same size.