APL Sequence (APL 1.7 to 2024.1)

(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)

A Sequence uses a data set to inflate a repeating set of components and display them in a long scrolling list.

Although Sequence is similar to a Container, the Sequence has better performance for long lists of items. The Sequence has a less-flexible layout model.

You can also use a Sequence to allow ordinal and anaphor-based selection of items on the screen. For details, see APL Support for Item Selection.

For a pre-built responsive templates that display a Sequence, see AlexaTextList, AlexaImageList, and AlexaLists.

Properties

The Sequence component has the following properties:

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

height and width

To minimize visibility errors, the height of a vertical sequence and the width of a horizontal sequence initialize to 100 dp when not specified. Don't use auto for the height or width. Use an absolute or relative dimension for the Sequence size.

Any item template inside a vertical Sequence that has a height value must use absolute dimensions and can't use a percentage value for the height. Any item template inside a horizontal Sequence that has a width value must use absolute dimensions and can't use a percentage value for the width.

layoutDirection component property

The component layoutDirection property determines the direction to display the items when the scrollDirection property is horizontal:

• Left-to-right (LTR) – The Sequence arranges items starting on the left side. Items scroll into view from the right.
• Right-to-left (RTL) – The Sequence arranges items starting from the right side. Items scroll into view from the left.

numbered

When true, set the data-binding ordinal for each of the items in the sequence. The ordinals start with "1" and increment by one unless the numbering property in the child component is skip or reset. The firstItem and lastItem aren't included in ordinal numbering.

The numbered property doesn't display any numbers on the screen automatically. You can use the ordinal value in the data-binding context to display the numbers in a Text component.

onScroll

Commands to run during scrolling. The runtime attempts to run these commands one time per drawing frame during scrolling, but this attempt might not succeed. On slow hardware, the onScroll command might run intermittently.

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

The event generated has the following form.

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

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

The onScroll event handler runs in fast mode in the component data-binding context.

preserve

An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate command.

A Sequence has the following component-specific property names you can assign to the preserve array:

• centerId – The id of the child in the center of the sequence.
• centerIndex – The index of the child in the center of the sequence
• firstId – The id of the child at the top of the sequence.
• firstIndex – The index of the child at the top of the sequence.
• scrollOffset – Absolute scroll position (measured in dp).
• scrollPercent – Relative scroll position (measured as percentage of the visible area).

The firstIndex option uses the index of the current child shown at the start of the sequence and (after reinflation) sets the scroll position to place the same child (by index) at the start of the sequence. The firstId uses the id of the current child shown at the start of the sequence and (after reinflation) sets the scroll position to put the same child (by id) at the start of the sequence.

The centerIndex option uses the index of the current child shown in the center of the sequence and (after reinflation) sets the scroll position to place the same child (by index) in the center of the sequence. The centerId uses the id of the current child shown in the center of the sequence and (after reinflation) sets the scroll position to put the same child (by id) in the center of the sequence.

When searching by id (for both centerId and firstId), if the id is not found either before reinflation or after reinflation, the sequence is positioned at the start. When searching for a component by index (for both centerIndex and firstIndex), if no child is present at that index, the sequence is positioned at the start.

scrollDirection

The direction to lay out and scroll the Sequence items. The scrollDirection property can be one of the following:

• vertical – Display the items in a vertical list. The list scrolls up and down.
• horizontal – Display the items in a horizontal list. The list scrolls left and right.

snap

The alignment that the child components snap to when scrolling stops. When the user scrolls through the content and then stops scrolling, the Sequence can shift the child items to "snap" to the start, center, or end of the Sequence container. The Sequence aligns the child item closest to the snap position. For example, when snap is center, the Sequence shifts the items so that the item closest to the center snaps to the center of the container.

A Sequence supports two types of snap behavior:

• Snap when scrolling has velocity – When the user scrolls through the content, releases the pointer, and allows the sequence to slow to a stop, the Sequence aligns the child components as requested or at the start or end of the sequence. No snapping occurs when the user releases the pointer with little or no scroll velocity. For this type of snapping, set snap to start, center, or end.
• Always snap (force snap) – After the user releases the pointer, the Sequence always aligns the child components as requested or at the start or end of the Sequence. With the force snap behavior, the scroll velocity doesn't matter. For this type of snapping, set snap to forceStart, forceCenter, or forceEnd.

