Container (Character Displays)

A Container is a layout that uses a subset of Flexbox/Yoga (https://github.com/facebook/yoga) as the layout language.

Container properties

Property Type Default Dynamic Description
alignItems stretch | center | start | end stretch No Alignment for children in the cross-axis.
data Array <none> No Data to bind into this container.
direction column | row column No The direction that children will be laid out.
firstItem Array of components and layouts <none> No A component to include before all others.
items Array of components and layouts [] No The Component(s) used to lay out the data set.
justifyContent start | end | center | spaceBetween | spaceAround start No How to distribute free space when there is room on the main axis.
lastItem Array of components and layouts <none> No A component to include after all others.

APL-T containers never scroll.

When the container is the target of an event (see Event definition), the following values are reported in event.target:

"event": {
  "target": {
    "disabled": Boolean, // True if the component is disabled
    "id": ID,            // ID of the component
    "uid": UID,          // Runtime-generated unique ID of the component
    "height": Number,    // Height of the component, in characters (includes the padding)
    "width": Number      // Width of the component, in characters (includes the padding)
  }
}

alignItems

The Flexbox specification for how children should be aligned in the cross-axis of the container.

data

An array of arbitrary data. If the data array is bound, the container uses the data array inflation method (Data array inflation)

direction

The direction of layout in the container. Defaults to column.

firstItem

If assigned, a single component/layout will be prepended to the container using the single child inflation method (Single child inflation).

item (items)

An array of components and layouts to be displayed in the container. If the data property is assigned, the container uses the data-array inflation method (Data array inflation). If the data property is not assigned, the container uses the simple array of child components inflation method (Simple child array inflation).

lastItem

If assigned, a single component/layout will be appended to the container using the single child inflation method (Single child inflation).

justifyContent

The Flexbox specification for how free space will be distributed when there is room on the main axis. Only useful if the container is larger than the size of its children.

Container Children

Children of containers have additional properties that control how that child is positioned in the parent container.

Property Type Default Dynamic Description
alignSelf auto | start | end | center | baseline | stretch auto No Cross-axis layout position.
bottom Dimension <none> No Only used in absolute positioning; specifies the distance from the bottom edge of the parent container.
grow Number 0 No If positive, this component will stretch if there is extra space in the Container.
left Dimension <none> No Only used in absolute positioning; specifies the distance from the left edge of the parent container.
position relative | absolute relative No If absolute, the component is positioned with respect to the parent container.
right Dimension <none> No Only used in absolute positioning; specifies the distance from the right edge of the parent container.
shrink Number 0 No If positive, this component will shrink if there is not enough space in the Container.
spacing Absolute Dimension 0 No Only used in relative positioning; Additional space to add between this and the previous component.
top Dimension <none> No Only used in absolute positioning; specifies the distance from the top edge of the parent container.

alignSelf

Overrides the alignItems property for this child.

position, bottom, left, right, top

If position is set to "absolute", this child is taken out of the normal layout ordering for the container and instead positioned absolutely relative to the parent. The top, bottom, left, and right properties are dimensional offsets from the sides of the parent container. The padding of the parent container is ignored for an absolutely positioned child.

In an "absolute"-positioned element where the size of the element is fixed, the left property overrides the right property if both are set and the top property overrides the bottom property if both are set. If neither is set, the element is positioned at the top-left of the parent container. For example, the following component will be positioned 5 units from the top-right of its parent container:

{
  "position": "absolute",
  "width": 10,
  "height": 10,
  "top": 5,
  "bottom": 5,  // Ignored because "top" was set
  "right": 5
}

grow

Flexbox grow property. A positive grow value will stretch the component proportionally if there is extra space in the container. A negative grow values is ignored.

shrink

Flexbox shrink property. A positive shrink value will allow the component to shrink below its normal size if there is not enough space in the container. A negative shrink value is ignored.

spacing

An amount of spacing to add between this component and the previous component in the sequence. The first item in the sequence ignores spacing. The spacing must be specified in absolute dimensions; relative are not supported. The spacing property only applies for "relative"-positioned elements.