How to use ResponsiveGridLayout with Feathers UI containers

The ResponsiveGridLayout class positions items in a grid, with a specific number of columns (defaulting to twelve columns). Items may span multiple columns and may be positioned with offsets in between. When a row is "full", meaning that all twelve columns have been filled, items are laid out starting on the next row automatically.

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

container.layout = new ResponsiveGridLayout();

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 horizontal row, until the total number of columns exceeds the maximum columns of the layout (defaults to 12 columns). Then, the next child will be positioned below the previous children to start a new row.

If ResponsiveGridLayoutData is not passed to a child, the layout will automatically assign the child to 1 column with no offset.

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 is the space between items, either horizontally or vertically. The columnGap and rowGap properties are measured in pixels.

layout.columnGap = 10.0;
layout.rowGap = 6.0;

If both gap properties should be set to the same value, call the setGap() method instead.

// sets column and row gaps to the same value
layout.setGap(10.0);

ResponsiveGridLayoutData

To adjust how many columns a child should fill, or to provide an offset, create an instance of ResponsiveGridLayoutData and pass it to a child's layoutData property.

The following example sets span property to 12, meaning that the child will fill an entire row of 12 columns.

var childLayoutData = new ResponsiveGridLayoutData();
childLayoutData.span = 12;
child.layoutData = childLayoutData;

The next example sets offset property to 3, meaning that the child will be positioned after three empty columns.

var childLayoutData = new ResponsiveGridLayoutData();
childLayoutData.span = 6;
childLayoutData.offset = 3;
child.layoutData = childLayoutData;

ResponsiveGridLayoutData has a number of additional properties, but it's necessary to understand the concept of breakpoints to use them.

Breakpoints

ResponsiveGridLayout supports breakpoints, which are customizable width thresholds that determine how the layout behaves depending on the size of the container. This is what makes the layout responsive.

The following breakpoints are defined by default.

The following example sets different span values over a variety of breakpoints for a single child.

var childLayoutData = new ResponsiveGridLayoutData();
childLayoutData.span = 12;
childLayoutData.smSpan = 8;
childLayoutData.mdSpan = 6;
childLayoutData.lgSpan = 4;
childLayoutData.xlSpan = 2;
childLayoutData.xxlSpan = 1;
child.layoutData = childLayoutData;

Similarly, a child may have different offset values over a variety of breakpoints too.

var childLayoutData = new ResponsiveGridLayoutData();
childLayoutData.span = 12;
childLayoutData.mdSpan = 6;
childLayoutData.lgSpan = 4;
childLayoutData.offset = 0;
childLayoutData.mdOffset = 3;
childLayoutData.lgOffset = 4;
child.layoutData = childLayoutData;

If a span or an offset isn't defined for a particular breakpoint, the layout will fall back to using the smaller breakpoint. In the code above, spans/offsets are defined for the the xs, md, and lg breakpoints. If the container width is large enough that the xl or xxl breakpoint would be necessary, the layout will use the values for the lg breakpoint instead. Similarly, since a span and offset is not specified for the sm breakpoint, the layout will fall back to the xs breakpoint values when the container width is smaller than the md breakpoint.

The next example demonstrates how to exclude a child from the layout using the display property of the ResponsiveGridLayoutData class.

var childLayoutData = new ResponsiveGridLayoutData();
childLayoutData.display = false;
childLayoutData.lgDisplay = true;
child.layoutData = childLayoutData;

In the code abovee, the child will be excluded from the layout and hidden in breakpoints below lg. The child will be included in the layout when the breakpoint is lg or greater (including xl and xxl).

Related Links

• feathers.layout.ResponsiveGridLayout API Documentation