Version 3.18.1
Show:

File: event-gestures/js/Flick.js

  1.             /**
  2.              * The gestures module provides gesture events such as "flick", which normalize user interactions
  3.              * across touch and mouse or pointer based input devices. This layer can be used by application developers
  4.              * to build input device agnostic components which behave the same in response to either touch or mouse based
  5.              * interaction.
  6.              *
  7.              * <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>
  8.              *
  9.              *
  10.              @example
  11.             
  12.                  YUI().use('event-flick', function (Y) {
  13.                      Y.one('#myNode').on('flick', function (e) {
  14.                          Y.log('flick event fired. The event payload has goodies.');
  15.                      });
  16.                  });
  17.             
  18.              *
  19.              * @module event-gestures
  20.              */
  21.             
  22.             /**
  23.              * Adds support for a "flick" event, which is fired at the end of a touch or mouse based flick gesture, and provides
  24.              * velocity of the flick, along with distance and time information.
  25.              *
  26.              * <p>Documentation for the flick event can be found on the <a href="../classes/YUI.html#event_flick">YUI</a> global,
  27.              * along with the other supported events.</p>
  28.              *
  29.              * @module event-gestures
  30.              * @submodule event-flick
  31.              */
  32.             var GESTURE_MAP = Y.Event._GESTURE_MAP,
  33.                 EVENT = {
  34.                     start: GESTURE_MAP.start,
  35.                     end: GESTURE_MAP.end,
  36.                     move: GESTURE_MAP.move
  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.