APL ScrollView

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.

preserve

Array of string

[]

No

No

Properties to save when reinflating the document with the Reinflate command.

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 might 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.

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.

preserve

An array of dynamic component properties and bound properties to save when reinflating the document with the Reinflate command.

A ScrollView has the following component-specific property names you can assign to the preserve array:

  • scrollOffset – Absolute scroll position (measured in dp)
  • scrollPercent – Relative scroll position (measured as percentage of the visible area)

For example when reinflating a scroll view that contains text at a fixed font size in a fixed with, using scrollOffset ensures that first visible line of text in the scroll view remains the same:

{
  "type": "ScrollView",
  "id": "MyScrollView",
  "preserve": [ "scrollOffset" ]
}

Actionable properties

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

Sample ScrollView

The following example shows a ScrollView that contains a single Text component as the child item.

To display multiple components in a ScrollView, use a Container as the child item. For example, you might want to include the header and footer within the ScrollView for small viewports, but position those elements outside the scrolling area for larger viewports. In this case, the ScrollView for the small viewport uses a Container that contains the header, Text component with content, and footer. For an example, see Combine scrolling text with the header and footer.

To display a scrolling list of items, consider the Sequence component instead.

Last updated: Mar 02, 2023