Class: UWA.Controls.Scroller

// Inject your long content that need scroller
var myContent = UWA.createElement('div', {
html: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.'
   + 'Fusce eu urna massa. Nullam mi odio, elementum ut viverra'
   + 'vitae, adipiscing eget est. Mauris massa neque, faucibus'
   + 'sed consequat non, congue ac diam. Donec in arcu nisi,'
   + 'sit amet scelerisque mauris. Quisque facilisis urna in'
   + 'ligula sodales ut adipiscing velit tempor. Vivamus ac felis'
   + 'mi. Sed hendrerit velit vel lacus aliquet ac gravida urna'
   + 'rhoncus. Ut semper, ligula et ultrices fermentum, magna'
   + 'augue vulputate odio, in pharetra arcu enim vel nisl.'
   + 'Etiam vulputate viverra ante sit amet congue. Mauris'
   + 'rutrum, lacus a luctus ullamcorper, magna lorem aliquam'
   + 'eros, ac iaculis orci neque in urna.'
}).inject(widget.body);

// Init Scroller with content as first argument and needed options
var myScroller = new UWA.Controls.Scroller(myContent, {
    height: 50,
    bounce: true,
    events: {
        onScrollStart: function () {
            myContent.setStyle('background-color', 'blue');
        },
        onScrollPull: function () {
            myContent.setStyle('background-color', 'red');
        },
        onScrollEnd: function () {
            myContent.setStyle('background-color', 'green');
        }
    }
});

Extends

• UWA.Controls.Abstract

Mixes In

• UWA.Controls.Abstract

Index

Members

<protected> name

Properties:

Name	Type	Description
name	Object	Controls identifier

<protected> position

Properties:

Name	Type	Description
position	Object	Last scheduled scroller position.

<protected> direction

Properties:

Name	Type	Description
direction	Object	Last scroller direction.

<protected> scroll

Properties:

Name	Type	Description
scroll	Object	hash or a key/value pair with scroller width/height and x/y axis state.

<protected> maxScroll

Properties:

Name	Type	Description
maxScroll	Object	axis/value pair with max scroll value.

<protected> scroller

Properties:

Name	Type	Description
scroller	Object	axis/value pair with scroller offset value.

<protected> maxPage

Properties:

Name	Type	Description
maxPage	Object	axis/value pair with max page value.

<protected> scrollBars

Properties:

Name	Type	Description
scrollBars	Object	axis/value pair with scrollBars instance.

<protected> isScrolling

Properties:

Name	Type	Description
isScrolling	Boolean	Define if scroller currently scrolling.

<protected> isTracking

Properties:

Name	Type	Description
isTracking	Boolean	Whether a touch event sequence is in progress.

<protected> isDragging

Properties:

Name	Type	Description
isDragging	Boolean	Whether the user has moved by such a distance that we have enabled

<protected> isPulling

Properties:

Name	Type	Description
isPulling	Boolean	Define if scroller has moved out of boundaries.

<protected> enabled

Properties:

Name	Type	Description
enabled	Boolean	Current scroller enable state.

<protected> defaultOptions

Properties:

Name	Type	Description
defaultOptions	Object	The default controls options.

Methods

destroy()

Destroy scroller instance and remove wrapper arround element.

setOptions(options) → {this}

Set options, automatically adds events when passed in options.

Parameters

Name	Type	Description
options	Object	options hash or a option/value pair.

Returns

• this instance

Type

this

buildNative(element)

Build main dom elements using native scroller.

Parameters

Name	Type	Description
element	DOMElement	element to wrap with the scroller.

buildSkeleton(element)

Build main dom elements used by scroller.

Parameters

Name	Type	Description
element	DOMElement	element to wrap with the scroller.

initEvents()

Init scroller events.

handleEvent() → {Boolean}

Handle scroller events.

Returns

• false if event should not propagate.

Type

Boolean

scrollTo(x, y, runtime)

Scroll to coordinate.

Parameters

Name	Type	Description
x	Number	Target on X axis
y	Number	Target on Y axis
runtime	Number	Scroll duration (default is options.scrollTime)

scrollToPage(pageX, pageY, runtime)

Scroll to page coordonate.

Parameters

Name	Type	Description
pageX	Number	Page target on X axis
pageY	Number	Page target on Y axis
runtime	Number	Scroll duration (default is options.scrollTime)

scrollToElement(el, where)

Scroll until the element is shown.

Parameters

Name	Type	Argument	Description
el	HTMLElement		the element to show
where	String	<optional>	'start', 'center', 'end', or an object with properties 'x' and 'y' with one of those value: try to put the element in the beginning, the center or the end of the scrollable zone. Default to 'center'.

setPosition(x, y, runtime, hideScrollBars)

Scroll to position and handle scrollbar position/display.

Parameters

Name	Type	Description
x	Number	New x position axis position
y	Number	New y position axis position
runtime	Number	Position translation duration
hideScrollBars	Boolean	Hide scrollbar during scroll

stopScroll()

Stop current scroll animation.

scrollToPosition(newPosition, runtime)

Scroll to position.

Parameters

