APL Sequence (APL 1.3 and earlier)
(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.
A Sequence is similar to a Container. Inside a ScrollView, a Sequence will have better performance on long lists, but 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 in addition to the base component properties. See the meaning of the columns.
Property | Type/Value | Default | Styled | Dynamic | Description |
---|---|---|---|---|---|
data |
Array of data | none | No | No | Data to bind into this container. |
firstItem |
Array of components | none | No | No | A component to include before all others. |
item(s) |
Array of components | [] | No | No | The component(s) used to lay out the data set. |
lastItem |
Array of components | none | No | No | A component to include after all others. |
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 run 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.
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 cannot have height set as a percentage value. Any item inside a horizontal Sequence that has a width value must use absolute dimensions and cannot have width set as a percentage value.
When the Sequence
component is the target of an event, event.target
reports the following values:
"event": {
"target": {
"disabled": Boolean, // True if the component is disabled
"id": ID, // ID of the component
"uid": UID, // Runtime-generated unique ID of the component
"height": Number, // Height of the component, in dp (includes the padding)
"opacity": Number, // Opacity of the component [0-1]
"position": Number, // Scrolled position of the component, as a percentage
"width": Number // Width of the component, in dp (includes the padding)
}
}
The position
value reported is calculated in the same way as the value
property
in the onScroll
property.
data
An array of arbitrary data. If the data array is bound, the sequence uses the data array inflation method.
firstItem
If assigned, the specified component is placed first in the Sequence
using the single child inflation method.
item (items)
An array of components and layouts to display in the Sequence
.
When the data
property is assigned, the Sequence
uses the data-array inflation method. When the data
property is not assigned, the sequence uses the simple array of child components inflation method.
lastItem
If assigned, a single component/layout will be appended to the sequence using the single child inflation method.
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 run during scrolling. The runtime will attempt to run 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.value
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 form:
"event": {
"source": {
"type": "Sequence",
"handler": "Scroll",
"id": ID, // ID of the sequence component
"uid": UID, // Runtime-generated unique ID of the component
"value": Number // Percentage of the current scroll position
}
}
scrollDirection
The scrollDirection is either vertical
or horizontal
. Default is vertical
.
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.
Child properties
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 = ordinalreset
: 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.
Last updated: Jun 18, 2024