Scroll Command (APL 2023.1 to 2023.2)

Scrolls a ScrollView, Sequence, or GridSequence forward or backward by a specified number of pages.

Properties

The Scroll command has the properties shown in the following table, in addition to the common command properties. Set the type property to Scroll.

In the following table, the "Default" column shows "Required" for properties that must have a value for the command to run. Otherwise it displays the default value, which might be none.

Property Type Default Description

componentId

Selector

:source

The component to scroll.

distance

Number or dimension

1

The number of pages to scroll. Defaults to 1.

The distance sets how far to scroll, in pages. For example, to scroll a list forward a single page:

  {
    "type": "Scroll",
    "componentId": "myScrollingList",
    "distance": 1
  }

Scrolling stops when any of the following occur:

  • The destination is reached.
  • The end of the scrollable content is reached.
  • The user touches the screen.
  • Alexa sends a new command. Starting a new command ends the Scroll command, which stops scrolling immediately.

To smoothly scroll through all available content, set the distance to a large number. For example, to smoothly scroll back to the beginning of a list:

  {
    "type": "Scroll",
    "componentId": "myScrollingList",
    "distance": -10000
  }

The Scroll command is ignored in fast mode.

componentId

A selector that identifies the ScrollView, Sequence, or GridSequence component to scroll. When not provided, defaults to :source. The :source selector targets the component that issued the Scroll command.

distance

The scrolling distance, measured in pages. One "page" is the width or height of the ScrollView or Sequence, less any applied padding. Negative numbers scroll backwards. The component doesn't scroll when distance is 0.

For example consider a ScrollView with a height of 400 dp and 50 dp of padding on the top and bottom. A "page" of the ScrollView is 300 dp. Specifying a distance of 0.5 scrolls forward by 50 percent of the page, or 150 dp.

You can also specify the distance as a relative or absolute dimension with a suitable suffix. For example, 50%, 33dp, or 25vh. Setting the distance to a relative number such as 50% is exactly equal to using a simple number such as 0.5. When possible, use relative scrolling dimensions such as 50% or 0.5 instead of absolute dimensions such as 100dp. This practice ensures that the content scrolls a sensible distance for the user regardless of the size of the screen.

Reinflation strategy

When the Reinflate command runs, the Scroll command can resume after Alexa reinflates the document. The command resumes when it runs on a sequencer specified in the preservedSequencers array on Reinflate. The Scroll command saves the target component and the remaining distance.

If the target component isn't a scrollable component in the reinflated hierarchy, the command is ignored.

After Alexa reinflates the document, scrolling continues for the remaining distance as calculated when the Scroll command started running. For example, assume a ScrollView with a height of 400 dp. The Scroll command started with the distance set to 50%. The command was halfway finished, so it had scrolled 25 percent of the total height, a total of 100 dp and had another 100 dp remaining to scroll when the document reinflated. After reinflation, the ScrollView now has a height of 500 dp. The Scroll command resumes and scrolls the 100 dp that was calculated before reinflation.

Scroll command example

The following example shows a Sequence that displays a long list of items. The Forward and Back buttons each run the Scroll command with a distance of 1 page. To change the distance, edit the distance property in the data source.

Was this page helpful?

Last updated: frontmatter-missing