APL Pager (APL 1.0)

(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 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 in addition to the base component properties. See the meaning of the columns.

Property Type Required Styled Dynamic Description
data Array No No No Data to bind into this container.
firstItem Array of components and layouts No No No A component to include before all others.
initialPage Integer No No No The index of the starting page (0-based). Defaults to 0.
item(s) Array of components and layouts Yes No No The Component(s) used to lay out the data set.
lastItem Array of components and layouts No No No A component to include after all others.
navigation normal | none | wrap | forward-only No No No Specifies the allowed navigation direction. Defaults to "normal".

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.

data

An array of arbitrary data. If the data array is bound, the pager uses the data array inflation method.

firstItem

If assigned, a single component/layout will be prepended to the pager using the single child inflation method.

item(s)

An array of components and layouts to be displayed in the pager. If the data property is assigned, the pager uses the data-array inflation method. If the data property is not assigned, the pager uses the simple array of child components inflation method.

lastItem

If assigned, a single component/layout will be appended to the pager using the single child inflation method.

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.

The navigation property controls how the user may navigate with the content:

  • normal: Default. The user may move freely forwards and backwards in the pager.

  • none: The user may not move the pager. We assume that some automatic page advance mechanism will move the pages.

  • wrap: The user may move freely. The last page wraps around to the first page.

  • forward-only: The user may only move forward. This mode is intended for games or puzzles.

The SetPage/AutoPage commands can always move the pager. The navigation property only restricts what the user can do by swiping on the screen.

Sample Pager

{
  "type": "Pager",
  "items": [
    {
      "type": "Text"
      "text": "Text content shown on page #1"
    },
    {
      "type": "Text"
      "text": "Text content shown on page #2"
    }
  ]
}