APL Sequence (APL 1.5)

---

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

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.

Property	Type	Default	Styled	Dynamic	Description
numbered	Boolean	false	No	No	When true, assign ordinal numbers to the Sequence children in the data-binding context.
onScroll	Array of commands	[]	No	No	Commands to run while the Sequence scrolls.
scrollDirection	One of: horizontal, vertical	vertical	No	No	The direction to scroll this sequence.

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.

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

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.

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:

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

Sequence children

The children of a sequence display 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	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

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'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 in absolute dimensions.

---

---

Last updated: Jun 18, 2024