APL Pager
A Pager
displays a series of components one at a time. Pagers are commonly used for displaying a time-ordered sequence of data items. A Pager
differs from a Sequence because a Pager
displays separate pages instead of a long, continuous strip.
Properties
The Pager component has the following properties:
- All actionable component properties
- All multi-child component properties
- All base component properties
- The
Pager
properties listed in following table. See the meaning of the columns here.
Property | Type | Default | Styled | Dynamic | Description |
---|---|---|---|---|---|
initialPage |
Integer | 0 | No | No | The index of the starting page (0-based). Defaults to 0. |
navigation |
normal , none , wrap , forward-only |
wrap |
No | No | Specifies the allowed navigation direction. |
onPageChanged |
Array of commands | [] | No | No | Commands to run when the page changes |
Pagers present themselves to the user as a series of pages arranged in a left-to-right order. The user typically swipes the pager left or right to change pages. On a device without a touchscreen, the pager moves based on keyboard input (left\/right\/tab).
A Pager behaves differently than a Sequence. A Sequence presents as a continuous list of items. On small screens, the Sequence may show just a single item when swiped slowly, but still support a faster swiping mode that rapidly advances through the content, and may show multiple small versions of the content in a "fast scroll mode". The individual items are displayed as immediately adjacent to each other. In contrast, a Pager presents its content as the new page replacing or fading in over the old page, often with a little motion in the swipe direction of both the old and new page.
The height
and width
of the Pager
component default to 100dp if not specified. The height
and width
of a Pager must be either an absolute or relative dimension. You cannot use auto
. The height
and width
of the children of a Pager
are fixed at "100%".
When the Pager
is the source or target of an event, the following values are reported in event.source
or event.target
:
{
// Pager-specific values
"type": "Pager",
"page": Integer, // Current page
// 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)
}
initialPage
The index of the starting page to display. The index is 0-based and defaults to 0. If a firstItem
is specified, that is at index 0.
navigation
The navigation
property controls how the user may navigate with the content:
normal
– Default. The user can move freely forwards and backwards in the pager.none
– The user can't move the pager. Use commands such asAutoPage
to programmatically move the pager.wrap
– The user can move freely forwards and backwards. The last page wraps around to the first page.forward-only
: The user can only move forward.
The SetPage
and AutoPage
commands can always move the pager. The navigation
property restricts what the user can do by swiping on the screen.
onPageChanged
The onPageChanged
handler runs when the page has fully switched to
a new page. The event generated has the following form.
"event": {
"source": {
"type": "Pager",
"handler": "Page",
... // Component source properties
}
}
Refer to Event source for a description of event.source
properties. The event.source.value
property contains the index of the new page (0-based index).
Actionable properties
A pager is an actionable component. The pager inherits all of the actionable properties.
Multichild properties
A pager is a multichild component. The pager inherits all of the multichild properties.
Sample Pager
{
"type": "Pager",
"items": [
{
"type": "Text"
"text": "Text content shown on page #1"
},
{
"type": "Text"
"text": "Text content shown on page #2"
}
]
}