lib/yui/3.5.0/build/event-flick/event-flick.js

   1 /*
   2 YUI 3.5.0 (build 5089)
   3 Copyright 2012 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7 YUI.add('event-flick', function(Y) {
   8
   9 /**
  10  * The gestures module provides gesture events such as "flick", which normalize user interactions
  11  * across touch and mouse or pointer based input devices. This layer can be used by application developers
  12  * to build input device agnostic components which behave the same in response to either touch or mouse based
  13  * interaction.
  14  *
  15  * <p>Documentation for events added by this module can be found in the event document for the <a href="YUI.html#events">YUI</a> global.</p>
  16  *
  17  * @module event-gestures
  18  */
  19
  20 /**
  21  * Adds support for a "flick" event, which is fired at the end of a touch or mouse based flick gesture, and provides
  22  * velocity of the flick, along with distance and time information.
  23  *
  24  * @module event-gestures
  25  * @submodule event-flick
  26  */
  27
  28 var EVENT = ((Y.config.win && ("ontouchstart" in Y.config.win)) && !(Y.UA.chrome && Y.UA.chrome < 6)) ? {
  29         start: "touchstart",
  30         end: "touchend",
  31         move: "touchmove"
  32     } : {
  33         start: "mousedown",
  34         end: "mouseup",
  35         move: "mousemove"
  36     },
  37
  38     START = "start",
  39     END = "end",
  40     MOVE = "move",
  41
  42     OWNER_DOCUMENT = "ownerDocument",
  43     MIN_VELOCITY = "minVelocity",
  44     MIN_DISTANCE = "minDistance",
  45     PREVENT_DEFAULT = "preventDefault",
  46
  47     _FLICK_START = "_fs",
  48     _FLICK_START_HANDLE = "_fsh",
  49     _FLICK_END_HANDLE = "_feh",
  50     _FLICK_MOVE_HANDLE = "_fmh",
  51
  52     NODE_TYPE = "nodeType";
  53
  54 /**
  55  * Sets up a "flick" event, that is fired whenever the user initiates a flick gesture on the node
  56  * where the listener is attached. The subscriber can specify a minimum distance or velocity for
  57  * which the event is to be fired. The subscriber can also specify if there is a particular axis which
  58  * they are interested in - "x" or "y". If no axis is specified, the axis along which there was most distance
  59  * covered is used.
  60  *
  61  * <p>It is recommended that you use Y.bind to set up context and additional arguments for your event handler,
  62  * however if you want to pass the context and arguments as additional signature arguments to "on",
  63  * you need to provide a null value for the configuration object, e.g: <code>node.on("flick", fn, null, context, arg1, arg2, arg3)</code></p>
  64  *
  65  * @event flick
  66  * @for YUI
  67  * @param type {string} "flick"
  68  * @param fn {function} The method the event invokes. It receives an event facade with an e.flick object containing the flick related properties: e.flick.time, e.flick.distance, e.flick.velocity and e.flick.axis, e.flick.start.
  69  * @param cfg {Object} Optional. An object which specifies any of the following:
  70  * <dl>
  71  * <dt>minDistance (in pixels, defaults to 10)</dt>
  72  * <dd>The minimum distance between start and end points, which would qualify the gesture as a flick.</dd>
  73  * <dt>minVelocity (in pixels/ms, defaults to 0)</dt>
  74  * <dd>The minimum velocity which would qualify the gesture as a flick.</dd>
  75  * <dt>preventDefault (defaults to false)</dt>
  76  * <dd>Can be set to true/false to prevent default behavior as soon as the touchstart/touchend or mousedown/mouseup is received so that things like scrolling or text selection can be
  77  * prevented. This property can also be set to a function, which returns true or false, based on the event facade passed to it.</dd>
  78  * <dt>axis (no default)</dt>
  79  * <dd>Can be set to "x" or "y" if you want to constrain the flick velocity and distance to a single axis. If not
  80  * defined, the axis along which the maximum distance was covered is used.</dd>
  81  * </dl>
  82  * @return {EventHandle} the detach handle
  83  */
  84
  85 Y.Event.define('flick', {
  86
  87     on: function (node, subscriber, ce) {
  88
  89         var startHandle = node.on(EVENT[START],
  90             this._onStart,
  91             this,
  92             node,
  93             subscriber,
  94             ce);
  95
  96         subscriber[_FLICK_START_HANDLE] = startHandle;
  97     },
  98
  99     detach: function (node, subscriber, ce) {
 100
 101         var startHandle = subscriber[_FLICK_START_HANDLE],
 102             endHandle = subscriber[_FLICK_END_HANDLE];
 103
 104         if (startHandle) {
 105             startHandle.detach();
 106             subscriber[_FLICK_START_HANDLE] = null;
 107         }
 108
 109         if (endHandle) {
 110             endHandle.detach();
 111             subscriber[_FLICK_END_HANDLE] = null;
 112         }
 113     },
 114
 115     processArgs: function(args) {
 116         var params = (args.length > 3) ? Y.merge(args.splice(3, 1)[0]) : {};
 117
 118         if (!(MIN_VELOCITY in params)) {
 119             params[MIN_VELOCITY] = this.MIN_VELOCITY;
 120         }
 121
 122         if (!(MIN_DISTANCE in params)) {
 123             params[MIN_DISTANCE] = this.MIN_DISTANCE;
 124         }
 125
 126         if (!(PREVENT_DEFAULT in params)) {
 127             params[PREVENT_DEFAULT] = this.PREVENT_DEFAULT;
 128         }
 129
 130         return params;
 131     },
 132
 133     _onStart: function(e, node, subscriber, ce) {
 134
 135         var start = true, // always true for mouse
 136             endHandle,
 137             moveHandle,
 138             doc,
 139             preventDefault = subscriber._extra.preventDefault,
 140             origE = e;
 141
 142         if (e.touches) {
 143             start = (e.touches.length === 1);
 144             e = e.touches[0];
 145         }
 146
 147         if (start) {
 148
 149             if (preventDefault) {
 150                 // preventDefault is a boolean or function
 151                 if (!preventDefault.call || preventDefault(e)) {
 152                     origE.preventDefault();
 153                 }
 154             }
 155
 156             e.flick = {
 157                 time : new Date().getTime()
 158             };
 159
 160             subscriber[_FLICK_START] = e;
 161
 162             endHandle = subscriber[_FLICK_END_HANDLE];
 163
 164             doc = (node.get(NODE_TYPE) === 9) ? node : node.get(OWNER_DOCUMENT);
 165             if (!endHandle) {
 166                 endHandle = doc.on(EVENT[END], Y.bind(this._onEnd, this), null, node, subscriber, ce);
 167                 subscriber[_FLICK_END_HANDLE] = endHandle;
 168             }
 169
 170             subscriber[_FLICK_MOVE_HANDLE] = doc.once(EVENT[MOVE], Y.bind(this._onMove, this), null, node, subscriber, ce);
 171         }
 172     },
 173
 174     _onMove: function(e, node, subscriber, ce) {
 175         var start = subscriber[_FLICK_START];
 176
 177         // Start timing from first move.
 178         if (start && start.flick) {
 179             start.flick.time = new Date().getTime();
 180         }
 181     },
 182
 183     _onEnd: function(e, node, subscriber, ce) {
 184
 185         var endTime = new Date().getTime(),
 186             start = subscriber[_FLICK_START],
 187             valid = !!start,
 188             endEvent = e,
 189             startTime,
 190             time,
 191             preventDefault,
 192             params,
 193             xyDistance,
 194             distance,
 195             velocity,
 196             axis,
 197             moveHandle = subscriber[_FLICK_MOVE_HANDLE];
 198
 199         if (moveHandle) {
 200             moveHandle.detach();
 201             delete subscriber[_FLICK_MOVE_HANDLE];
 202         }
 203
 204         if (valid) {
 205
 206             if (e.changedTouches) {
 207                 if (e.changedTouches.length === 1 && e.touches.length === 0) {
 208                     endEvent = e.changedTouches[0];
 209                 } else {
 210                     valid = false;
 211                 }
 212             }
 213
 214             if (valid) {
 215
 216                 params = subscriber._extra;
 217                 preventDefault = params[PREVENT_DEFAULT];
 218
 219                 if (preventDefault) {
 220                     // preventDefault is a boolean or function
 221                     if (!preventDefault.call || preventDefault(e)) {
 222                         e.preventDefault();
 223                     }
 224                 }
 225
 226                 startTime = start.flick.time;
 227                 endTime = new Date().getTime();
 228                 time = endTime - startTime;
 229
 230                 xyDistance = [
 231                     endEvent.pageX - start.pageX,
 232                     endEvent.pageY - start.pageY
 233                 ];
 234
 235                 if (params.axis) {
 236                     axis = params.axis;
 237                 } else {
 238                     axis = (Math.abs(xyDistance[0]) >= Math.abs(xyDistance[1])) ? 'x' : 'y';
 239                 }
 240
 241                 distance = xyDistance[(axis === 'x') ? 0 : 1];
 242                 velocity = (time !== 0) ? distance/time : 0;
 243
 244                 if (isFinite(velocity) && (Math.abs(distance) >= params[MIN_DISTANCE]) && (Math.abs(velocity)  >= params[MIN_VELOCITY])) {
 245
 246                     e.type = "flick";
 247                     e.flick = {
 248                         time:time,
 249                         distance: distance,
 250                         velocity:velocity,
 251                         axis: axis,
 252                         start : start
 253                     };
 254
 255                     ce.fire(e);
 256
 257                 }
 258
 259                 subscriber[_FLICK_START] = null;
 260             }
 261         }
 262     },
 263
 264     MIN_VELOCITY : 0,
 265     MIN_DISTANCE : 0,
 266     PREVENT_DEFAULT : false
 267 });
 268
 269
 270 }, '3.5.0' ,{requires:['node-base','event-touch','event-synthetic']});