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.

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 as AutoPage 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 executes 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"
    }
  ]
}