API Docs for: 3.8.0
Show:

File: scrollview/js/scrollview-base.js

  1. /**
  2.  * The scrollview-base module provides a basic ScrollView Widget, without scrollbar indicators
  3.  *
  4.  * @module scrollview
  5.  * @submodule scrollview-base
  6.  */
  7. var getClassName = Y.ClassNameManager.getClassName,
  8.     DOCUMENT = Y.config.doc,
  9.     WINDOW = Y.config.win,
  10.     IE = Y.UA.ie,
  11.     NATIVE_TRANSITIONS = Y.Transition.useNative,
  12.     vendorPrefix = Y.Transition._VENDOR_PREFIX, // Todo: This is a private property, and alternative approaches should be investigated
  13.     SCROLLVIEW = 'scrollview',
  14.     CLASS_NAMES = {
  15.         vertical: getClassName(SCROLLVIEW, 'vert'),
  16.         horizontal: getClassName(SCROLLVIEW, 'horiz')
  17.     },
  18.     EV_SCROLL_END = 'scrollEnd',
  19.     FLICK = 'flick',
  20.     DRAG = 'drag',
  21.     MOUSEWHEEL = 'mousewheel',
  22.     UI = 'ui',
  23.     TOP = 'top',
  24.     RIGHT = 'right',
  25.     BOTTOM = 'bottom',
  26.     LEFT = 'left',
  27.     PX = 'px',
  28.     AXIS = 'axis',
  29.     SCROLL_Y = 'scrollY',
  30.     SCROLL_X = 'scrollX',
  31.     BOUNCE = 'bounce',
  32.     DISABLED = 'disabled',
  33.     DECELERATION = 'deceleration',
  34.     DIM_X = 'x',
  35.     DIM_Y = 'y',
  36.     BOUNDING_BOX = 'boundingBox',
  37.     CONTENT_BOX = 'contentBox',
  38.     GESTURE_MOVE = 'gesturemove',
  39.     START = 'start',
  40.     END = 'end',
  41.     EMPTY = '',
  42.     ZERO = '0s',
  43.     SNAP_DURATION = 'snapDuration',
  44.     SNAP_EASING = 'snapEasing',
  45.     EASING = 'easing',
  46.     FRAME_DURATION = 'frameDuration',
  47.     BOUNCE_RANGE = 'bounceRange',
  48.    
  49.     _constrain = function (val, min, max) {
  50.         return Math.min(Math.max(val, min), max);
  51.     };

  52. /**
  53.  * ScrollView provides a scrollable widget, supporting flick gestures,
  54.  * across both touch and mouse based devices.
  55.  *
  56.  * @class ScrollView
  57.  * @param config {Object} Object literal with initial attribute values
  58.  * @extends Widget
  59.  * @constructor
  60.  */
  61. function ScrollView() {
  62.     ScrollView.superclass.constructor.apply(this, arguments);
  63. }

  64. Y.ScrollView = Y.extend(ScrollView, Y.Widget, {

  65.     // *** Y.ScrollView prototype

  66.     /**
  67.      * Flag driving whether or not we should try and force H/W acceleration when transforming. Currently enabled by default for Webkit.
  68.      * Used by the _transform method.
  69.      *
  70.      * @property _forceHWTransforms
  71.      * @type boolean
  72.      * @protected
  73.      */
  74.     _forceHWTransforms: Y.UA.webkit ? true : false,

  75.     /**
  76.      * <p>Used to control whether or not ScrollView's internal
  77.      * gesturemovestart, gesturemove and gesturemoveend
  78.      * event listeners should preventDefault. The value is an
  79.      * object, with "start", "move" and "end" properties used to
  80.      * specify which events should preventDefault and which shouldn't:</p>
  81.      *
  82.      * <pre>
  83.      * {
  84.      *    start: false,
  85.      *    move: true,
  86.      *    end: false
  87.      * }
  88.      * </pre>
  89.      *
  90.      * <p>The default values are set up in order to prevent panning,
  91.      * on touch devices, while allowing click listeners on elements inside
  92.      * the ScrollView to be notified as expected.</p>
  93.      *
  94.      * @property _prevent
  95.      * @type Object
  96.      * @protected
  97.      */
  98.     _prevent: {
  99.         start: false,
  100.         move: true,
  101.         end: false
  102.     },

  103.     /**
  104.      * Contains the distance (postive or negative) in pixels by which
  105.      * the scrollview was last scrolled. This is useful when setting up
  106.      * click listeners on the scrollview content, which on mouse based
  107.      * devices are always fired, even after a drag/flick.
  108.      *
  109.      * <p>Touch based devices don't currently fire a click event,
  110.      * if the finger has been moved (beyond a threshold) so this
  111.      * check isn't required, if working in a purely touch based environment</p>
  112.      *
  113.      * @property lastScrolledAmt
  114.      * @type Number
  115.      * @public
  116.      * @default 0
  117.      */
  118.     lastScrolledAmt: 0,

  119.     /**
  120.      * Designated initializer
  121.      *
  122.      * @method initializer
  123.      * @param {config} Configuration object for the plugin
  124.      */
  125.     initializer: function (config) {
  126.         var sv = this;

  127.         // Cache these values, since they aren't going to change.
  128.         sv._bb = sv.get(BOUNDING_BOX);
  129.         sv._cb = sv.get(CONTENT_BOX);

  130.         // Cache some attributes
  131.         sv._cAxis = sv.get(AXIS);
  132.         sv._cBounce = sv.get(BOUNCE);
  133.         sv._cBounceRange = sv.get(BOUNCE_RANGE);
  134.         sv._cDeceleration = sv.get(DECELERATION);
  135.         sv._cFrameDuration = sv.get(FRAME_DURATION);
  136.     },

  137.     /**
  138.      * bindUI implementation
  139.      *
  140.      * Hooks up events for the widget
  141.      * @method bindUI
  142.      */
  143.     bindUI: function () {
  144.         var sv = this;

  145.         // Bind interaction listers
  146.         sv._bindFlick(sv.get(FLICK));
  147.         sv._bindDrag(sv.get(DRAG));
  148.         sv._bindMousewheel(true);
  149.        
  150.         // Bind change events
  151.         sv._bindAttrs();

  152.         // IE SELECT HACK. See if we can do this non-natively and in the gesture for a future release.
  153.         if (IE) {
  154.             sv._fixIESelect(sv._bb, sv._cb);
  155.         }

  156.         // Set any deprecated static properties
  157.         if (ScrollView.SNAP_DURATION) {
  158.             sv.set(SNAP_DURATION, ScrollView.SNAP_DURATION);
  159.         }

  160.         if (ScrollView.SNAP_EASING) {
  161.             sv.set(SNAP_EASING, ScrollView.SNAP_EASING);
  162.         }

  163.         if (ScrollView.EASING) {
  164.             sv.set(EASING, ScrollView.EASING);
  165.         }

  166.         if (ScrollView.FRAME_STEP) {
  167.             sv.set(FRAME_DURATION, ScrollView.FRAME_STEP);
  168.         }

  169.         if (ScrollView.BOUNCE_RANGE) {
  170.             sv.set(BOUNCE_RANGE, ScrollView.BOUNCE_RANGE);
  171.         }

  172.         // Recalculate dimension properties
  173.         // TODO: This should be throttled.
  174.         // Y.one(WINDOW).after('resize', sv._afterDimChange, sv);
  175.     },

  176.     /**
  177.      * Bind event listeners
  178.      *
  179.      * @method _bindAttrs
  180.      * @private
  181.      */
  182.     _bindAttrs: function () {
  183.         var sv = this,
  184.             scrollChangeHandler = sv._afterScrollChange,
  185.             dimChangeHandler = sv._afterDimChange;

  186.         // Bind any change event listeners
  187.         sv.after({
  188.             'scrollEnd': sv._afterScrollEnd,
  189.             'disabledChange': sv._afterDisabledChange,
  190.             'flickChange': sv._afterFlickChange,
  191.             'dragChange': sv._afterDragChange,
  192.             'axisChange': sv._afterAxisChange,
  193.             'scrollYChange': scrollChangeHandler,
  194.             'scrollXChange': scrollChangeHandler,
  195.             'heightChange': dimChangeHandler,
  196.             'widthChange': dimChangeHandler
  197.         });
  198.     },

  199.     /**
  200.      * Bind (or unbind) gesture move listeners required for drag support
  201.      *
  202.      * @method _bindDrag
  203.      * @param drag {boolean} If true, the method binds listener to enable drag (gesturemovestart). If false, the method unbinds gesturemove listeners for drag support.
  204.      * @private
  205.      */
  206.     _bindDrag: function (drag) {
  207.         var sv = this,
  208.             bb = sv._bb;

  209.         // Unbind any previous 'drag' listeners
  210.         bb.detach(DRAG + '|*');

  211.         if (drag) {
  212.             bb.on(DRAG + '|' + GESTURE_MOVE + START, Y.bind(sv._onGestureMoveStart, sv));
  213.         }
  214.     },

  215.     /**
  216.      * Bind (or unbind) flick listeners.
  217.      *
  218.      * @method _bindFlick
  219.      * @param flick {Object|boolean} If truthy, the method binds listeners for flick support. If false, the method unbinds flick listeners.
  220.      * @private
  221.      */
  222.     _bindFlick: function (flick) {
  223.         var sv = this,
  224.             bb = sv._bb;

  225.         // Unbind any previous 'flick' listeners
  226.         bb.detach(FLICK + '|*');

  227.         if (flick) {
  228.             bb.on(FLICK + '|' + FLICK, Y.bind(sv._flick, sv), flick);

  229.             // Rebind Drag, becuase _onGestureMoveEnd always has to fire -after- _flick
  230.             sv._bindDrag(sv.get(DRAG));
  231.         }
  232.     },

  233.     /**
  234.      * Bind (or unbind) mousewheel listeners.
  235.      *
  236.      * @method _bindMousewheel
  237.      * @param mousewheel {Object|boolean} If truthy, the method binds listeners for mousewheel support. If false, the method unbinds mousewheel listeners.
  238.      * @private
  239.      */
  240.     _bindMousewheel: function (mousewheel) {
  241.         var sv = this,
  242.             bb = sv._bb;

  243.         // Unbind any previous 'mousewheel' listeners
  244.         // TODO: This doesn't actually appear to work properly. Fix. #2532743
  245.         bb.detach(MOUSEWHEEL + '|*');

  246.         // Only enable for vertical scrollviews
  247.         if (mousewheel) {
  248.             // Bound to document, because that's where mousewheel events fire off of.
  249.             Y.one(DOCUMENT).on(MOUSEWHEEL, Y.bind(sv._mousewheel, sv));
  250.         }
  251.     },

  252.     /**
  253.      * syncUI implementation.
  254.      *
  255.      * Update the scroll position, based on the current value of scrollX/scrollY.
  256.      *
  257.      * @method syncUI
  258.      */
  259.     syncUI: function () {
  260.         var sv = this,
  261.             scrollDims = sv._getScrollDims(),
  262.             width = scrollDims.offsetWidth,
  263.             height = scrollDims.offsetHeight,
  264.             scrollWidth = scrollDims.scrollWidth,
  265.             scrollHeight = scrollDims.scrollHeight;

  266.         // If the axis is undefined, auto-calculate it
  267.         if (sv._cAxis === undefined) {
  268.             // This should only ever be run once (for now).
  269.             // In the future SV might post-load axis changes
  270.             sv._cAxis = {
  271.                 x: (scrollWidth > width),
  272.                 y: (scrollHeight > height)
  273.             };

  274.             sv._set(AXIS, sv._cAxis);
  275.         }
  276.        
  277.         // get text direction on or inherited by scrollview node
  278.         sv.rtl = (sv._cb.getComputedStyle('direction') === 'rtl');

  279.         // Cache the disabled value
  280.         sv._cDisabled = sv.get(DISABLED);

  281.         // Run this to set initial values
  282.         sv._uiDimensionsChange();

  283.         // If we're out-of-bounds, snap back.
  284.         if (sv._isOutOfBounds()) {
  285.             sv._snapBack();
  286.         }
  287.     },

  288.     /**
  289.      * Utility method to obtain widget dimensions
  290.      *
  291.      * @method _getScrollDims
  292.      * @returns {Object} The offsetWidth, offsetHeight, scrollWidth and scrollHeight as an array: [offsetWidth, offsetHeight, scrollWidth, scrollHeight]
  293.      * @private
  294.      */
  295.     _getScrollDims: function () {
  296.         var sv = this,
  297.             cb = sv._cb,
  298.             bb = sv._bb,
  299.             TRANS = ScrollView._TRANSITION,
  300.             // Ideally using CSSMatrix - don't think we have it normalized yet though.
  301.             // origX = (new WebKitCSSMatrix(cb.getComputedStyle("transform"))).e,
  302.             // origY = (new WebKitCSSMatrix(cb.getComputedStyle("transform"))).f,
  303.             origX = sv.get(SCROLL_X),
  304.             origY = sv.get(SCROLL_Y),
  305.             origHWTransform,
  306.             dims;

  307.         // TODO: Is this OK? Just in case it's called 'during' a transition.
  308.         if (NATIVE_TRANSITIONS) {
  309.             cb.setStyle(TRANS.DURATION, ZERO);
  310.             cb.setStyle(TRANS.PROPERTY, EMPTY);
  311.         }

  312.         origHWTransform = sv._forceHWTransforms;
  313.         sv._forceHWTransforms = false; // the z translation was causing issues with picking up accurate scrollWidths in Chrome/Mac.

  314.         sv._moveTo(cb, 0, 0);
  315.         dims = {
  316.             'offsetWidth': bb.get('offsetWidth'),
  317.             'offsetHeight': bb.get('offsetHeight'),
  318.             'scrollWidth': bb.get('scrollWidth'),
  319.             'scrollHeight': bb.get('scrollHeight')
  320.         };
  321.         sv._moveTo(cb, -(origX), -(origY));

  322.         sv._forceHWTransforms = origHWTransform;

  323.         return dims;
  324.     },

  325.     /**
  326.      * This method gets invoked whenever the height or width attributes change,
  327.      * allowing us to determine which scrolling axes need to be enabled.
  328.      *
  329.      * @method _uiDimensionsChange
  330.      * @protected
  331.      */
  332.     _uiDimensionsChange: function () {
  333.         var sv = this,
  334.             bb = sv._bb,
  335.             scrollDims = sv._getScrollDims(),
  336.             width = scrollDims.offsetWidth,
  337.             height = scrollDims.offsetHeight,
  338.             scrollWidth = scrollDims.scrollWidth,
  339.             scrollHeight = scrollDims.scrollHeight,
  340.             rtl = sv.rtl,
  341.             svAxis = sv._cAxis;
  342.            
  343.         if (svAxis && svAxis.x) {
  344.             bb.addClass(CLASS_NAMES.horizontal);
  345.         }

  346.         if (svAxis && svAxis.y) {
  347.             bb.addClass(CLASS_NAMES.vertical);
  348.         }

  349.         /**
  350.          * Internal state, defines the minimum amount that the scrollview can be scrolled along the X axis
  351.          *
  352.          * @property _minScrollX
  353.          * @type number
  354.          * @protected
  355.          */
  356.         sv._minScrollX = (rtl) ? Math.min(0, -(scrollWidth - width)) : 0;

  357.         /**
  358.          * Internal state, defines the maximum amount that the scrollview can be scrolled along the X axis
  359.          *
  360.          * @property _maxScrollX
  361.          * @type number
  362.          * @protected
  363.          */
  364.         sv._maxScrollX = (rtl) ? 0 : Math.max(0, scrollWidth - width);

  365.         /**
  366.          * Internal state, defines the minimum amount that the scrollview can be scrolled along the Y axis
  367.          *
  368.          * @property _minScrollY
  369.          * @type number
  370.          * @protected
  371.          */
  372.         sv._minScrollY = 0;

  373.         /**
  374.          * Internal state, defines the maximum amount that the scrollview can be scrolled along the Y axis
  375.          *
  376.          * @property _maxScrollY
  377.          * @type number
  378.          * @protected
  379.          */
  380.         sv._maxScrollY = Math.max(0, scrollHeight - height);
  381.     },

  382.     /**
  383.      * Scroll the element to a given xy coordinate
  384.      *
  385.      * @method scrollTo
  386.      * @param x {Number} The x-position to scroll to. (null for no movement)
  387.      * @param y {Number} The y-position to scroll to. (null for no movement)
  388.      * @param {Number} [duration] ms of the scroll animation. (default is 0)
  389.      * @param {String} [easing] An easing equation if duration is set. (default is `easing` attribute)
  390.      * @param {String} [node] The node to transform.  Setting this can be useful in dual-axis paginated instances. (default is the instance's contentBox)
  391.      */
  392.     scrollTo: function (x, y, duration, easing, node) {
  393.         // Check to see if widget is disabled
  394.         if (this._cDisabled) {
  395.             return;
  396.         }

  397.         var sv = this,
  398.             cb = sv._cb,
  399.             TRANS = ScrollView._TRANSITION,
  400.             callback = Y.bind(sv._onTransEnd, sv), // @Todo : cache this
  401.             newX = 0,
  402.             newY = 0,
  403.             transition = {},
  404.             transform;

  405.         // default the optional arguments
  406.         duration = duration || 0;
  407.         easing = easing || sv.get(EASING); // @TODO: Cache this
  408.         node = node || cb;

  409.         if (x !== null) {
  410.             sv.set(SCROLL_X, x, {src:UI});
  411.             newX = -(x);
  412.         }

  413.         if (y !== null) {
  414.             sv.set(SCROLL_Y, y, {src:UI});
  415.             newY = -(y);
  416.         }

  417.         transform = sv._transform(newX, newY);

  418.         if (NATIVE_TRANSITIONS) {
  419.             // ANDROID WORKAROUND - try and stop existing transition, before kicking off new one.
  420.             node.setStyle(TRANS.DURATION, ZERO).setStyle(TRANS.PROPERTY, EMPTY);
  421.         }

  422.         // Move
  423.         if (duration === 0) {
  424.             if (NATIVE_TRANSITIONS) {
  425.                 node.setStyle('transform', transform);
  426.             }
  427.             else {
  428.                 // TODO: If both set, batch them in the same update
  429.                 // Update: Nope, setStyles() just loops through each property and applies it.
  430.                 if (x !== null) {
  431.                     node.setStyle(LEFT, newX + PX);
  432.                 }
  433.                 if (y !== null) {
  434.                     node.setStyle(TOP, newY + PX);
  435.                 }
  436.             }
  437.         }

  438.         // Animate
  439.         else {
  440.             transition.easing = easing;
  441.             transition.duration = duration / 1000;

  442.             if (NATIVE_TRANSITIONS) {
  443.                 transition.transform = transform;
  444.             }
  445.             else {
  446.                 transition.left = newX + PX;
  447.                 transition.top = newY + PX;
  448.             }

  449.             node.transition(transition, callback);
  450.         }
  451.     },

  452.     /**
  453.      * Utility method, to create the translate transform string with the
  454.      * x, y translation amounts provided.
  455.      *
  456.      * @method _transform
  457.      * @param {Number} x Number of pixels to translate along the x axis
  458.      * @param {Number} y Number of pixels to translate along the y axis
  459.      * @private
  460.      */
  461.     _transform: function (x, y) {
  462.         // TODO: Would we be better off using a Matrix for this?
  463.         var prop = 'translate(' + x + 'px, ' + y + 'px)';

  464.         if (this._forceHWTransforms) {
  465.             prop += ' translateZ(0)';
  466.         }

  467.         return prop;
  468.     },

  469.     /**
  470.     * Utility method, to move the given element to the given xy position
  471.     *
  472.     * @method _moveTo
  473.     * @param node {Node} The node to move
  474.     * @param x {Number} The x-position to move to
  475.     * @param y {Number} The y-position to move to
  476.     * @private
  477.     */
  478.     _moveTo : function(node, x, y) {
  479.         if (NATIVE_TRANSITIONS) {
  480.             node.setStyle('transform', this._transform(x, y));
  481.         } else {
  482.             node.setStyle(LEFT, x + PX);
  483.             node.setStyle(TOP, y + PX);
  484.         }
  485.     },


  486.     /**
  487.      * Content box transition callback
  488.      *
  489.      * @method _onTransEnd
  490.      * @param {Event.Facade} e The event facade
  491.      * @private
  492.      */
  493.     _onTransEnd: function (e) {
  494.         var sv = this;

  495.         /**
  496.          * Notification event fired at the end of a scroll transition
  497.          *
  498.          * @event scrollEnd
  499.          * @param e {EventFacade} The default event facade.
  500.          */
  501.         sv.fire(EV_SCROLL_END);
  502.     },

  503.     /**
  504.      * gesturemovestart event handler
  505.      *
  506.      * @method _onGestureMoveStart
  507.      * @param e {Event.Facade} The gesturemovestart event facade
  508.      * @private
  509.      */
  510.     _onGestureMoveStart: function (e) {

  511.         if (this._cDisabled) {
  512.             return false;
  513.         }

  514.         var sv = this,
  515.             bb = sv._bb,
  516.             currentX = sv.get(SCROLL_X),
  517.             currentY = sv.get(SCROLL_Y),
  518.             clientX = e.clientX,
  519.             clientY = e.clientY;

  520.         if (sv._prevent.start) {
  521.             e.preventDefault();
  522.         }

  523.         // if a flick animation is in progress, cancel it
  524.         if (sv._flickAnim) {
  525.             // Cancel and delete sv._flickAnim
  526.             sv._flickAnim.cancel();
  527.             delete sv._flickAnim;
  528.             sv._onTransEnd();
  529.         }

  530.         // TODO: Review if neccesary (#2530129)
  531.         e.stopPropagation();

  532.         // Reset lastScrolledAmt
  533.         sv.lastScrolledAmt = 0;

  534.         // Stores data for this gesture cycle.  Cleaned up later
  535.         sv._gesture = {

  536.             // Will hold the axis value
  537.             axis: null,

  538.             // The current attribute values
  539.             startX: currentX,
  540.             startY: currentY,

  541.             // The X/Y coordinates where the event began
  542.             startClientX: clientX,
  543.             startClientY: clientY,

  544.             // The X/Y coordinates where the event will end
  545.             endClientX: null,
  546.             endClientY: null,

  547.             // The current delta of the event
  548.             deltaX: null,
  549.             deltaY: null,

  550.             // Will be populated for flicks
  551.             flick: null,

  552.             // Create some listeners for the rest of the gesture cycle
  553.             onGestureMove: bb.on(DRAG + '|' + GESTURE_MOVE, Y.bind(sv._onGestureMove, sv)),
  554.            
  555.             // @TODO: Don't bind gestureMoveEnd if it's a Flick?
  556.             onGestureMoveEnd: bb.on(DRAG + '|' + GESTURE_MOVE + END, Y.bind(sv._onGestureMoveEnd, sv))
  557.         };
  558.     },

  559.     /**
  560.      * gesturemove event handler
  561.      *
  562.      * @method _onGestureMove
  563.      * @param e {Event.Facade} The gesturemove event facade
  564.      * @private
  565.      */
  566.     _onGestureMove: function (e) {
  567.         var sv = this,
  568.             gesture = sv._gesture,
  569.             svAxis = sv._cAxis,
  570.             svAxisX = svAxis.x,
  571.             svAxisY = svAxis.y,
  572.             startX = gesture.startX,
  573.             startY = gesture.startY,
  574.             startClientX = gesture.startClientX,
  575.             startClientY = gesture.startClientY,
  576.             clientX = e.clientX,
  577.             clientY = e.clientY;

  578.         if (sv._prevent.move) {
  579.             e.preventDefault();
  580.         }

  581.         gesture.deltaX = startClientX - clientX;
  582.         gesture.deltaY = startClientY - clientY;

  583.         // Determine if this is a vertical or horizontal movement
  584.         // @TODO: This is crude, but it works.  Investigate more intelligent ways to detect intent
  585.         if (gesture.axis === null) {
  586.             gesture.axis = (Math.abs(gesture.deltaX) > Math.abs(gesture.deltaY)) ? DIM_X : DIM_Y;
  587.         }

  588.         // Move X or Y.  @TODO: Move both if dualaxis.        
  589.         if (gesture.axis === DIM_X && svAxisX) {
  590.             sv.set(SCROLL_X, startX + gesture.deltaX);
  591.         }
  592.         else if (gesture.axis === DIM_Y && svAxisY) {
  593.             sv.set(SCROLL_Y, startY + gesture.deltaY);
  594.         }
  595.     },

  596.     /**
  597.      * gesturemoveend event handler
  598.      *
  599.      * @method _onGestureMoveEnd
  600.      * @param e {Event.Facade} The gesturemoveend event facade
  601.      * @private
  602.      */
  603.     _onGestureMoveEnd: function (e) {
  604.         var sv = this,
  605.             gesture = sv._gesture,
  606.             flick = gesture.flick,
  607.             clientX = e.clientX,
  608.             clientY = e.clientY;

  609.         if (sv._prevent.end) {
  610.             e.preventDefault();
  611.         }

  612.         // Store the end X/Y coordinates
  613.         gesture.endClientX = clientX;
  614.         gesture.endClientY = clientY;

  615.         // Cleanup the event handlers
  616.         gesture.onGestureMove.detach();
  617.         gesture.onGestureMoveEnd.detach();

  618.         // If this wasn't a flick, wrap up the gesture cycle
  619.         if (!flick) {
  620.             // @TODO: Be more intelligent about this. Look at the Flick attribute to see
  621.             // if it is safe to assume _flick did or didn't fire.  
  622.             // Then, the order _flick and _onGestureMoveEnd fire doesn't matter?

  623.             // If there was movement (_onGestureMove fired)
  624.             if (gesture.deltaX !== null && gesture.deltaY !== null) {

  625.                 // If we're out-out-bounds, then snapback
  626.                 if (sv._isOutOfBounds()) {
  627.                     sv._snapBack();
  628.                 }

  629.                 // Inbounds
  630.                 else {
  631.                     // Don't fire scrollEnd on the gesture axis is the same as paginator's
  632.                     // Not totally confident this is ideal to access a plugin's properties from a host, @TODO revisit
  633.                     if (sv.pages && !sv.pages.get(AXIS)[gesture.axis]) {
  634.                         sv._onTransEnd();
  635.                     }
  636.                 }
  637.             }
  638.         }
  639.     },

  640.     /**
  641.      * Execute a flick at the end of a scroll action
  642.      *
  643.      * @method _flick
  644.      * @param e {Event.Facade} The Flick event facade
  645.      * @private
  646.      */
  647.     _flick: function (e) {
  648.         if (this._cDisabled) {
  649.             return false;
  650.         }

  651.         var sv = this,
  652.             svAxis = sv._cAxis,
  653.             flick = e.flick,
  654.             flickAxis = flick.axis,
  655.             flickVelocity = flick.velocity,
  656.             axisAttr = flickAxis === DIM_X ? SCROLL_X : SCROLL_Y,
  657.             startPosition = sv.get(axisAttr);

  658.         // Sometimes flick is enabled, but drag is disabled
  659.         if (sv._gesture) {
  660.             sv._gesture.flick = flick;
  661.         }

  662.         // Prevent unneccesary firing of _flickFrame if we can't scroll on the flick axis
  663.         if (svAxis[flickAxis]) {
  664.             sv._flickFrame(flickVelocity, flickAxis, startPosition);
  665.         }
  666.     },

  667.     /**
  668.      * Execute a single frame in the flick animation
  669.      *
  670.      * @method _flickFrame
  671.      * @param velocity {Number} The velocity of this animated frame
  672.      * @param flickAxis {String} The axis on which to animate
  673.      * @param startPosition {Number} The starting X/Y point to flick from
  674.      * @protected
  675.      */
  676.     _flickFrame: function (velocity, flickAxis, startPosition) {

  677.         var sv = this,
  678.             axisAttr = flickAxis === DIM_X ? SCROLL_X : SCROLL_Y,

  679.             // Localize cached values
  680.             bounce = sv._cBounce,
  681.             bounceRange = sv._cBounceRange,
  682.             deceleration = sv._cDeceleration,
  683.             frameDuration = sv._cFrameDuration,

  684.             // Calculate
  685.             newVelocity = velocity * deceleration,
  686.             newPosition = startPosition - (frameDuration * newVelocity),

  687.             // Some convinience conditions
  688.             min = flickAxis === DIM_X ? sv._minScrollX : sv._minScrollY,
  689.             max = flickAxis === DIM_X ? sv._maxScrollX : sv._maxScrollY,
  690.             belowMin       = (newPosition < min),
  691.             belowMax       = (newPosition < max),
  692.             aboveMin       = (newPosition > min),
  693.             aboveMax       = (newPosition > max),
  694.             belowMinRange  = (newPosition < (min - bounceRange)),
  695.             belowMaxRange  = (newPosition < (max + bounceRange)),
  696.             withinMinRange = (belowMin && (newPosition > (min - bounceRange))),
  697.             withinMaxRange = (aboveMax && (newPosition < (max + bounceRange))),
  698.             aboveMinRange  = (newPosition > (min - bounceRange)),
  699.             aboveMaxRange  = (newPosition > (max + bounceRange)),
  700.             tooSlow;

  701.         // If we're within the range but outside min/max, dampen the velocity
  702.         if (withinMinRange || withinMaxRange) {
  703.             newVelocity *= bounce;
  704.         }

  705.         // Is the velocity too slow to bother?
  706.         tooSlow = (Math.abs(newVelocity).toFixed(4) < 0.015);

  707.         // If the velocity is too slow or we're outside the range
  708.         if (tooSlow || belowMinRange || aboveMaxRange) {
  709.             // Cancel and delete sv._flickAnim
  710.             if (sv._flickAnim) {
  711.                 sv._flickAnim.cancel();
  712.                 delete sv._flickAnim;
  713.             }

  714.             // If we're inside the scroll area, just end
  715.             if (aboveMin && belowMax) {
  716.                 sv._onTransEnd();
  717.             }

  718.             // We're outside the scroll area, so we need to snap back
  719.             else {
  720.                 sv._snapBack();
  721.             }
  722.         }

  723.         // Otherwise, animate to the next frame
  724.         else {
  725.             // @TODO: maybe use requestAnimationFrame instead
  726.             sv._flickAnim = Y.later(frameDuration, sv, '_flickFrame', [newVelocity, flickAxis, newPosition]);
  727.             sv.set(axisAttr, newPosition);
  728.         }
  729.     },

  730.     /**
  731.      * Handle mousewheel events on the widget
  732.      *
  733.      * @method _mousewheel
  734.      * @param e {Event.Facade} The mousewheel event facade
  735.      * @private
  736.      */
  737.     _mousewheel: function (e) {
  738.         var sv = this,
  739.             scrollY = sv.get(SCROLL_Y),
  740.             bb = sv._bb,
  741.             scrollOffset = 10, // 10px
  742.             isForward = (e.wheelDelta > 0),
  743.             scrollToY = scrollY - ((isForward ? 1 : -1) * scrollOffset);

  744.         scrollToY = _constrain(scrollToY, sv._minScrollY, sv._maxScrollY);

  745.         // Because Mousewheel events fire off 'document', every ScrollView widget will react
  746.         // to any mousewheel anywhere on the page. This check will ensure that the mouse is currently
  747.         // over this specific ScrollView.  Also, only allow mousewheel scrolling on Y-axis,
  748.         // becuase otherwise the 'prevent' will block page scrolling.
  749.         if (bb.contains(e.target) && sv._cAxis[DIM_Y]) {

  750.             // Reset lastScrolledAmt
  751.             sv.lastScrolledAmt = 0;

  752.             // Jump to the new offset
  753.             sv.set(SCROLL_Y, scrollToY);

  754.             // if we have scrollbars plugin, update & set the flash timer on the scrollbar
  755.             // @TODO: This probably shouldn't be in this module
  756.             if (sv.scrollbars) {
  757.                 // @TODO: The scrollbars should handle this themselves
  758.                 sv.scrollbars._update();
  759.                 sv.scrollbars.flash();
  760.                 // or just this
  761.                 // sv.scrollbars._hostDimensionsChange();
  762.             }

  763.             // Fire the 'scrollEnd' event
  764.             sv._onTransEnd();

  765.             // prevent browser default behavior on mouse scroll
  766.             e.preventDefault();
  767.         }
  768.     },

  769.     /**
  770.      * Checks to see the current scrollX/scrollY position beyond the min/max boundary
  771.      *
  772.      * @method _isOutOfBounds
  773.      * @param x {Number} [optional] The X position to check
  774.      * @param y {Number} [optional] The Y position to check
  775.      * @returns {boolen} Whether the current X/Y position is out of bounds (true) or not (false)
  776.      * @private
  777.      */
  778.     _isOutOfBounds: function (x, y) {
  779.         var sv = this,
  780.             svAxis = sv._cAxis,
  781.             svAxisX = svAxis.x,
  782.             svAxisY = svAxis.y,
  783.             currentX = x || sv.get(SCROLL_X),
  784.             currentY = y || sv.get(SCROLL_Y),
  785.             minX = sv._minScrollX,
  786.             minY = sv._minScrollY,
  787.             maxX = sv._maxScrollX,
  788.             maxY = sv._maxScrollY;

  789.         return (svAxisX && (currentX < minX || currentX > maxX)) || (svAxisY && (currentY < minY || currentY > maxY));
  790.     },

  791.     /**
  792.      * Bounces back
  793.      * @TODO: Should be more generalized and support both X and Y detection
  794.      *
  795.      * @method _snapBack
  796.      * @private
  797.      */
  798.     _snapBack: function () {
  799.         var sv = this,
  800.             currentX = sv.get(SCROLL_X),
  801.             currentY = sv.get(SCROLL_Y),
  802.             minX = sv._minScrollX,
  803.             minY = sv._minScrollY,
  804.             maxX = sv._maxScrollX,
  805.             maxY = sv._maxScrollY,
  806.             newY = _constrain(currentY, minY, maxY),
  807.             newX = _constrain(currentX, minX, maxX),
  808.             duration = sv.get(SNAP_DURATION),
  809.             easing = sv.get(SNAP_EASING);

  810.         if (newX !== currentX) {
  811.             sv.set(SCROLL_X, newX, {duration:duration, easing:easing});
  812.         }
  813.         else if (newY !== currentY) {
  814.             sv.set(SCROLL_Y, newY, {duration:duration, easing:easing});
  815.         }
  816.         else {
  817.             // It shouldn't ever get here, but in case it does, fire scrollEnd
  818.             sv._onTransEnd();
  819.         }
  820.     },

  821.     /**
  822.      * After listener for changes to the scrollX or scrollY attribute
  823.      *
  824.      * @method _afterScrollChange
  825.      * @param e {Event.Facade} The event facade
  826.      * @protected
  827.      */
  828.     _afterScrollChange: function (e) {

  829.         if (e.src === ScrollView.UI_SRC) {
  830.             return false;
  831.         }

  832.         var sv = this,
  833.             duration = e.duration,
  834.             easing = e.easing,
  835.             val = e.newVal,
  836.             scrollToArgs = [];

  837.         // Set the scrolled value
  838.         sv.lastScrolledAmt = sv.lastScrolledAmt + (e.newVal - e.prevVal);

  839.         // Generate the array of args to pass to scrollTo()
  840.         if (e.attrName === SCROLL_X) {
  841.             scrollToArgs.push(val);
  842.             scrollToArgs.push(sv.get(SCROLL_Y));
  843.         }
  844.         else {
  845.             scrollToArgs.push(sv.get(SCROLL_X));
  846.             scrollToArgs.push(val);
  847.         }

  848.         scrollToArgs.push(duration);
  849.         scrollToArgs.push(easing);

  850.         sv.scrollTo.apply(sv, scrollToArgs);
  851.     },

  852.     /**
  853.      * After listener for changes to the flick attribute
  854.      *
  855.      * @method _afterFlickChange
  856.      * @param e {Event.Facade} The event facade
  857.      * @protected
  858.      */
  859.     _afterFlickChange: function (e) {
  860.         this._bindFlick(e.newVal);
  861.     },

  862.     /**
  863.      * After listener for changes to the disabled attribute
  864.      *
  865.      * @method _afterDisabledChange
  866.      * @param e {Event.Facade} The event facade
  867.      * @protected
  868.      */
  869.     _afterDisabledChange: function (e) {
  870.         // Cache for performance - we check during move
  871.         this._cDisabled = e.newVal;
  872.     },

  873.     /**
  874.      * After listener for the axis attribute
  875.      *
  876.      * @method _afterAxisChange
  877.      * @param e {Event.Facade} The event facade
  878.      * @protected
  879.      */
  880.     _afterAxisChange: function (e) {
  881.         this._cAxis = e.newVal;
  882.     },

  883.     /**
  884.      * After listener for changes to the drag attribute
  885.      *
  886.      * @method _afterDragChange
  887.      * @param e {Event.Facade} The event facade
  888.      * @protected
  889.      */
  890.     _afterDragChange: function (e) {
  891.         this._bindDrag(e.newVal);
  892.     },

  893.     /**
  894.      * After listener for the height or width attribute
  895.      *
  896.      * @method _afterDimChange
  897.      * @param e {Event.Facade} The event facade
  898.      * @protected
  899.      */
  900.     _afterDimChange: function () {
  901.         this._uiDimensionsChange();
  902.     },

  903.     /**
  904.      * After listener for scrollEnd, for cleanup
  905.      *
  906.      * @method _afterScrollEnd
  907.      * @param e {Event.Facade} The event facade
  908.      * @protected
  909.      */
  910.     _afterScrollEnd: function (e) {
  911.         var sv = this;

  912.         // @TODO: Move to sv._cancelFlick()
  913.         if (sv._flickAnim) {
  914.             // Cancel the flick (if it exists)
  915.             sv._flickAnim.cancel();

  916.             // Also delete it, otherwise _onGestureMoveStart will think we're still flicking
  917.             delete sv._flickAnim;
  918.         }

  919.         // If for some reason we're OOB, snapback
  920.         if (sv._isOutOfBounds()) {
  921.             sv._snapBack();
  922.         }

  923.         // Ideally this should be removed, but doing so causing some JS errors with fast swiping
  924.         // because _gesture is being deleted after the previous one has been overwritten
  925.         // delete sv._gesture; // TODO: Move to sv.prevGesture?
  926.     },

  927.     /**
  928.      * Setter for 'axis' attribute
  929.      *
  930.      * @method _axisSetter
  931.      * @param val {Mixed} A string ('x', 'y', 'xy') to specify which axis/axes to allow scrolling on
  932.      * @param name {String} The attribute name
  933.      * @return {Object} An object to specify scrollability on the x & y axes
  934.      *
  935.      * @protected
  936.      */
  937.     _axisSetter: function (val, name) {

  938.         // Turn a string into an axis object
  939.         if (Y.Lang.isString(val)) {
  940.             return {
  941.                 x: val.match(/x/i) ? true : false,
  942.                 y: val.match(/y/i) ? true : false
  943.             };
  944.         }
  945.     },
  946.    
  947.     /**
  948.     * The scrollX, scrollY setter implementation
  949.     *
  950.     * @method _setScroll
  951.     * @private
  952.     * @param {Number} val
  953.     * @param {String} dim
  954.     *
  955.     * @return {Number} The value
  956.     */
  957.     _setScroll : function(val, dim) {

  958.         // Just ensure the widget is not disabled
  959.         if (this._cDisabled) {
  960.             val = Y.Attribute.INVALID_VALUE;
  961.         }

  962.         return val;
  963.     },

  964.     /**
  965.     * Setter for the scrollX attribute
  966.     *
  967.     * @method _setScrollX
  968.     * @param val {Number} The new scrollX value
  969.     * @return {Number} The normalized value
  970.     * @protected
  971.     */
  972.     _setScrollX: function(val) {
  973.         return this._setScroll(val, DIM_X);
  974.     },

  975.     /**
  976.     * Setter for the scrollY ATTR
  977.     *
  978.     * @method _setScrollY
  979.     * @param val {Number} The new scrollY value
  980.     * @return {Number} The normalized value
  981.     * @protected
  982.     */
  983.     _setScrollY: function(val) {
  984.         return this._setScroll(val, DIM_Y);
  985.     }

  986.     // End prototype properties

  987. }, {

  988.     // Static properties

  989.     /**
  990.      * The identity of the widget.
  991.      *
  992.      * @property NAME
  993.      * @type String
  994.      * @default 'scrollview'
  995.      * @readOnly
  996.      * @protected
  997.      * @static
  998.      */
  999.     NAME: 'scrollview',

  1000.     /**
  1001.      * Static property used to define the default attribute configuration of
  1002.      * the Widget.
  1003.      *
  1004.      * @property ATTRS
  1005.      * @type {Object}
  1006.      * @protected
  1007.      * @static
  1008.      */
  1009.     ATTRS: {

  1010.         /**
  1011.          * Specifies ability to scroll on x, y, or x and y axis/axes.
  1012.          *
  1013.          * @attribute axis
  1014.          * @type String
  1015.          */
  1016.         axis: {
  1017.             setter: '_axisSetter',
  1018.             writeOnce: 'initOnly'
  1019.         },

  1020.         /**
  1021.          * The current scroll position in the x-axis
  1022.          *
  1023.          * @attribute scrollX
  1024.          * @type Number
  1025.          * @default 0
  1026.          */
  1027.         scrollX: {
  1028.             value: 0,
  1029.             setter: '_setScrollX'
  1030.         },

  1031.         /**
  1032.          * The current scroll position in the y-axis
  1033.          *
  1034.          * @attribute scrollY
  1035.          * @type Number
  1036.          * @default 0
  1037.          */
  1038.         scrollY: {
  1039.             value: 0,
  1040.             setter: '_setScrollY'
  1041.         },

  1042.         /**
  1043.          * Drag coefficent for inertial scrolling. The closer to 1 this
  1044.          * value is, the less friction during scrolling.
  1045.          *
  1046.          * @attribute deceleration
  1047.          * @default 0.93
  1048.          */
  1049.         deceleration: {
  1050.             value: 0.93
  1051.         },

  1052.         /**
  1053.          * Drag coefficient for intertial scrolling at the upper
  1054.          * and lower boundaries of the scrollview. Set to 0 to
  1055.          * disable "rubber-banding".
  1056.          *
  1057.          * @attribute bounce
  1058.          * @type Number
  1059.          * @default 0.1
  1060.          */
  1061.         bounce: {
  1062.             value: 0.1
  1063.         },

  1064.         /**
  1065.          * The minimum distance and/or velocity which define a flick. Can be set to false,
  1066.          * to disable flick support (note: drag support is enabled/disabled separately)
  1067.          *
  1068.          * @attribute flick
  1069.          * @type Object
  1070.          * @default Object with properties minDistance = 10, minVelocity = 0.3.
  1071.          */
  1072.         flick: {
  1073.             value: {
  1074.                 minDistance: 10,
  1075.                 minVelocity: 0.3
  1076.             }
  1077.         },

  1078.         /**
  1079.          * Enable/Disable dragging the ScrollView content (note: flick support is enabled/disabled separately)
  1080.          * @attribute drag
  1081.          * @type boolean
  1082.          * @default true
  1083.          */
  1084.         drag: {
  1085.             value: true
  1086.         },

  1087.         /**
  1088.          * The default duration to use when animating the bounce snap back.
  1089.          *
  1090.          * @attribute snapDuration
  1091.          * @type Number
  1092.          * @default 400
  1093.          */
  1094.         snapDuration: {
  1095.             value: 400
  1096.         },

  1097.         /**
  1098.          * The default easing to use when animating the bounce snap back.
  1099.          *
  1100.          * @attribute snapEasing
  1101.          * @type String
  1102.          * @default 'ease-out'
  1103.          */
  1104.         snapEasing: {
  1105.             value: 'ease-out'
  1106.         },

  1107.         /**
  1108.          * The default easing used when animating the flick
  1109.          *
  1110.          * @attribute easing
  1111.          * @type String
  1112.          * @default 'cubic-bezier(0, 0.1, 0, 1.0)'
  1113.          */
  1114.         easing: {
  1115.             value: 'cubic-bezier(0, 0.1, 0, 1.0)'
  1116.         },

  1117.         /**
  1118.          * The interval (ms) used when animating the flick for JS-timer animations
  1119.          *
  1120.          * @attribute frameDuration
  1121.          * @type Number
  1122.          * @default 15
  1123.          */
  1124.         frameDuration: {
  1125.             value: 15
  1126.         },

  1127.         /**
  1128.          * The default bounce distance in pixels
  1129.          *
  1130.          * @attribute bounceRange
  1131.          * @type Number
  1132.          * @default 150
  1133.          */
  1134.         bounceRange: {
  1135.             value: 150
  1136.         }
  1137.     },

  1138.     /**
  1139.      * List of class names used in the scrollview's DOM
  1140.      *
  1141.      * @property CLASS_NAMES
  1142.      * @type Object
  1143.      * @static
  1144.      */
  1145.     CLASS_NAMES: CLASS_NAMES,

  1146.     /**
  1147.      * Flag used to source property changes initiated from the DOM
  1148.      *
  1149.      * @property UI_SRC
  1150.      * @type String
  1151.      * @static
  1152.      * @default 'ui'
  1153.      */
  1154.     UI_SRC: UI,

  1155.     /**
  1156.      * Object map of style property names used to set transition properties.
  1157.      * Defaults to the vendor prefix established by the Transition module.
  1158.      * The configured property names are `_TRANSITION.DURATION` (e.g. "WebkitTransitionDuration") and
  1159.      * `_TRANSITION.PROPERTY (e.g. "WebkitTransitionProperty").
  1160.      *
  1161.      * @property _TRANSITION
  1162.      * @private
  1163.      */
  1164.     _TRANSITION: {
  1165.         DURATION: (vendorPrefix ? vendorPrefix + 'TransitionDuration' : 'transitionDuration'),
  1166.         PROPERTY: (vendorPrefix ? vendorPrefix + 'TransitionProperty' : 'transitionProperty')
  1167.     },

  1168.     /**
  1169.      * The default bounce distance in pixels
  1170.      *
  1171.      * @property BOUNCE_RANGE
  1172.      * @type Number
  1173.      * @static
  1174.      * @default false
  1175.      * @deprecated (in 3.7.0)
  1176.      */
  1177.     BOUNCE_RANGE: false,

  1178.     /**
  1179.      * The interval (ms) used when animating the flick
  1180.      *
  1181.      * @property FRAME_STEP
  1182.      * @type Number
  1183.      * @static
  1184.      * @default false
  1185.      * @deprecated (in 3.7.0)
  1186.      */
  1187.     FRAME_STEP: false,

  1188.     /**
  1189.      * The default easing used when animating the flick
  1190.      *
  1191.      * @property EASING
  1192.      * @type String
  1193.      * @static
  1194.      * @default false
  1195.      * @deprecated (in 3.7.0)
  1196.      */
  1197.     EASING: false,

  1198.     /**
  1199.      * The default easing to use when animating the bounce snap back.
  1200.      *
  1201.      * @property SNAP_EASING
  1202.      * @type String
  1203.      * @static
  1204.      * @default false
  1205.      * @deprecated (in 3.7.0)
  1206.      */
  1207.     SNAP_EASING: false,

  1208.     /**
  1209.      * The default duration to use when animating the bounce snap back.
  1210.      *
  1211.      * @property SNAP_DURATION
  1212.      * @type Number
  1213.      * @static
  1214.      * @default false
  1215.      * @deprecated (in 3.7.0)
  1216.      */
  1217.     SNAP_DURATION: false

  1218.     // End static properties

  1219. });
  1220.