Using WaterfallLayout in Feathers containers (Starling version)

The WaterfallLayout class may be used by components that support layout, such as List, LayoutGroup and ScrollContainer, to display items with multiple columns of equal width where items may have variable heights. Items are added to the layout in order, but they may be added to any of the available columns. The layout selects the column where the column's height plus the item's height will result in the smallest possible total height.

Screenshot of Feathers WaterfallLayout

WaterfallLayout supports a number of useful options for adjusting the number of columns, the spacing between items, and the alignment of the columns.

The Basics

First, let's create a WaterfallLayout and pass it to a LayoutGroup:

var layout:WaterfallLayout = new WaterfallLayout();
 
var container:LayoutGroup = new LayoutGroup();
container.layout = layout;
this.addChild( container );

There are a number of simple properties that may be used to affect positioning and sizing of items in the layout. Let's look at some of the most common.

Spacing

The padding is the space around the edges of the container. Let's set the padding property to 12 pixels:

layout.padding = 12;

If needed, we may set padding on each side of the container separately. Below, we set the paddingTop and paddingBottom to 10 pixels, and we set the paddingLeft and paddingRight to 15 pixels:

layout.paddingTop = 10;
layout.paddingRight = 15;
layout.paddingBottom = 10;
layout.paddingLeft = 15;

The gap is the space between items. Let's set the gap property to 5 pixels:

layout.gap = 5;

If needed, we can set the horizontal and vertical gaps separately. We'll set the horizontalGap property to 4 pixels and the verticalGap property to 6 pixels:

layout.horizontalGap = 4;
layout.verticalGap = 6;

Columns

We can align the columns in the layout using the horizontalAlign property. Let's adjust the horizontal alignment so that the content will be pulled to the right:

layout.horizontalAlign = HorizontalAlign.RIGHT;

It's possible to request a specific number of columns for the layout to display. The layout may not always be able to accomodate this value because the container may be too small, but if there is enough room for the requested number of columns, that's the number it will display. Let's tell the layout to use three columns by setting the requestedColumnCount property:

layout.requestedColumnCount = 3;

Now, the layout will always display three columns, even if the container can fit four or more. However, if only one or two columns can be fit into the container, the layout will display the maximum number that will fit.

If the width of the container is not set, the layout will automatically calculate a width that accomodates the requestedColumnCount.