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