Mojo.Widget.Scroller

Namespace Detail

Overview

The Scroller widget provides all scrolling behavior. One is installed automatically in every scene (you can disable this behavior by having a truthy value in the disableSceneScroller property in the scene arguments to pushScene and you can have any number of additional scrollers anywhere in the DOM.

You can select one of six scrolling modes currently, specified in the mode property of the widget's attributes:

  1. free: allow scrolling along the x and y axis.

  2. horizontal: allow scrolling only along the horizontal axis.

  3. vertical: allow scrolling only along the vertical axis.

  4. dominant: allow scrolling along the horizontal or vertical axis, but not both at once. The direction of the intial drag will determine the axis of scrolling.

  5. horizontal-snap: In this mode, scrolling is locked to the horizontal axis, but snaps to points determined by the position of the block elements found in the model's snapElements property. As the scroller scrolls from snap point to snap point it will send a propertyChange event.

  6. vertical-snap: similarly, this mode locks scrolling to the vertical axis, but snaps to points determined by the elements in the snapElements property array

The Scroller declaration MUST wrap the scrolled contents within its scope.

Declaration

<div x-mojo-element="Scroller" id="scrollerId" class="scrollerClass"
  name="scrollerName">
  <div> TARGET SCROLL CONTENT </div>
</div>

Properties Required Value Description
x-mojo-element Required Scroller Declares the widget as type 'Scroller'.
id Required Any String Identifies the widget element for use when instantiating or rendering.
class Optional Any String Scroller uses .palm-scroller-container by default, but you can override this setting.
name Optional Any String Adds a unique name to the Scroller widget; generally used in templates.

Events

this.controller.listen(this.controller.get("scrollerId"),
  'Mojo.Event.propertyChange', this.handleUpdate);

Event Type Value Event Handling
Mojo.Event.propertyChange None Respond to Scroller value change.
Mojo.Event.scrollStarting None When contained in a scroller, down action followed by movement generates a scroll-starting event.

Instantiation

this.controller.setupWidget("scrollerId",
  this.attributes = {
      mode: 'vertical
  },
  this.model = {
      snapElements: {
          x: [DOMElement, DOMElement, DOMElement, ...]
      }
  }
); 

Attribute Properties

Attribute Property Type Required Default Description
mode String Required value Scrolling mode; one of: free, vertical, horizontal, dominant, vertical-snap, horizontal-snap

Model Properties

Model Property Type Required Default Description
snapElements Object Optional none Object containing array of DOM elements used as snap points for horizontal or vertical scrolling under the appropriate component, e.g.,
{y: [DOMElement, DOMElement, DOMElement, ...]}

Methods

To invoke a method on a widget, use the scene controller's get method for the desired widget, and append mojo followed by the method.

Example:

this.controller.get('myWidget').mojo.getValue()

Method Arguments Description
adjustBy Integer {deltaX}, Integer {deltaY} Adjust the current scroll position by the given amount. Safe to call from scroll listeners while animating.
Does not cause listeners to be notified of any changes.
createThreshholder functionToCall, element, inThreshhold Creates a function suitable for use as a moved method that calls the passed-in function only after the given element's containing scroller has moved more than the threshhold in pixels.
Safe to call from scroll listeners while animating.
Does not cause listeners to be notified of any changes.
getScrollPosition Returns an object with "left" and "top" properties indicating the current scroll position: {left: nnn px, top: nnn px}.
getState Returns the current scroll state for use in a future call to setState.
revealBottom Jumps the scroll to reveal the bottom of the content being scrolled.
revealElement HTML Element Jumps the scroll to reveal a specific element; only scrolls vertically.
revealTop Object Jumps the scroll to reveal the top of the content being scrolled.
scrollerSize Returns the size of the scroller's view port in pixels: {height:nnn, width:nnn}.
scrollTo Integer {x-coord}, Integer {x-coord}, Boolean {animate}, Boolean {supressNotification} Jumps the scroll to the x,y coordinates specified. If either of the coordinates are undefined, they are ignored.
Pass true for animate to animate the scroll.
Pass true for suppressNotification to prevent a non-animated scroll from notifying listeners.
setMode String {newMode} Sets the mode of the scroller, which controls which drag directions cause scrolling. Choices are 'free', 'dominant', 'horizontal', 'horizontal-snap', and 'vertical'.
setSnapIndex Number {snapIndex}, Boolean {animate} Sets the snap index for a snap scroller and scrolls to the new position; pass true to animate.
setState Object {scrollState}, Boolean {animate} Jumps the scroll to the value specified in scrollState; pass true to animate the scroll.