APL ScrollView (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 ScrollView holds a single child and scrolls vertically.

Properties

The ScrollView component has the following properties:

The default height and width properties are each set at 100dp.

Property Type Default Styled Dynamic Description
item, items Array of components [] No No The Component displayed in the ScrollView.
onScroll Array of commands [] No No Command to run during scrolling.

The ScrollView holds a single child. The child of the ScrollView can be arbitrarily long in the vertical direction. If the child is small enough to fully fit on the screen, no scrolling occurs. To minimize errors, the height of the scroll view defaults to 100dp if not specified.

When the ScrollView is the source or target of an event, the following values are reported in event.source or event.target:

{
  // ScrollView-specific values
  "type": "ScrollView",
  "position": Number,  // Scrolled position of the component, as a percentage

  // 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)
}

The position value reported is calculated in the same way as the value property in the onScroll property.

item

The child component. If more than one component is supplied, the first one selected by the when property is used.

onScroll

An array of commands to run during scrolling. The runtime attempts to run these commands once per drawing frame during scrolling, but there is no guarantee that it will succeed. On slow devices 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 height of the scroll view. For example, if the ScrollView is 200 pixels tall and the contents have shifted up by 320 pixels, the reported value is 1.60.

The event generated has the following form.

"event": {
  "source": {
    "type": "ScrollView",
    "handler": "Scroll",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

The onScroll event handler runs in fast mode.

Actionable properties

A ScrollView is an actionable component. The ScrollView inherits all of the actionable properties.

Sample ScrollView

{
  "type": "ScrollView",
  "item": {
    "type": "Text",
    "text": "${payload.longTextBlock}"
  }
}

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 hardware, the onScroll command may only fire intermittently.

The event.source.position reported in the command is the percentage of the current scroll position as expressed by the height of the scroll view. For example, if the ScrollView is 200 pixels tall and the contents have shifted up by 320 pixels, the reported value is 1.60.

Was this page helpful?

Last updated: Jun 18, 2024