APL Pager (APL 1.4 to 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 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.

About the Pager component

A Pager displays as a series of pages arranged in a left-to-right order. The user 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 is different than a Sequence. A Sequence presents as a continuous list of items. On small screens, the Sequence might show one item when swiped slowly, but the Sequence still supports a faster swiping mode to rapidly advance through the content. When the Sequence items are small, the Sequence can show multiple small versions of the content in a "fast scroll mode." The individual items display next 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.

Properties

The Pager component has the following properties:

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

The height and width of the Pager component default to 100 dp if not specified. The height and width of a Pager must be either an absolute or relative dimension. You can't use auto. The height and width of the children of a Pager are always 100%. This means that a Pager child item is always the same size as the Pager itself.

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. When the firstItem property has a value, the firstItem item is at index 0.

The navigation property controls how navigates 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 to programmatically move the pager. For example, the AutoPage and SetPage commands.
  • wrap – The user can move freely forwards and backwards. When the user swipes on the last page, the pager wraps to the first page.
  • forward-only: The user can move forward but not backwards.

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 pager 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 the actionable properties.

Multichild properties

A pager is a multichild component. The pager inherits all 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"
    }
  ]
}
Was this page helpful?

Last updated: Nov 28, 2023