How to use HorizontalLayout with Feathers UI containers

The HorizontalLayout class may be used to position the children of a container from left to right, in a single row. 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 HorizontalListLayout instead because it is better optimized for data containers by offering performance improvements like layout virtualization.

Live preview of HorizontalLayout

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 HorizontalLayout instance.

container.layout = new HorizontalLayout();

By default, the first child will be positioned in the top-left corner. Each additional child will be positioned to the right of the previous child — creating a single, horizontal row.

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.

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

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.

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

layout.verticalAlign = JUSTIFY;

Percentage Sizing

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

To see a live demonstration of percentage sizing with HorizontalLayout, open the horizontal-layout-percentage-sizing sample in your web browser. (Source Code)

percentWidth

When the parent container is using HorizontalLayout, set the percentWidth property on a HorizontalLayoutData 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 width, and the second child fills 75% of the container's total width.

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

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

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

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

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

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

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

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

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

percentHeight

When the parent container is using HorizontalLayout, set the percentHeight property on a HorizontalLayoutData 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 height, and the second child fills 50% of the container's total height.

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

var child1 = new Button();
child1.text = "One";
child1.width = 150.0;
var layoutData1 = new HorizontalLayoutData();
layoutData1.percentHeight = 100.0;
child1.layoutData = layoutData1;
container.addChild(child1);

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

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

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