Snapping excludes any padding when determining the start, center, or end of the Sequence container.

The snap property can take the following values:

• none – (Default) No snapping occurs.
• start – Align the starting side of the child component to the start of the container when scrolling has velocity.
• center – Align the center of the child component to the center of the container when scrolling has velocity.
• end – Align the ending side of the child component to the end of the container when scrolling has velocity.
• forceStart – Align the starting side of the child component to the start of the container, regardless of scrolling velocity.
• forceCenter – Align the center of the child component to the center of the container, regardless of scrolling velocity.
• forceEnd – Align the ending side of the child component to the end of the container, regardless of scrolling velocity.

The snap property applies when the user scrolls the content. The property doesn't apply to scrolling commands. To align items during command-driven scrolling, use the ScrollToComponent or ScrollToIndex command and set the align property on the command.

Multichild properties

A Sequence is a multichild component. The Sequence inherits all the multichild properties.

Actionable properties

A Sequence is an actionable component. The Sequence inherits all the actionable properties.

Sequence event object

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

{
  // Sequence-specific values
  "type": "Sequence",
  "position": Number,  // Scrolled position of the component, as a percentage

  // Visible children
  "firstVisibleChild": Integer,       // Index of the first partially visible child
  "firstFullyVisibleChild": Integer,  // Index of the first fully visible child
  "lastFullyVisibleChild": Integer,   // Index of the last fully visible child
  "lastVisibleChild": Integer,        // Index of the last partially visible child

  // 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 the percentage of the current scroll position as expressed by the width or height of the sequence. This value is the same as the position reported by the onScroll handler.

The event properties include ranges for visible children.

A child component is fully visible when all the following are true:

• The bounds of the child component don't extend outside of the default bounds of the Sequence,
• The child component display property is "normal"
• The child component has an opacity of 1.0.

A child component is visible, but not fully visible when all the following are true:

• The default bounds of child component intersect with the bounds of the sequence
• The child display property is "normal"
• The child has a non-zero opacity.

The range firstVisibleChild to lastVisibleChild contains all the child components which have some part shown in the sequence. The range firstFullyVisibleChild to lastFullyVisibleChild contains all the child components which are fully visible in the sequence.

The firstVisibleChild and lastVisibleChild properties return –1 if no children are visible in the sequence. The firstFullyVisibleChild and lastFullyVisibleChild properties return –1 if no children are fully visible in the sequence.

The visibility calculations don't consider the child transform property or occlusion by other components that might overlap the sequence.

The following example shows a Sequence that displays a list of Text components. As you scroll through the list, the text below the Sequence updates to show some of the event object properties. Click the buttons to scroll to a specific index in the list. Click and drag in the Sequence to scroll manually.

Sequence child items

The children of a sequence display in a continuous strip. The Sequence arranges the items in either a horizontal or vertical direction:

• Horizontal – The items display in either a left-to-right or right-to-left order, depending on the value of the layoutDirection property. The user swipes the component left or right to scroll through the items.
• Vertical – The items display in a top-to-bottom order. The user swipes the component up and down to scroll through the items.

The dimension of the child along the scrolling axis is auto; that is, it wraps the content of the child by default.

The children of a Sequence support the following additional properties.

numbering

Applies when the Sequence has numbered set to true. The numbering property controls how the Sequence updates the ordinal value for the next child in the sequence.

• normal: The next child ordinal is ordinal + 1.
• skip: The next child ordinal is ordinal
• reset: The next child ordinal is 1

spacing

An amount of spacing to add between this component and the previous component in the sequence. The first item in the sequence ignores spacing. The value must be in absolute dimensions.

Sequence example

The following example shows a Sequence that displays a Text component. The example binds the data property to an array of items, so the Sequence uses data array inflation. Therefore, the Sequence displays the child item one time for each item in the data array.

The example also demonstrates the firstItem and lastItem properties. For the small, round hub, these properties define the header and footer. The header and footer scroll along with the rest of the list items. For all other viewports, the example uses a Container for the header, Sequence, and footer. The header and footer remain fixed on the screen all the time.

Related topics

• Actionable Component Properties
• Multi-child Component Properties
• GridSequence
• Alexa Design Guide: Alexa Presentation Language

Last updated: Feb 29, 2024