Name	Type	Description
newPosition	Object	Position axis/value pair
runtime	Number	Scroll duration

triggerOnScrollStart()

TODO.

triggerOnScroll()

TODO.

triggerOnScrollEnd()

TODO.

getPosition(round) → {Object}

Get current scroller position.

Note: Using WebKitCSSMatrix feature detectiom when using CSS transform.

Parameters

Name	Type	Description
round	Boolean	Round position to integer instead of float

Returns

Position axis/value pair.

Type

Object

getResetPosition() → {Object}

Get postion inside boundaries.

Returns

• position axis/value pair.

Note: * Used after scrollEnd when bounce options is enable to restore position to the edges.

Type

Object

isInViewport(element, partially, axis) → {Boolean}

Check if the element is visible in the scroller viewport.

Parameters

Name	Type	Argument	Description
element	Element		The element to check visibility
partially	Boolean		If any part of the element is visible in the viewport or only entirely visible
axis	String	<optional>	Optionnal specific axis to check ('x' or 'y') (default: both)

Returns

true if the element is in the scroller viewport else false.

Type

Boolean

isMaxPosition(axis, position, direction) → {Boolean}

Whether or not the position reach the edge of scroller on the given axis.

Parameters

Name	Type	Description
axis	String	'x' or 'y'
position	Object
direction	Object

Returns

true if scroller reach the edge of scroller on the given axis else false.

Type

Boolean

hasOverflow(axis) → {Boolean}

Whether or not the scroller needs a scrollbar on the given axis.

Parameters

Name	Type	Description
axis	String	'x' or 'y'

Returns

true if scroller has overflow on the given axis else false.

Type

Boolean

setSize(size)

Change scroller dimensions.

Example

scroller.setSize({height: '800px'});

Parameters

Name	Type	Description
size	Object	The width and/or the height to setup

setCursor(cursor)

Change scroller cursor.

Example

scroller.setCursor('grabbing');

Parameters

Name	Type	Description
cursor	String	New scroller cursor (e.g: grab, grabbing, col-resize, row-resize)

focus() → {Scroller}

Set the focus to the scroller. When the scroller has the focus, it can be scrolled with the keyboard arrows.

Returns

this instance

Type

Scroller

updateGhostPosition(position)

Update Ghost pixel position that is used to avoid bad click events.

Parameters

Name	Type	Description
position	Object	position axis/value pair.

createDebugPixel(position, color, msg, clear)

Create Ghost pixel position that is used to avoid bad click events.

Parameters

Name	Type	Description
position	Object	position axis/value pair.
color	String	pixel color.
msg	String	debug color.
clear	Bool	if true will remove previous pixel.

getPage() → {Object}

Get current axis pages offset.

Returns

Pages axis/value pair.

Type

Object

getSnapSize() → {Object}

Get current axis snap size.

Returns

Snap size axis/value pair.

Type

Object

getScrollSize() → {Object}

Get current axis scroll size.

Returns

Scroll size axis/value pair.

Type

Object

bounce(newPosition) → {Object}

Calculate new position and transition duration for bounce options.

Parameters

Name	Type	Description
newPosition	Number	next position.

Returns

• position axis/value pair.

Type

Object

momentum(x, y, startPosition, endPosition, duration) → {Object}

Calculate new position and transition duration for momentum options.

Parameters

Name	Type	Description
x	Number	new x position axis position.
y	Number	new y position axis position.
startPosition	Object	start position axis/value pair.
endPosition	Object	end position axis/value pair.
duration	Number	duration of transition from startPosition to endPosition.

Returns

• position axis/value pair.

Note: - http://code.google.com/mobile/articles/webapp_fixed_ui.html#momentum - http://physics.stackexchange.com/questions/33323/end-position-of-movement-factoring-in-deceleration

Type

Object

snap(x, y, position) → {Object}

Calculate new position and transition duration for snap options.

Parameters

Name	Type	Description
x	Number	new x position axis position.
y	Number	new y position axis position.
position	Object	last position axis/value pair (default is <position> property value).

Returns

• position axis/value pair.

Type

Object

onScrollInit(event)

Invoked when user click on left button or touch the scrollable area.

Parameters

Name	Type	Description
event	Event	a standart DOM event.

onScrollMove(event)

Invoked when user mouse or touch move on the scrollable area.

Parameters

Name	Type	Description
event	Event	a standart DOM event.

onScrollStop(event)

Invoked when user mouse or touch up/end/cancel on the scrollable area.

Parameters

Name	Type	Description
event	Event	a standart DOM event.

onScrollStart()

Invoked when scroller starting to scroll content.

onScroll()

Invoked when scroller scroll content.

onScrollEnd()

Invoked when scroller stop to scroll content.

onScrollPull()

Invoked when user start to scroll content out of boundaries.

onKeyDown(event)

Invoked when user use keyboard key.

Parameters

Name	Type	Description
event	Event	a standart DOM event. Notes: * http://unixpapa.com/js/key.html

onMouseWheel(event)

Invoked when user use mouse wheel.

Parameters

Name	Type	Description
event	Event	a standart DOM event.

onRefresh()

Invoked when the content or the scroller container change or resize.