APL GridSequence (APL 1.4)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

The GridSequence component uses a data set to display a repeating set of components in a fixed grid layout that scrolls in a single direction.

The difference between a GridSequence and a Container component is that the GridSequence has better performance on long lists, but a less flexible layout model. The difference between a GridSequence and a regular Sequence is that the GridSequence arranges its children in rows and columns.

For a pre-built responsive template that displays a GridSequence, see AlexaGridList.

Properties

The GridSequence component has the following properties:

• All actionable component properties
• All multi-child component properties
• All base component properties
• The GridSequence properties listed in following table. See the meaning of the columns.

The children of a GridSequence are laid out in fixed sizes based on the child width, height, and scrolling direction. To minimize visibility errors, the height of a vertical GridSequence and the width of a horizontal GridSequence are initialized to 100dp if they are not specified.

When the GridSequence is the source or target of an event, the following values are reported in event.source or event.target:

{
  // Grid Sequence-specific values
  "type": "GridSequence",
  "position": Number,       // Scrolled position of the component, as a percentage
  "itemsPerCourse": Number, // Number of children in each row (vertical scroll) or column (horizontal scroll)

  // General component values
  "bind": Map,              // Access to component data-binding context
  "checked": Boolean,       // Checked state
  "disabled": Boolean,      // Disabled state
  "focused": Boolean,       // Focused state
  "height": Number,         // Height of the component, in dp (includes the padding)
  "id": ID,                 // ID of the component
  "opacity": Number,        // Opacity of the component [0-1]
  "pressed": Boolean,       // Pressed state
  "uid": UID,               // Runtime-generated unique ID of the component
  "width": Number           // Width of the component, in dp (includes the padding)
}

The position value reported is described in onScroll.

childHeight

The child height property is an array that determines the height of each row in the GridSequence. In a vertically-scrolling GridSequence only the first child height value will be used and it must be either an absolute or a relative dimension (it can't be "auto"). In a horizontally-scrolling GridSequence one or more child height values may be given and the layout algorithm described previously will be used to position each child item.

childWidth

The child width property is an array that determines the width of each column in the GridSequence. In a horizontally-scrolling GridSequence only the first child width value will be used and it must be either an absolute or a relative dimension (it cannot be "auto"). In a vertically-scrolling GridSequence one or more child width values may be given and the layout algorithm described previously will be used to position each child item.

numbered

If true, set the data-binding ordinal for each of the items in the GridSequence. The ordinals start with "1" and increment by one unless the numbering property in a child is set to "skip" or "reset". The firstItem and lastItem do not participate in ordinal numbering.

onScroll

Commands to run during scrolling. The runtime attempts to run these commands once per drawing frame during scrolling, but there is no guarantee that it will succeed. On slow hardware the onScroll command may only fire intermittently.

The event.source.position reported in the command is the percentage of the current scroll position as expressed by the width/height of the sequence. For example, if the GridSequence is 200 pixels wide and the contents have shifted left by 520 pixels, the reported value is 2.60.

The event generated has the form:

"event": {
  "source": {
    "type": "GridSequence",
    "handler": "Scroll",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

The onScroll event handler runs in fast mode.

scrollDirection

The scrollDirection is either vertical or horizontal.

Multichild properties

A GridSequence is a multichild component. The GridSequence inherits all of the multichild properties.

Actionable properties

A GridSequence is an actionable component. The GridSequence inherits all of the actionable properties.

Child Properties

The children of a GridSequence support the following additional properties.

numbering

Controls the ordinal value when the parent has set numbered. This property controls how the ordinal value will be updated for the next child in the GridSequence, not the current child in the GridSequence.

• normal: The next child's ordinal = ordinal + 1.
• skip: The next child's ordinal = ordinal
• reset: The next child's ordinal = 1

GridSequence and dynamic data sources

A GridSequence can be bound to a dynamic data source such as a dynamicIndexList. Adding items to the front of a dynamic data source or in the middle of it can result in unpredictable scrolling behavior for the GridSequence. To avoid this make sure that the number of items prepended or added in the middle is a multiple of the number of items in the cross-axis. For a GridSequence with scrollDirection set to vertical the cross-axis is determined by childWidth. Conversely, for a GridSequence with scrollDirection set to horizontal the cross-axis is determined by childHeight.

Calculating the height and width of columns

The following algorithm is used when calculating the width of columns in a vertically-scrolling GridSequence.

Fixed GridSequenceWidth + Single ChildWidth

If the width of the GridSequence is a known dimension and a single child width is assigned, then the number of columns created will be equal to 100% divided by the child width and rounded down.

For example, a child width of "23%" will result in 4 columns being created with a little space left over on the right side. Similarly, a GridSequence with a width of 300dp and assigned a single child of width 50dp will give 6 columns of children.

Fixed GridSequenceWidth + Multiple ChildWidths

If the width of the GridSequence is a known dimension and more than one child width is assigned:

• Columns with an absolute dimension are assigned that value.
• Columns with a relative dimension (a percentage) are assigned the width of the overall GridSequence multiplied by that percentage.
• If there is any space left over (if the sum of the assigned column widths is less than the overall column width), divide that space evenly between each column that has an "auto" dimension. If there is no space left over, the "auto" columns are assigned a width of zero.

Auto GridSequenceWidth

If the width of the GridSequence is "auto":

• Columns with an absolute dimension are assigned that value.
• Columns with a relative dimension are assigned a width of zero.
• Columns with an "auto" dimension are assigned a width of zero.
• The overall width of the GridSequence is assigned the sum of the widths of the columns.

The algorithm for assigning heights of rows in a horizontally-scrolling GridSequence follows the same rules.

It is possible to size the children so that they are larger than the GridSequence. For example, a child width array of [ auto, 30%, 50%, 30%, auto ] will clip the fourth element and assign a size of zero to the first and the fifth elements.

A good use of the "auto" property is to fill out sizes. To define three equal-sized children, the expression [auto, auto, auto] avoids numerical rounding errors and ensures that the children are the same size.

GridSequence examples

Horizontal grid example

An example of a horizontal grid with two rows of uniform height:

{
  "type": "GridSequence",
  "height": "300dp",
  "scrollDirection": "horizontal",
  "childWidth": "200dp",
  "childHeight": "50%"
}

This example is a horizontal scrolling grid, so children will be packed in vertical columns. The height of the GridSequence is 300dp and the child height was specified as 50%, so two rows of children will be filled with each row having a height of 150dp. Each column is 200dp wide, as specified by the child width. The children of the GridSequence are arranged from the top-left filling each column before moving on to the next column. The following figure shows the layout:

Vertical grid example

An example of a vertical grid with three columns of unequal width:

{
  "type": "GridSequence",
  "width": "1000dp",
  "scrollDirection": "vertical",
  "childWidths": [ "20%", "30%", "auto" ],
  "childHeight": "100dp"
}

This example shows a vertical scrolling grid, so the child width array is used to determine the width of each column. The "auto" dimension scales to fill the remaining space, so the grid cell widths are calculated as 200, 300, and 500 dp respectively. The children of the GridSequence are arranged from the top-left filling each row before moving on to the next row. The following figure shows the layout:

Related topics

• Actionable Component Properties
• Multi-child Component Properties
• Sequence

Last updated: Jun 18, 2024