APL Sequence

A Sequence uses a data set to inflate a repeating set of components and display them in a long scrolling list. See Alexa Design Guide–Sequence for guidance on using sequences to develop a good user experience in Alexa skills.

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. See APL Support for Item Selection.

Properties

The Sequence component has the following properties:

Property Type/Value Default Styled Dynamic Description
numbered boolean false No No If true, assign ordinal numbers to children in the data-binding context.
onScroll Array of command [] No No Command to execute during scrolling
scrollDirection horizontal, vertical vertical No No The direction to scroll this sequence.

The children of a sequence are laid out in a continuous strip (either left-to-right or top-to-bottom). The dimension of the child component along the scrolling axis is auto, meaning that it wraps the content of the child by default.

height and width

To minimize visibility errors, the height of a vertical sequence and the width of a horizontal sequence are initialized to 100dp if they are 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 inside a horizontal Sequence that has a width value must use absolute dimensions and can't use a percentage value for the width.

numbered

If 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 a child is set to "skip" or "reset". Note that the firstItem and lastItem do not participate in ordinal numbering.

The numbered property does not 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 execute during scrolling. The runtime will attempt to execute these commands once per drawing frame during scrolling, but there is no guarantee that it will succeed. On slow hard 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 Sequence is 200 pixels wide and the contents have shifted left by 520 pixels, the reported 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.

scrollDirection

The scrollDirection is either vertical or horizontal. Default is vertical.

Multichild properties

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

Actionable properties

A Sequence is an actionable component. The Sequence inherits all of 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 described in the onScroll property.

The event properties include ranges for visible children.

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

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

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

  • The 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 of the child components which have some part shown in the sequence. The range firstFullyVisibleChild to lastFullyVisibleChild contains all of 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.

Sequence children

The children of a sequence lay out in a continuous strip (either left-to-right or top-to-bottom). 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.

Property Type/Value Default Styled Dynamic Description
numbering normal, skip, or reset normal No No Control ordinal numbering of the next child.
spacing Absolute dimension 0 No No Additional space to add between this component and the previous component in the layout.

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 sequence, not the current child in the sequence.

  • normal: The next child's ordinal = ordinal + 1.
  • skip: The next child's ordinal = ordinal
  • reset: The next child's ordinal = 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 expressed in absolute dimensions.