[Summary view] [Print] [Text view]

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