APL ScrollView

A ScrollView holds a single child and scrolls vertically.

Properties

The ScrollView component has the following properties:

• All actionable component properties
• All base component properties
• The ScrollView properties listed in following table. See the meaning of the columns.

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

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:

Actionable properties

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

Sample ScrollView

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.