Scroller

From WebOS101

Contents 1 Introduction 2 Scroller Properties 2.1 HTML 2.2 Events 2.3 Attributes 2.4 Model Properties 2.5 Methods 3 Notes 4 Example

Introduction

For the Enyo kind, please see enyo.Scroller.

A scroller is a non-visual component on your scene that contains other items. It allows for horizontal and/or vertical scrolling with optional snap points. A scroller is automatically created for each scene unless you suppress it during scene creation.

Scroller Properties

HTML

The HTML code for a scroller element is fairly simple:

<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 the .palm-scroller-container by default but you override this setting
name	Optional	Any String	Add a unique name to the scroller widget; generally used in templates when used

Events

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

Attributes

Attribute Property	Type	Required	Default	Description
mode	String	Required	value	Scrolling mode; either: 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. i.e {y: [DOMElement, DOMElement, DOMElement, ...]}
snapIndex	Integer	Optional	none	The index of the currently snapped-to item

Methods

Method	Arguments	Description
revealTop	Object	Jump the scroll to reveal the top of the content being scrolled.
revealBottom		Jump the scroll to reveal the bottom of the content being scrolled
revealElement	HTML Element	Jump the scroll to reveal a specific element, only scrolls vertically
scrollTo	Integer {x-coord}, Integer {x-coord}, Boolean {animate}, Boolean {supress notifications}	Jump the scroll to the x,y coordinates specified. If either of the coordinates are undefined, they are ignored
getState		Returns the current scroll state for use in a future call to setState.
setState	Object {scrollState},Boolean {animate}	Jumps the scroll to the value specified in scrollState; pass true to animate the scrollJumps the scroll to the value specified in scrollState
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.
scrollerSize		Returns the size of the scroller's view port in pixels: {height:nnn, width:nnn}
setMode	String {newMode}	Set the mode of the scroller, which controls which drag directions causes scrolling. Choices are 'free', 'dominant', 'horizontal', 'horizontal-snap', and 'vertical'.
getScrollPosition		Get the current position of the scroller. Returns {left: nnn px, top: nnn px}
setSnapIndex	Number{snapIndex}, Boolean {animate}	Sets the snap index for a snap scroller and scrolls to the new position; pass true to animate.

Notes

If you're using a vertical scroller you should not create your container to have a height greater than the screen or it won't scroll vertically.

To get the default scene controller created for you by mojo use:

this.controller.getSceneScroller();

Example

Define your scroller:

<div x-mojo-element="Scroller" id="myScroller" class="scrollerClass" name="scrollerName">
    <div id="myContent">
        <canvas id="myCanvas" width="768" height="768"></canvas>
    </div>
</div>

set it up:

this.controller.setupWidget("myScroller",
    this.attributes = {
    },
    this.model = {
        scrollbars: true,
        mode: "free"
    });

and don't forget to adjust its size

this.controller.get("myScroller").setStyle({ height: this.controller.window.innerHeight + "px"});
this.controller.get("myScroller").setStyle({ width: this.controller.window.innerWidth + "px"});

if the scroller contains a list, simply set the list width/height to auto (this just shows an example with inline styling - best practice is to place styles in your css):

<div id="vert_scroller" x-mojo-element="Scroller" width="auto" height="300px">
    <div id="vert_scrolling_contents" width="auto" height="auto">
        <div id='myList' x-mojo-element="List"></div>
    </div>
</div>

If you need to subscribe to the scroller's position, use Mojo.Event.dragging:

// scrollDrag being an example; you'd use your actual handler function reference
this.controller.listen('myScroller', Mojo.Event.dragging, this.scrollDrag);