search

Dindows-Systems / Overscroll

Overscroll is a jQuery Plugin and polyfill for mobile safari's overflow-scrolling style. It is intended for use in a desktop browser.
http://azoffdesign.com/overscroll
0 stars 0 forks source link

readme

Overscroll v1.6.4

Thursday, October 10 2012

Overscroll is a jQuery Plugin and polyfill for mobile safari's overflow-scrolling style. It is intended for use on desktop browsers, with the latest version of jQuery.

Homepage: http://azoffdesign.com/overscroll

License

Copyright 2012, Jonathan Azoff

Dual licensed under the MIT or GPL Version 2 licenses.

http://jquery.org/license

Usage

$(selector).overscroll([options]);
$(selector).removeOverscroll();

Global Settings

Due to popular demand, overscroll also exposes some of its internal constants for advanced tweaking. You can modify any of these settings via jQuery.fn.overscroll.settings, here are the defaults:

jQuery.fn.overscroll.settings = {
    captureThreshold:   3,   // The number of mouse move events before considering the gesture a "drag"
    driftDecay:         1.1, // The linear-friction coefficient for drift decay (must be > 1)
    driftSequences:     22,  // The number of animation frames to constrain a drift to
    driftTimeout:       100, // The amount of time to imply the user is no longer trying to drift (in ms)
    thumbOpacity:       0.7, // The default active opacity for the thumbs
    thumbThickness:     6,   // The thickness, in pixels, of the generated thumbs
    thumbTimeout:       400, // The amount of time to wait before fading out thumbs
}

Events

Apart from regular DOM events, overscrolled elements emit events to capture dragging and drifting boundaries. To listen to these events, simply listen for one of the following events on an overscrolled element:

Here is an example using jQuery's on() method, listening for drag start:

$('#selector').overscroll().on('overscroll:dragstart', function(){ console.log('Drag started!') });

Notes

In order to get the most out of this plugin, make sure to only apply it to parent elements that are smaller than the collective width and/or height then their children. This way, you can see the actual scroll effect as you pan the element.

While you can programatically control whether or not overscroll allows horizontal and/or vertical scroll, it is best practice to size the child elements accordingly (via CSS) and not depend on programatic restrictions.

As of 1.3.1, if you would like to add click handlers to links inside of overscroll, you can dynamially check the state of the overscrolled element via the jQuery's data() method. This ability should allow you to prevent default behavior of a click handler if a drag state is detected. For example, an overscrolled jQuery element elm can be checked for drag state via elm.data("overscroll").dragging.

As of 1.4.4 you can call the overscroll constructor on a jQuery element as much as you like, without worrying about memory leaks. What this means is that you may dynamically add elements to the overscrolled element, and then re-call the overscroll method to take into account the new height. This would have been done programatically if DOM Elements supported the resize event, alas only the window object supports this event.

A Note About AMD

Full disclosure, I have no interest in supporting AMD. It seems great, I'm sure lots of people use it - but its goals seem tangential to making Overscroll a better plug-in. It's hard enough keeping up with browsers, no sense in making Overscroll anything more than what it is: a jQuery plug-in. If you want to turn Overscroll into an AMD module, than I wholly encourage you to do so! Just fork the project and shoot me a link so that I can reference it here.

Change Log