lib/yuilib/3.13.0/node-event-simulate/node-event-simulate.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('node-event-simulate', function (Y, NAME) {
   9
  10 /**
  11  * Adds functionality to simulate events.
  12  * @module node
  13  * @submodule node-event-simulate
  14  */
  15
  16 /**
  17  * Simulates an event on the node.
  18  * @param {String} type The type of event (i.e., "click").
  19  * @param {Object} options (Optional) Extra options to copy onto the event object.
  20  * @return {void}
  21  * @for Node
  22  * @method simulate
  23  */
  24 Y.Node.prototype.simulate = function (type, options) {
  25
  26     Y.Event.simulate(Y.Node.getDOMNode(this), type, options);
  27 };
  28
  29 /**
  30  * Simulates the higher user level gesture of the given name on this node.
  31  * This method generates a set of low level touch events(Apple specific gesture
  32  * events as well for the iOS platforms) asynchronously. Note that gesture
  33  * simulation is relying on `Y.Event.simulate()` method to generate
  34  * the touch events under the hood. The `Y.Event.simulate()` method
  35  * itself is a synchronous method.
  36  *
  37  * Supported gestures are `tap`, `doubletap`, `press`, `move`, `flick`, `pinch`
  38  * and `rotate`.
  39  *
  40  * The `pinch` gesture is used to simulate the pinching and spreading of two
  41  * fingers. During a pinch simulation, rotation is also possible. Essentially
  42  * `pinch` and `rotate` simulations share the same base implementation to allow
  43  * both pinching and rotation at the same time. The only difference is `pinch`
  44  * requires `start` and `end` option properties while `rotate` requires `rotation`
  45  * option property.
  46  *
  47  * The `pinch` and `rotate` gestures can be described as placing 2 fingers along a
  48  * circle. Pinching and spreading can be described by start and end circles while
  49  * rotation occurs on a single circle. If the radius of the start circle is greater
  50  * than the end circle, the gesture becomes a pinch, otherwise it is a spread spread.
  51  *
  52  * @example
  53  *
  54  *     var node = Y.one("#target");
  55  *
  56  *     // double tap example
  57  *     node.simulateGesture("doubletap", function() {
  58  *         // my callback function
  59  *     });
  60  *
  61  *     // flick example from the center of the node, move 50 pixels down for 50ms)
  62  *     node.simulateGesture("flick", {
  63  *         axis: y,
  64  *         distance: -100
  65  *         duration: 50
  66  *     }, function() {
  67  *         // my callback function
  68  *     });
  69  *
  70  *     // simulate rotating a node 75 degrees counter-clockwise
  71  *     node.simulateGesture("rotate", {
  72  *         rotation: -75
  73  *     });
  74  *
  75  *     // simulate a pinch and a rotation at the same time.
  76  *     // fingers start on a circle of radius 100 px, placed at top/bottom
  77  *     // fingers end on a circle of radius 50px, placed at right/left
  78  *     node.simulateGesture("pinch", {
  79  *         r1: 100,
  80  *         r2: 50,
  81  *         start: 0
  82  *         rotation: 90
  83  *     });
  84  *
  85  * @method simulateGesture
  86  * @param {String} name The name of the supported gesture to simulate. The
  87  *      supported gesture name is one of "tap", "doubletap", "press", "move",
  88  *      "flick", "pinch" and "rotate".
  89  * @param {Object} [options] Extra options used to define the gesture behavior:
  90  *
  91  *      Valid options properties for the `tap` gesture:
  92  *
  93  *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
  94  *        where the tap should be simulated. Default is the center of the node
  95  *        element.
  96  *      @param {Number} [options.hold=10] (Optional) The hold time in milliseconds.
  97  *        This is the time between `touchstart` and `touchend` event generation.
  98  *      @param {Number} [options.times=1] (Optional) Indicates the number of taps.
  99  *      @param {Number} [options.delay=10] (Optional) The number of milliseconds
 100  *        before the next tap simulation happens. This is valid only when `times`
 101  *        is more than 1.
 102  *
 103  *      Valid options properties for the `doubletap` gesture:
 104  *
 105  *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
 106  *        where the doubletap should be simulated. Default is the center of the
 107  *        node element.
 108  *
 109  *      Valid options properties for the `press` gesture:
 110  *
 111  *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
 112  *        where the press should be simulated. Default is the center of the node
 113  *        element.
 114  *      @param {Number} [options.hold=3000] (Optional) The hold time in milliseconds.
 115  *        This is the time between `touchstart` and `touchend` event generation.
 116  *        Default is 3000ms (3 seconds).
 117  *
 118  *      Valid options properties for the `move` gesture:
 119  *
 120  *      @param {Object} [options.path] (Optional) Indicates the path of the finger
 121  *        movement. It's an object with three optional properties: `point`,
 122  *        `xdist` and  `ydist`.
 123  *        @param {Array} [options.path.point] A starting point of the gesture.
 124  *          Default is the center of the node element.
 125  *        @param {Number} [options.path.xdist=200] A distance to move in pixels
 126  *          along the X axis. A negative distance value indicates moving left.
 127  *        @param {Number} [options.path.ydist=0] A distance to move in pixels
 128  *          along the Y axis. A negative distance value indicates moving up.
 129  *      @param {Number} [options.duration=1000] (Optional) The duration of the
 130  *        gesture in milliseconds.
 131  *
 132  *      Valid options properties for the `flick` gesture:
 133  *
 134  *      @param {Array} [options.point] (Optional) Indicates the [x, y] coordinates
 135  *        where the flick should be simulated. Default is the center of the
 136  *        node element.
 137  *      @param {String} [options.axis='x'] (Optional) Valid values are either
 138  *        "x" or "y". Indicates axis to move along. The flick can move to one of
 139  *        4 directions(left, right, up and down).
 140  *      @param {Number} [options.distance=200] (Optional) Distance to move in pixels
 141  *      @param {Number} [options.duration=1000] (Optional) The duration of the
 142  *        gesture in milliseconds. User given value could be automatically
 143  *        adjusted by the framework if it is below the minimum velocity to be
 144  *        a flick gesture.
 145  *
 146  *      Valid options properties for the `pinch` gesture:
 147  *
 148  *      @param {Array} [options.center] (Optional) The center of the circle where
 149  *        two fingers are placed. Default is the center of the node element.
 150  *      @param {Number} [options.r1] (Required) Pixel radius of the start circle
 151  *        where 2 fingers will be on when the gesture starts. The circles are
 152  *        centered at the center of the element.
 153  *      @param {Number} [options.r2] (Required) Pixel radius of the end circle
 154  *        when this gesture ends.
 155  *      @param {Number} [options.duration=1000] (Optional) The duration of the
 156  *        gesture in milliseconds.
 157  *      @param {Number} [options.start=0] (Optional) Starting degree of the first
 158  *        finger. The value is relative to the path of the north. Default is 0
 159  *        (i.e., 12:00 on a clock).
 160  *      @param {Number} [options.rotation=0] (Optional) Degrees to rotate from
 161  *        the starting degree. A negative value means rotation to the
 162  *        counter-clockwise direction.
 163  *
 164  *      Valid options properties for the `rotate` gesture:
 165  *
 166  *      @param {Array} [options.center] (Optional) The center of the circle where
 167  *        two fingers are placed. Default is the center of the node element.
 168  *      @param {Number} [options.r1] (Optional) Pixel radius of the start circle
 169  *        where 2 fingers will be on when the gesture starts. The circles are
 170  *        centered at the center of the element. Default is a fourth of the node
 171  *        element width or height, whichever is smaller.
 172  *      @param {Number} [options.r2] (Optional) Pixel radius of the end circle
 173  *        when this gesture ends. Default is a fourth of the node element width or
 174  *        height, whichever is smaller.
 175  *      @param {Number} [options.duration=1000] (Optional) The duration of the
 176  *        gesture in milliseconds.
 177  *      @param {Number} [options.start=0] (Optional) Starting degree of the first
 178  *        finger. The value is relative to the path of the north. Default is 0
 179  *        (i.e., 12:00 on a clock).
 180  *      @param {Number} [options.rotation] (Required) Degrees to rotate from
 181  *        the starting degree. A negative value means rotation to the
 182  *        counter-clockwise direction.
 183  *
 184  * @param {Function} [cb] The callback to execute when the asynchronouse gesture
 185  *      simulation is completed.
 186  *      @param {Error} cb.err An error object if the simulation is failed.
 187  * @return {void}
 188  * @for Node
 189  */
 190 Y.Node.prototype.simulateGesture = function (name, options, cb) {
 191
 192     Y.Event.simulateGesture(this, name, options, cb);
 193 };
 194
 195
 196 }, '3.13.0', {"requires": ["node-base", "event-simulate", "gesture-simulate"]});