Class: UWA.Controls.Scroller

UWA/Controls/Scroller. UWA.Controls.Scroller

new UWA.Controls.Scroller(element, options)

UWA.Controls.Scroller constructor.

Available Events
Event Description
onScrollStart Invoked when user starting to scroll content.
onScrollMove Invoked when user mouse or touch move on the scrollable area.
onScrollStop Invoked when user mouse or touch up/end/cancel on the scrollable area.
onScrollEnd Invoked when user stop to scroll content (after momentum or bounce ended).
onScrollPull Invoked when user start to scroll content out of boundaries.
onKeyDown Invoked when user use keyboard key.
onMouseWheel Invoked when user use mouse wheel.
onRefresh Invoked when the content or the scroller container change or resize.
Example
// 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');
        }
    }
});
Parameters
Name Type Description
element Object

Element arround the scroller wil be injected

options Object

Options hash or a option/value pair.

Properties
Name Type Argument Default Description
height String <optional>
''

Height of the scroller viewport

width String <optional>
''

Width of the scroller viewport

bounce Boolean <optional>
false

Enable scroller bounce

momentum Boolean <optional>
false

Enable momentum effect

scrollDrag Boolean <optional>
false

Enable scroller drag (mouse or touch)

useNative Boolean <optional>
false

Force native scroller usage

snap Boolean <optional>
false

Enable snap gesture

lockDirection Boolean <optional>
true

Force Scroller to move in one direction at the time

scrollableX Boolean <optional>
true

X axis scrolling is enable

scrollableY Boolean <optional>
true

Y axis scrolling is enable

scrollbarH Boolean <optional>
true

Horizontal scrollbar is enable

scrollbarV Boolean <optional>
true

Vertical scrollbar is enable

scrollTime Number <optional>
300

Scrolling duration for keyboard and nousewheel

scrollSize Number <optional>
40

Scroll offset for keyboard and nousewheel

useTransform Boolean <optional>
true

Use CSS Transform instead of UWA.FX (default: UWA.Client.Features.cssTransitions)

isTouch Boolean <optional>
true

Enable touch events support instead of mouse (default: UWA.Client.Features.touchEvents)

has3d Boolean <optional>
true

Enable 3D acceleration on momentum effect (default: UWA.Client.Features.cssMatrix)

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