How to use VerticalLayout with Feathers UI containers

The VerticalLayout class may be used to position the children of a container from top to bottom, in a single column. It supports a number of useful options for adjusting the spacing around the container's children and their alignment within the bounds of the container.

This layout is designed to be used with basic containers like LayoutGroup and ScrollContainer, which are intended purely for visual layout and do not offer built-in capabilities for rendering data from a collection. If using a container that renders a collection of data — such as ListView, TreeView, or GridView — consider using VerticalListLayout instead because it is better optimized for data containers by offering performance improvements like layout virtualization.

Live preview of VerticalLayout

The Basics

Create a LayoutGroup container, add it to the display list, and then add a few children to the container.

var container = new LayoutGroup();
addChild(container);

var child1 = new Button();
child1.text = "One";
container.addChild(child1);

var child2 = new Button();
child2.text = "Two";
container.addChild(child2);

var child3 = new Button();
child3.text = "Three";
container.addChild(child3);

Set the container's layout property to a new VerticalLayout instance.

container.layout = new VerticalLayout();

By default, the first child will be positioned in the top-left corner. Each additional child will be positioned below the previous child — creating a single, vertical column.

The following sections will introduce a number of properties that may be used to adjust the positioning and sizing of children in the layout.

Spacing

The padding is the space around the edges of the container that will contain no children. Padding may be added on each side, including top, right, bottom, and left.

layout.paddingTop = 10.0;
layout.paddingRight = 15.0;
layout.paddingBottom = 10.0;
layout.paddingLeft = 15.0;

If all four padding properties should be set to the same value, call the setPadding() method instead.

// sets top, right, bottom and left to the same value
layout.setPadding(10.0);

The gap refers to the space, measured in pixels, between each child in the container.

layout.gap = 5.0;

Alignment

The children of the container may be aligned within the container's bounds.

To align the children along the x-axis, set the horizontalAlign property.

layout.horizontalAlign = CENTER;

In the example above, the children are aligned to the center of the x-axis. They may also be aligned to the left or to the right.

The horizontalAlign property also supports a special value, named JUSTIFY. When horizontal justification is specified, the width of all items in the layout is adjusted to fill the full width of the container.

layout.horizontalAlign = JUSTIFY;

To align the children along the y-axis, set the verticalAlign property.

layout.verticalAlign = MIDDLE;

In the example above, the children are aligned to the middle of the y-axis. They may also be aligned to the top or to the bottom.

Note: Vertical alignment may be used only when the total height of the content (including padding and gap values) is less than or equal to the height of the container. If the content is larger than its parent container, the layout will position the children starting from 0.0 on the y-axis, the same as if they were top-aligned.

Percentage Sizing

The dimensions of each child in a container using VerticalLayout may optionally be set to some percentage of the container's total width or height.

To see a live demonstration percentage sizing with HorizontalLayout (which works similarly to VerticalLayout), open the horizontal-layout-percentage-sizing sample in your web browser.

percentWidth

When the parent container is using VerticalLayout, set the percentWidth property on a VerticalLayoutData instance, and pass it to a child's layoutData property.

In the following example, two children are added to a container. The first child fills 100% of the container's total width, and the second child fills 50% of the container's total width.

var container = new LayoutGroup();
container.layout = new VerticalLayout();
addChild(container);

var child1 = new Button();
child1.text = "One";
child1.height = 150.0;
var layoutData1 = new VerticalLayoutData();
layoutData1.percentWidth = 100.0;
child1.layoutData = layoutData1;
container.addChild(child1);

var child2 = new Button();
child2.text = "Two";
var layoutData2 = new VerticalLayoutData();
layoutData2.percentWidth = 50.0;
child2.layoutData = layoutData2;
container.addChild(child2);

Notice that fixed pixel values may be mixed with percentage values on the same child. The height of the first child is 150.0 pixels, but the width is 100% of the container's total width.

Tip: If the width of every child in a VerticalLayout should be 100%, set horizontalAlign to JUSTIFY. You'll write less code, and performance will be better optimized.

percentHeight

When the parent container is using VerticalLayout, set the percentHeight property on a VerticalLayoutData instance, and pass it to a child's layoutData property.

In the following example, two children are added to a container. The first child fills 25% of the container's total height, and the second child fills 75% of the container's total height.

var container = new LayoutGroup();
container.layout = new VerticalLayout();
addChild(container);

var child1 = new Button();
child1.text = "One";
var layoutData1 = new VerticalLayoutData();
layoutData1.percentHeight = 25.0;
child1.layoutData = layoutData1;
container.addChild(child1);

var child2 = new Button();
child2.text = "Two";
var layoutData2 = new VerticalLayoutData();
layoutData2.percentHeight = 75.0;
child2.layoutData = layoutData2;
container.addChild(child2);

Children with percentage sizing may be combined with children using fixed pixel heights. In that case, percentHeight will be based on the remaining space in the parent container after the fixed pixel height is subtracted from the container's height.

In the following example, there are two children again, but this time, the first child is a fixed 150.0 pixels tall, and the second child uses percentHeight. In this situation, the percentage will be based on the height of the container minus 150.0 pixels.

var container = new LayoutGroup();
container.layout = new VerticalLayout();
addChild(container);

var child1 = new Button();
child1.text = "One";
child1.height = 150.0; // pixels
container.addChild(child1);

var child2 = new Button();
child2.text = "Two";
var layoutData2 = new VerticalLayoutData();
layoutData2.percentHeight = 100.0;
child2.layoutData = layoutData2;
container.addChild(child2);

Because the first child's height is 150.0 pixels, and not a percentage, the second child's height won't be equal to the height of the container, even though percentHeight is equal to 100.0. Percentages are always calculated after fixed values in pixels have been subtracted from the container's total size.