OverflowAndroid
Implement the inertia scroll for overflow
element. And the polyfill for overflow:scroll
/ overflow:auto
and element.scrollLeft
/ element.scrollTop
on Android browser.
The desktop can implement UI that scrolls by mouse drag, inertia scroll like touch device. And problems of Android browser are solved.
Android browser has problems as below:
overflow:scroll
andoverflow:auto
don't work on Android 2.x. The elements don't accept scroll operations (swipe, flick, drag, etc.).element.scrollLeft
andelement.scrollTop
don't work on Android 4.0.x. The elements can't scroll via JavaScript. Strange to say, the element that is setoverflow:hidden
can scroll. But of course that element doesn't accept scroll operations.
OverflowAndroid solves problems above.
See DEMO
Usage
Hammer.js is required.
<!-- This `overflow:auto` isn't necessary. It works on desktop PC as native. --> <!-- Like an iframe window --> <!-- Like an iframe document -->
var element = document;element;// Now, the element accepts scroll operations (swipe, flick, drag, etc.). // And it can scroll via scrollLeft/scrollTop.elementscrollLeft = 30;
Constructor
overflowA = element
The OverflowAndroid
constructor accepts an element that is scrolling frame. It gets a first child element that includes contents and it moves when scrolling. The specified element like an iframe
window, and the first child element like an iframe
document.
That has already finished. Now, the specified element accepts scroll operations (swipe, flick, drag, etc.), and it can scroll via scrollLeft
/scrollTop
.
And the instance that is returned by constructor has some methods. (see below)
NOTE: The contents that is included in specified element other than a first child element of it are ignored.
Methods
scrollLeft
currentLeft = overflowA
Return the number of pixels that the element's content is scrolled to the left. If an argument is given, the element scrolls to specified position and it is returned.
This work equals element.scrollLeft
property.
scrollTop
currentTop = overflowA
Return the number of pixels that the element's content is scrolled upward. If an argument is given, the element scrolls to specified position and it is returned.
This work equals element.scrollTop
property.
scroll
currentLeftTop = overflowA
Return the Object that has left
as the number of pixels that the element's content is scrolled to the left, and top
as the number of pixels that the element's content is scrolled upward. If arguments are given, the element scrolls to specified position and it is returned.
stop
self = overflowA
Stop scroll immediately.
initSize
self = overflowA
OverflowAndroid computes the size of elements for scroll. It computes again automatically when a window is resized. Therefore you usually don't need to call this method.
If you changed the size of elements, you must call this method. If arguments are given, the size of elements is computed and the element scrolls to specified position.
Properties
clientWidth
, clientHeight
width = overflowAclientWidth
height = overflowAclientHeight
Size of the element's view-area. This area is padding-box
in CSS. In other words, a part of contents in child element that has this size is shown.
scrollWidth
, scrollHeight
width = overflowAscrollWidth
height = overflowAscrollHeight
Size of scrolled area. This area is all of contents in child element that includes margins, and padding of target element.
In CSS, border-box
of child element + margin
s of child element + padding
s of target element. Therefore this might differ from element.scrollWidth
/element.scrollHeight
.
Event
The scroll
event is fired when the target element has been scrolled. The Event
object that is passed to event listeners has an additional property below.
inertia
Type: Boolean
Indicate whether the current event was fired by inertia scroll after fast scroll operations. i.e. user isn't touching the element now, if this is true
.
Example:
element;
Options
You can tune the behavior of OverflowAndroid via options below.
OverflowAndroid.enable
By default, OverflowAndroid works only touch-device. You can control the working or not via specifying a boolean to this option.
NOTE: This must be done before making an instance.
Example:
// Android onlyOverflowAndroidenable = navigatoruserAgent >= 0;
// AnytimeOverflowAndroidenable = true;
OverflowAndroid.friction
Default: 0.001
This is strength of slowdown of inertia scroll after fast scroll operations. This is a number of pixels per milli second.
OverflowAndroid.fps
Default: 60
This is frame rate of animation of inertia scroll after fast scroll operations. This is a number of frames per second.
This is ignored when CSS Animations is used (see OverflowAndroid.transition
).
OverflowAndroid.cursorScrollable
Default:
The CSS cursor
value when the target element is not receiving scroll operations.
If ''
is specified, cursor
is not changed.
OverflowAndroid.cursorScrolling
Default:
The CSS cursor
value when the target element is receiving scroll operations.
If ''
is specified, cursor
is not changed.
OverflowAndroid.scrollBar
Default: true
Show scroll bars.
Now, these scroll bars are mere indicators that only show each scroll-position, user can not scroll the element by operating these scroll bars.
OverflowAndroid.scrollBarWidth
Default: 5
Size of scroll bars. This is a number of pixels.
OverflowAndroid.scrollBarColor
Default: 'rgba(0,0,0,0.5)'
Color of scroll bars.
OverflowAndroid.transition
If true
is specified to this option, the inertia scroll after fast scroll operations uses CSS Animations in modern browsers. The default is false
.
NOTE: This must be done before making an instance.
The CSS Animations work smoothly in many browsers, but some browsers (particularly Firefox for Android) are not. I tried many ways (e.g. hardware acceleration), but I found nothing yet... Someone, please let me know the way. (But Firefox for Android can't scroll smoothly normal overflow:scroll
in the first place.)
See Also
jQuery.overflowAndroid is jQuery plugin that is wrapper of OverflowAndroid.