Scrollers

BasicScroller

A BasicScroller control provides touch-based scrolling for controls placed inside it. Applications will typically create objects of kind Scroller, which derives directly from BasicScroller.

A scroller provides a viewport in which the user can drag or flick to scroll content. Note that a user can drag beyond a valid scroll position. When this occurs, the scroller moves with increased tension before returning to a valid position with an accompanying animation.

Note also that the scrolling of content exceeding the size of a viewport is not automatic; for content to scroll, it must be placed inside a scroller control.

Scroll Axes

By default, content scrolls along both the vertical and horizontal axes.

Scrolling in either dimension can be turned on or off. In addition, a scroller can be set to allow scrolling only when content actually exceeds the scroller's dimensions.

By default, the vertical axis always scrolls, whether or not the content exceeds the scroller's height, while the horizontal axis scrolls only if content exceeds the scroller's width.

This behavior--scrolling automatically if the size of the content warrants--is controlled by the autoHorizontal and autoVertical properties. By default, autoHorizontal is set to true and autoVertical is set to false. Setting autoVertical to true will cause scrolling along the vertical axis to occur only when the content's height exceeds the scroller's height.

The autoHorizontal and autoVertical properties have precedence over the horizontal and vertical properties, which both default to true.

To disable horizontal scrolling, set both the autoHorizontal and horizontal properties to false:

{kind: "Scroller", autoHorizontal: false, horizontal: false}

Scroll Position

Scroll position can be set such that the scroller either snaps to a position directly or animates into the new position.

To set scroll position directly, without animation, set the scrollTop and scrollLeft properties:

buttonClick: function() {
  // don't allow scrolling beyond a left position of 500
  if (this.$.scroller.getScrollLeft() > 500) {
      this.$.scroller.setScrollLeft(500);
  }
}

To set scroll position with animation, use the scrollTo method:

buttonClick: function() {
  if (this.$.scroller.getScrollTop() > 100
  || this.$.scroller.getScrollLeft() > 300) {
      this.$.scroller.scrollTo(100, 300);
  }
}

It's also possible to ensure that a given scroll position is visible in a scroller's viewport by calling the scrollIntoView method. If the scroll position is in view, the scroll position will not change. If not, the scroll position will be set to the given position.

Sizing

A scroller control must have explicit dimensions. If it does not, it will simply expand to fit its content and will not provide scrolling. There are a number of ways to ensure that a scroller's dimensions are set; most commonly, a scroller is placed inside a flex layout and given a flex value. For example:

{kind: "VFlexLayout", components: [
  {kind: "PageHeader", content: "A bunch of info"},
  // NOTE: the scroller has flex set to 1
  {kind: "Scroller", flex: 1, components: [
      {kind: "HtmlContent", srcId: "lotsOfText"}
  ]},
  {kind: "CommandMenu"}
]}

Published Properties

Name	Default	Description
scrollTop	0	Current scroll position along the vertical axis.
scrollLeft	0	Current scroll position along the horizontal axis.
autoHorizontal	true	Enables horizontal scrolling only if content exceeds the scroller's width.
autoVertical	false	Enables vertical scrolling only if content exceeds the scroller's height.
fpsShowing	false	Display fps counter
accelerated	true	Use accelerated scrolling

Published Events

Name	Default	Description
onScrollStart	""	Event that fires when scrolling starts
onBeforeScroll	""	Event that fires just before scroll position changes
onScroll	""	Event that fires just after scroll position changes
onScrollStop	""	Event that fires when scrolling stops

Methods

getBoundaries()

Returns an object describing the scroll boundaries, which are the dimensions of scrolling content. For example, if getBoundaries returns

{top: 0, left: 0, bottom: 1000, left: 1000}

then the scrolling content is 1000 by 1000.

isScrolling()

Returns true if the scroller is scrolling when called.

scrollIntoView(inY, inX)

Ensures that the specified position is displayed in the viewport. If the position is not currently in view, the specified position is scrolled to directly, without animation.

scrollTo(inY, inX)

Animates a scroll to the specified position.

scrollToBottom()

Sets the scroll position to the bottom of the content, without animation.

Scroller

In addition to providing all the functionality of a BasicScroller, enyo.Scroller ensures that the dimensions of the scroller content are at least as large as the dimensions of the scroller itself.

Since this is typically desirable--it allows a background image to expand to fit the scroller, for one thing--applications should generally create instances of enyo.Scroller.

The Scroller kind does not add any additional published properties, published events, or public methods to those inherited from BasicScroller.

SnapScroller

enyo.SnapScroller is another scroller variant that derives from BasicScroller. As one might expect from the name, a snap scroller snaps to the positions of the controls it contains.

When dragged, the scroller moves normally; when a drag is finished, the scroller snaps to the scroll position of the control closest to the dragged position.

Snapping can only occur along one axis at a time. By default, this is the horizontal axis. SnapScroller has an HFlexLayout, so its controls are arranged from left to right. Setting the layoutKind to "VFlexLayout" will enable vertical snapping. Here's an example:

{kind: "SnapScroller", layoutKind: "VFlexLayout", flex: 1, components: [
  {style: "background: red; width: 400px; height: 100px"},
  {style: "background: white; width: 400px; height: 100px"},
  {style: "background: blue; width: 400px; height: 100px"}
]}