#

API Docs for: 3.10.3
Show: Inherited Protected Private Deprecated

# File: gesture-simulate/js/gesture-simulate.js

    /**
     * Simulate high-level user gestures by generating a set of native DOM events.
     *
     * @module gesture-simulate
     * @requires event-simulate, async-queue, node-screen
     */

    var NAME = "gesture-simulate",

        // phantomjs check may be temporary, until we determine if it really support touch all the way through, like it claims to (http://code.google.com/p/phantomjs/issues/detail?id=375)
        SUPPORTS_TOUCH = ((Y.config.win && ("ontouchstart" in Y.config.win)) && !(Y.UA.phantomjs) && !(Y.UA.chrome && Y.UA.chrome < 6)),

        gestureNames = {
            tap: 1,
            doubletap: 1,
            press: 1,
            move: 1,
            flick: 1,
            pinch: 1,
            rotate: 1
        },

        touchEvents = {
            touchstart: 1,
            touchmove: 1,
            touchend: 1,
            touchcancel: 1
        },

        document = Y.config.doc,
        emptyTouchList,

        EVENT_INTERVAL = 20,        // 20ms
        START_PAGEX,                // will be adjusted to the node element center
        START_PAGEY,                // will be adjusted to the node element center

        // defaults that user can override.
        DEFAULTS = {
            // tap gestures
            HOLD_TAP: 10,           // 10ms
            DELAY_TAP: 10,          // 10ms

            // press gesture
            HOLD_PRESS: 3000,       // 3sec
            MIN_HOLD_PRESS: 1000,   // 1sec
            MAX_HOLD_PRESS: 60000,  // 1min

            // move gesture
            DISTANCE_MOVE: 200,     // 200 pixels
            DURATION_MOVE: 1000,    // 1sec
            MAX_DURATION_MOVE: 5000,// 5sec

            // flick gesture
            MIN_VELOCITY_FLICK: 1.3,
            DISTANCE_FLICK: 200,     // 200 pixels
            DURATION_FLICK: 1000,    // 1sec
            MAX_DURATION_FLICK: 5000,// 5sec

            // pinch/rotation
            DURATION_PINCH: 1000     // 1sec
        },

        TOUCH_START = 'touchstart',
        TOUCH_MOVE = 'touchmove',
        TOUCH_END = 'touchend',

        GESTURE_START = 'gesturestart',
        GESTURE_CHANGE = 'gesturechange',
        GESTURE_END = 'gestureend',

        MOUSE_UP    = 'mouseup',
        MOUSE_MOVE  = 'mousemove',
        MOUSE_DOWN  = 'mousedown',
        MOUSE_CLICK = 'click',
        MOUSE_DBLCLICK = 'dblclick',

        X_AXIS = 'x',
        Y_AXIS = 'y';

    function Simulations(node) {
        if(!node) {
            Y.error(NAME+': invalid target node');
        }
        this.node = node;
        this.target = Y.Node.getDOMNode(node);

        var startXY = this.node.getXY(),
            dims = this._getDims();

        START_PAGEX = startXY[0] + (dims[0])/2;
        START_PAGEY = startXY[1] + (dims[1])/2;
    }

    Simulations.prototype = {

        /**
         * Helper method to convert a degree to a radian.
         *
         * @method _toRadian
         * @private
         * @param {Number} deg A degree to be converted to a radian.
         * @return {Number} The degree in radian.
         */
        _toRadian: function(deg) {
            return deg * (Math.PI/180);
        },

        /**
         * Helper method to get height/width while accounting for
         * rotation/scale transforms where possible by using the
         * bounding client rectangle height/width instead of the
         * offsetWidth/Height which region uses.
         * @method _getDims
         * @private
         * @return {Array} Array with [height, width]
         */
        _getDims : function() {
            var region,
                width,
                height;

            // Ideally, this should be in DOM somewhere.
            if (this.target.getBoundingClientRect) {
                region = this.target.getBoundingClientRect();

                if ("height" in region) {
                    height = region.height;
                } else {
                    // IE7,8 has getBCR, but no height.
                    height = Math.abs(region.bottom - region.top);
                }

                if ("width" in region) {
                    width = region.width;
                } else {
                    // IE7,8 has getBCR, but no width.
                    width = Math.abs(region.right - region.left);
                }
            } else {
                region = this.node.get("region");
                width = region.width;
                height = region.height;
            }

            return [width, height];
        },

        /**
         * Helper method to convert a point relative to the node element into
         * the point in the page coordination.
         *
         * @method _calculateDefaultPoint
         * @private
         * @param {Array} point A point relative to the node element.
         * @return {Array} The same point in the page coordination.
         */
        _calculateDefaultPoint: function(point) {

            var height;

            if(!Y.Lang.isArray(point) || point.length === 0) {
                point = [START_PAGEX, START_PAGEY];
            } else {
                if(point.length == 1) {
                    height = this._getDims[1];
                    point[1] = height/2;
                }
                // convert to page(viewport) coordination
                point[0] = this.node.getX() + point[0];
                point[1] = this.node.getY() + point[1];
            }

            return point;
        },

        /**
         * The "rotate" and "pinch" methods are essencially same with the exact same
         * arguments. Only difference is the required parameters. The rotate method
         * requires "rotation" parameter while the pinch method requires "startRadius"
         * and "endRadius" parameters.
         *
         * @method rotate
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Array} center A center point where the pinch gesture of two fingers
         *      should happen. It is relative to the top left corner of the target
         *      node element.
         * @param {Number} startRadius A radius of start circle where 2 fingers are
         *      on when the gesture starts. This is optional. The default is a fourth of
         *      either target node width or height whichever is smaller.
         * @param {Number} endRadius A radius of end circle where 2 fingers will be on when
         *      the pinch or spread gestures are completed. This is optional.
         *      The default is a fourth of either target node width or height whichever is less.
         * @param {Number} duration A duration of the gesture in millisecond.
         * @param {Number} start A start angle(0 degree at 12 o'clock) where the
         *      gesture should start. Default is 0.
         * @param {Number} rotation A rotation in degree. It is required.
         */
        rotate: function(cb, center, startRadius, endRadius, duration, start, rotation) {
            var radius,
                r1 = startRadius,   // optional
                r2 = endRadius;     // optional

            if(!Y.Lang.isNumber(r1) || !Y.Lang.isNumber(r2) || r1<0 || r2<0) {
                radius = (this.target.offsetWidth < this.target.offsetHeight)?
                    this.target.offsetWidth/4 : this.target.offsetHeight/4;
                r1 = radius;
                r2 = radius;
            }

            // required
            if(!Y.Lang.isNumber(rotation)) {
                Y.error(NAME+'Invalid rotation detected.');
            }

            this.pinch(cb, center, r1, r2, duration, start, rotation);
        },

        /**
         * The "rotate" and "pinch" methods are essencially same with the exact same
         * arguments. Only difference is the required parameters. The rotate method
         * requires "rotation" parameter while the pinch method requires "startRadius"
         * and "endRadius" parameters.
         *
         * The "pinch" gesture can simulate various 2 finger gestures such as pinch,
         * spread and/or rotation. The "startRadius" and "endRadius" are required.
         * If endRadius is larger than startRadius, it becomes a spread gesture
         * otherwise a pinch gesture.
         *
         * @method pinch
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Array} center A center point where the pinch gesture of two fingers
         *      should happen. It is relative to the top left corner of the target
         *      node element.
         * @param {Number} startRadius A radius of start circle where 2 fingers are
         *      on when the gesture starts. This paramenter is required.
         * @param {Number} endRadius A radius of end circle where 2 fingers will be on when
         *      the pinch or spread gestures are completed. This parameter is required.
         * @param {Number} duration A duration of the gesture in millisecond.
         * @param {Number} start A start angle(0 degree at 12 o'clock) where the
         *      gesture should start. Default is 0.
         * @param {Number} rotation If rotation is desired during the pinch or
         *      spread gestures, this parameter can be used. Default is 0 degree.
         */
        pinch: function(cb, center, startRadius, endRadius, duration, start, rotation) {
            var eventQueue,
                i,
                interval = EVENT_INTERVAL,
                touches,
                id = 0,
                r1 = startRadius,   // required
                r2 = endRadius,     // required
                radiusPerStep,
                centerX, centerY,
                startScale, endScale, scalePerStep,
                startRot, endRot, rotPerStep,
                path1 = {start: [], end: []}, // paths for 1st and 2nd fingers.
                path2 = {start: [], end: []},
                steps,
                touchMove;

            center = this._calculateDefaultPoint(center);

            if(!Y.Lang.isNumber(r1) || !Y.Lang.isNumber(r2) || r1<0 || r2<0) {
                Y.error(NAME+'Invalid startRadius and endRadius detected.');
            }

            if(!Y.Lang.isNumber(duration) || duration <= 0) {
                duration = DEFAULTS.DURATION_PINCH;
            }

            if(!Y.Lang.isNumber(start)) {
                start = 0.0;
            } else {
                start = start%360;
                while(start < 0) {
                    start += 360;
                }
            }

            if(!Y.Lang.isNumber(rotation)) {
                rotation = 0.0;
            }

            Y.AsyncQueue.defaults.timeout = interval;
            eventQueue = new Y.AsyncQueue();

            // range determination
            centerX = center[0];
            centerY = center[1];

            startRot = start;
            endRot = start + rotation;

            // 1st finger path
            path1.start = [
                centerX + r1*Math.sin(this._toRadian(startRot)),
                centerY - r1*Math.cos(this._toRadian(startRot))
            ];
            path1.end   = [
                centerX + r2*Math.sin(this._toRadian(endRot)),
                centerY - r2*Math.cos(this._toRadian(endRot))
            ];

            // 2nd finger path
            path2.start = [
                centerX - r1*Math.sin(this._toRadian(startRot)),
                centerY + r1*Math.cos(this._toRadian(startRot))
            ];
            path2.end   = [
                centerX - r2*Math.sin(this._toRadian(endRot)),
                centerY + r2*Math.cos(this._toRadian(endRot))
            ];

            startScale = 1.0;
            endScale = endRadius/startRadius;

            // touch/gesture start
            eventQueue.add({
                fn: function() {
                    var coord1, coord2, coord, touches;

                    // coordinate for each touch object.
                    coord1 = {
                        pageX: path1.start[0],
                        pageY: path1.start[1],
                        clientX: path1.start[0],
                        clientY: path1.start[1]
                    };
                    coord2 = {
                        pageX: path2.start[0],
                        pageY: path2.start[1],
                        clientX: path2.start[0],
                        clientY: path2.start[1]
                    };
                    touches = this._createTouchList([Y.merge({
                        identifier: (id++)
                    }, coord1), Y.merge({
                        identifier: (id++)
                    }, coord2)]);

                    // coordinate for top level event
                    coord = {
                        pageX: (path1.start[0] + path2.start[0])/2,
                        pageY: (path1.start[0] + path2.start[1])/2,
                        clientX: (path1.start[0] + path2.start[0])/2,
                        clientY: (path1.start[0] + path2.start[1])/2
                    };

                    this._simulateEvent(this.target, TOUCH_START, Y.merge({
                        touches: touches,
                        targetTouches: touches,
                        changedTouches: touches,
                        scale: startScale,
                        rotation: startRot
                    }, coord));

                    if(Y.UA.ios >= 2.0) {
                        /* gesture starts when the 2nd finger touch starts.
                        * The implementation will fire 1 touch start event for both fingers,
                        * simulating 2 fingers touched on the screen at the same time.
                        */
                        this._simulateEvent(this.target, GESTURE_START, Y.merge({
                            scale: startScale,
                            rotation: startRot
                        }, coord));
                    }
                },
                timeout: 0,
                context: this
            });

            // gesture change
            steps = Math.floor(duration/interval);
            radiusPerStep = (r2 - r1)/steps;
            scalePerStep = (endScale - startScale)/steps;
            rotPerStep = (endRot - startRot)/steps;

            touchMove = function(step) {
                var radius = r1 + (radiusPerStep)*step,
                    px1 = centerX + radius*Math.sin(this._toRadian(startRot + rotPerStep*step)),
                    py1 = centerY - radius*Math.cos(this._toRadian(startRot + rotPerStep*step)),
                    px2 = centerX - radius*Math.sin(this._toRadian(startRot + rotPerStep*step)),
                    py2 = centerY + radius*Math.cos(this._toRadian(startRot + rotPerStep*step)),
                    px = (px1+px2)/2,
                    py = (py1+py2)/2,
                    coord1, coord2, coord, touches;

                // coordinate for each touch object.
                coord1 = {
                    pageX: px1,
                    pageY: py1,
                    clientX: px1,
                    clientY: py1
                };
                coord2 = {
                    pageX: px2,
                    pageY: py2,
                    clientX: px2,
                    clientY: py2
                };
                touches = this._createTouchList([Y.merge({
                    identifier: (id++)
                }, coord1), Y.merge({
                    identifier: (id++)
                }, coord2)]);

                // coordinate for top level event
                coord = {
                    pageX: px,
                    pageY: py,
                    clientX: px,
                    clientY: py
                };

                this._simulateEvent(this.target, TOUCH_MOVE, Y.merge({
                    touches: touches,
                    targetTouches: touches,
                    changedTouches: touches,
                    scale: startScale + scalePerStep*step,
                    rotation: startRot + rotPerStep*step
                }, coord));

                if(Y.UA.ios >= 2.0) {
                    this._simulateEvent(this.target, GESTURE_CHANGE, Y.merge({
                        scale: startScale + scalePerStep*step,
                        rotation: startRot + rotPerStep*step
                    }, coord));
                }
            };

            for (i=0; i < steps; i++) {
                eventQueue.add({
                    fn: touchMove,
                    args: [i],
                    context: this
                });
            }

            // gesture end
            eventQueue.add({
                fn: function() {
                    var emptyTouchList = this._getEmptyTouchList(),
                        coord1, coord2, coord, touches;

                    // coordinate for each touch object.
                    coord1 = {
                        pageX: path1.end[0],
                        pageY: path1.end[1],
                        clientX: path1.end[0],
                        clientY: path1.end[1]
                    };
                    coord2 = {
                        pageX: path2.end[0],
                        pageY: path2.end[1],
                        clientX: path2.end[0],
                        clientY: path2.end[1]
                    };
                    touches = this._createTouchList([Y.merge({
                        identifier: (id++)
                    }, coord1), Y.merge({
                        identifier: (id++)
                    }, coord2)]);

                    // coordinate for top level event
                    coord = {
                        pageX: (path1.end[0] + path2.end[0])/2,
                        pageY: (path1.end[0] + path2.end[1])/2,
                        clientX: (path1.end[0] + path2.end[0])/2,
                        clientY: (path1.end[0] + path2.end[1])/2
                    };

                    if(Y.UA.ios >= 2.0) {
                        this._simulateEvent(this.target, GESTURE_END, Y.merge({
                            scale: endScale,
                            rotation: endRot
                        }, coord));
                    }

                    this._simulateEvent(this.target, TOUCH_END, Y.merge({
                        touches: emptyTouchList,
                        targetTouches: emptyTouchList,
                        changedTouches: touches,
                        scale: endScale,
                        rotation: endRot
                    }, coord));
                },
                context: this
            });

            if(cb && Y.Lang.isFunction(cb)) {
                eventQueue.add({
                    fn: cb,

                    // by default, the callback runs the node context where
                    // simulateGesture method is called.
                    context: this.node

                    //TODO: Use args to pass error object as 1st param if there is an error.
                    //args:
                });
            }

            eventQueue.run();
        },

        /**
         * The "tap" gesture can be used for various single touch point gestures
         * such as single tap, N number of taps, long press. The default is a single
         * tap.
         *
         * @method tap
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Array} point A point(relative to the top left corner of the
         *      target node element) where the tap gesture should start. The default
         *      is the center of the taget node.
         * @param {Number} times The number of taps. Default is 1.
         * @param {Number} hold The hold time in milliseconds between "touchstart" and
         *      "touchend" event generation. Default is 10ms.
         * @param {Number} delay The time gap in millisecond between taps if this
         *      gesture has more than 1 tap. Default is 10ms.
         */
        tap: function(cb, point, times, hold, delay) {
            var eventQueue = new Y.AsyncQueue(),
                emptyTouchList = this._getEmptyTouchList(),
                touches,
                coord,
                i,
                touchStart,
                touchEnd;

            point = this._calculateDefaultPoint(point);

            if(!Y.Lang.isNumber(times) || times < 1) {
                times = 1;
            }

            if(!Y.Lang.isNumber(hold)) {
                hold = DEFAULTS.HOLD_TAP;
            }

            if(!Y.Lang.isNumber(delay)) {
                delay = DEFAULTS.DELAY_TAP;
            }

            coord = {
                pageX: point[0],
                pageY: point[1],
                clientX: point[0],
                clientY: point[1]
            };

            touches = this._createTouchList([Y.merge({identifier: 0}, coord)]);

            touchStart = function() {
                this._simulateEvent(this.target, TOUCH_START, Y.merge({
                    touches: touches,
                    targetTouches: touches,
                    changedTouches: touches
                }, coord));
            };

            touchEnd = function() {
                this._simulateEvent(this.target, TOUCH_END, Y.merge({
                    touches: emptyTouchList,
                    targetTouches: emptyTouchList,
                    changedTouches: touches
                }, coord));
            };

            for (i=0; i < times; i++) {
                eventQueue.add({
                    fn: touchStart,
                    context: this,
                    timeout: (i === 0)? 0 : delay
                });

                eventQueue.add({
                    fn: touchEnd,
                    context: this,
                    timeout: hold
                });
            }

            if(times > 1 && !SUPPORTS_TOUCH) {
                eventQueue.add({
                    fn: function() {
                        this._simulateEvent(this.target, MOUSE_DBLCLICK, coord);
                    },
                    context: this
                });
            }

            if(cb && Y.Lang.isFunction(cb)) {
                eventQueue.add({
                    fn: cb,

                    // by default, the callback runs the node context where
                    // simulateGesture method is called.
                    context: this.node

                    //TODO: Use args to pass error object as 1st param if there is an error.
                    //args:
                });
            }

            eventQueue.run();
        },

        /**
         * The "flick" gesture is a specialized "move" that has some velocity
         * and the movement always runs either x or y axis. The velocity is calculated
         * with "distance" and "duration" arguments. If the calculated velocity is
         * below than the minimum velocity, the given duration will be ignored and
         * new duration will be created to make a valid flick gesture.
         *
         * @method flick
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Array} point A point(relative to the top left corner of the
         *      target node element) where the flick gesture should start. The default
         *      is the center of the taget node.
         * @param {String} axis Either "x" or "y".
         * @param {Number} distance A distance in pixels to flick.
         * @param {Number} duration A duration of the gesture in millisecond.
         *
         */
        flick: function(cb, point, axis, distance, duration) {
            var path;

            point = this._calculateDefaultPoint(point);

            if(!Y.Lang.isString(axis)) {
                axis = X_AXIS;
            } else {
                axis = axis.toLowerCase();
                if(axis !== X_AXIS && axis !== Y_AXIS) {
                    Y.error(NAME+'(flick): Only x or y axis allowed');
                }
            }

            if(!Y.Lang.isNumber(distance)) {
                distance = DEFAULTS.DISTANCE_FLICK;
            }

            if(!Y.Lang.isNumber(duration)){
                duration = DEFAULTS.DURATION_FLICK; // ms
            } else {
                if(duration > DEFAULTS.MAX_DURATION_FLICK) {
                    duration = DEFAULTS.MAX_DURATION_FLICK;
                }
            }

            /*
             * Check if too slow for a flick.
             * Adjust duration if the calculated velocity is less than
             * the minimum velcocity to be claimed as a flick.
             */
            if(Math.abs(distance)/duration < DEFAULTS.MIN_VELOCITY_FLICK) {
                duration = Math.abs(distance)/DEFAULTS.MIN_VELOCITY_FLICK;
            }

            path = {
                start: Y.clone(point),
                end: [
                    (axis === X_AXIS) ? point[0]+distance : point[0],
                    (axis === Y_AXIS) ? point[1]+distance : point[1]
                ]
            };

            this._move(cb, path, duration);
        },

        /**
         * The "move" gesture simulate the movement of any direction between
         * the straight line of start and end point for the given duration.
         * The path argument is an object with "point", "xdist" and "ydist" properties.
         * The "point" property is an array with x and y coordinations(relative to the
         * top left corner of the target node element) while "xdist" and "ydist"
         * properties are used for the distance along the x and y axis. A negative
         * distance number can be used to drag either left or up direction.
         *
         * If no arguments are given, it will simulate the default move, which
         * is moving 200 pixels from the center of the element to the positive X-axis
         * direction for 1 sec.
         *
         * @method move
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Object} path An object with "point", "xdist" and "ydist".
         * @param {Number} duration A duration of the gesture in millisecond.
         */
        move: function(cb, path, duration) {
            var convertedPath;

            if(!Y.Lang.isObject(path)) {
                path = {
                    point: this._calculateDefaultPoint([]),
                    xdist: DEFAULTS.DISTANCE_MOVE,
                    ydist: 0
                };
            } else {
                // convert to the page coordination
                if(!Y.Lang.isArray(path.point)) {
                    path.point = this._calculateDefaultPoint([]);
                } else {
                    path.point = this._calculateDefaultPoint(path.point);
                }

                if(!Y.Lang.isNumber(path.xdist)) {
                    path.xdist = DEFAULTS.DISTANCE_MOVE;
                }

                if(!Y.Lang.isNumber(path.ydist)) {
                    path.ydist = 0;
                }
            }

            if(!Y.Lang.isNumber(duration)){
                duration = DEFAULTS.DURATION_MOVE; // ms
            } else {
                if(duration > DEFAULTS.MAX_DURATION_MOVE) {
                    duration = DEFAULTS.MAX_DURATION_MOVE;
                }
            }

            convertedPath = {
                start: Y.clone(path.point),
                end: [path.point[0]+path.xdist, path.point[1]+path.ydist]
            };

            this._move(cb, convertedPath, duration);
        },

        /**
         * A base method on top of "move" and "flick" methods. The method takes
         * the path with start/end properties and duration to generate a set of
         * touch events for the movement gesture.
         *
         * @method _move
         * @private
         * @param {Function} cb The callback to execute when the gesture simulation
         *      is completed.
         * @param {Object} path An object with "start" and "end" properties. Each
         *      property should be an array with x and y coordination (e.g. start: [100, 50])
         * @param {Number} duration A duration of the gesture in millisecond.
         */
        _move: function(cb, path, duration) {
            var eventQueue,
                i,
                interval = EVENT_INTERVAL,
                steps, stepX, stepY,
                id = 0,
                touchMove;

            if(!Y.Lang.isNumber(duration)){
                duration = DEFAULTS.DURATION_MOVE; // ms
            } else {
                if(duration > DEFAULTS.MAX_DURATION_MOVE) {
                    duration = DEFAULTS.MAX_DURATION_MOVE;
                }
            }

            if(!Y.Lang.isObject(path)) {
                path = {
                    start: [
                        START_PAGEX,
                        START_PAGEY
                    ],
                    end: [
                        START_PAGEX + DEFAULTS.DISTANCE_MOVE,
                        START_PAGEY
                    ]
                };
            } else {
                if(!Y.Lang.isArray(path.start)) {
                    path.start = [
                        START_PAGEX,
                        START_PAGEY
                    ];
                }
                if(!Y.Lang.isArray(path.end)) {
                    path.end = [
                        START_PAGEX + DEFAULTS.DISTANCE_MOVE,
                        START_PAGEY
                    ];
                }
            }

            Y.AsyncQueue.defaults.timeout = interval;
            eventQueue = new Y.AsyncQueue();

            // start
            eventQueue.add({
                fn: function() {
                    var coord = {
                            pageX: path.start[0],
                            pageY: path.start[1],
                            clientX: path.start[0],
                            clientY: path.start[1]
                        },
                        touches = this._createTouchList([
                            Y.merge({identifier: (id++)}, coord)
                        ]);

                    this._simulateEvent(this.target, TOUCH_START, Y.merge({
                        touches: touches,
                        targetTouches: touches,
                        changedTouches: touches
                    }, coord));
                },
                timeout: 0,
                context: this
            });

            // move
            steps = Math.floor(duration/interval);
            stepX = (path.end[0] - path.start[0])/steps;
            stepY = (path.end[1] - path.start[1])/steps;

            touchMove = function(step) {
                var px = path.start[0]+(stepX * step),
                    py = path.start[1]+(stepY * step),
                    coord = {
                        pageX: px,
                        pageY: py,
                        clientX: px,
                        clientY: py
                    },
                    touches = this._createTouchList([
                        Y.merge({identifier: (id++)}, coord)
                    ]);

                this._simulateEvent(this.target, TOUCH_MOVE, Y.merge({
                    touches: touches,
                    targetTouches: touches,
                    changedTouches: touches
                }, coord));
            };

            for (i=0; i < steps; i++) {
                eventQueue.add({
                    fn: touchMove,
                    args: [i],
                    context: this
                });
            }

            // last move
            eventQueue.add({
                fn: function() {
                    var coord = {
                            pageX: path.end[0],
                            pageY: path.end[1],
                            clientX: path.end[0],
                            clientY: path.end[1]
                        },
                        touches = this._createTouchList([
                            Y.merge({identifier: id}, coord)
                        ]);

                    this._simulateEvent(this.target, TOUCH_MOVE, Y.merge({
                        touches: touches,
                        targetTouches: touches,
                        changedTouches: touches
                    }, coord));
                },
                timeout: 0,
                context: this
            });

            // end
            eventQueue.add({
                fn: function() {
                    var coord = {
                        pageX: path.end[0],
                        pageY: path.end[1],
                        clientX: path.end[0],
                        clientY: path.end[1]
                    },
                    emptyTouchList = this._getEmptyTouchList(),
                    touches = this._createTouchList([
                        Y.merge({identifier: id}, coord)
                    ]);

                    this._simulateEvent(this.target, TOUCH_END, Y.merge({
                        touches: emptyTouchList,
                        targetTouches: emptyTouchList,
                        changedTouches: touches
                    }, coord));
                },
                context: this
            });

            if(cb && Y.Lang.isFunction(cb)) {
                eventQueue.add({
                    fn: cb,

                    // by default, the callback runs the node context where
                    // simulateGesture method is called.
                    context: this.node

                    //TODO: Use args to pass error object as 1st param if there is an error.
                    //args:
                });
            }

            eventQueue.run();
        },

        /**
         * Helper method to return a singleton instance of empty touch list.
         *
         * @method _getEmptyTouchList
         * @private
         * @return {TouchList | Array} An empty touch list object.
         */
        _getEmptyTouchList: function() {
            if(!emptyTouchList) {
                emptyTouchList = this._createTouchList([]);
            }

            return emptyTouchList;
        },

        /**
         * Helper method to convert an array with touch points to TouchList object as
         * defined in http://www.w3.org/TR/touch-events/
         *
         * @method _createTouchList
         * @private
         * @param {Array} touchPoints
         * @return {TouchList | Array} If underlaying platform support creating touch list
         *      a TouchList object will be returned otherwise a fake Array object
         *      will be returned.
         */
        _createTouchList: function(touchPoints) {
            /*
            * Android 4.0.3 emulator:
            * Native touch api supported starting in version 4.0 (Ice Cream Sandwich).
            * However the support seems limited. In Android 4.0.3 emulator, I got
            * "TouchList is not defined".
            */
            var touches = [],
                touchList,
                self = this;

            if(!!touchPoints && Y.Lang.isArray(touchPoints)) {
                if(Y.UA.android && Y.UA.android >= 4.0 || Y.UA.ios && Y.UA.ios >= 2.0) {
                    Y.each(touchPoints, function(point) {
                        if(!point.identifier) {point.identifier = 0;}
                        if(!point.pageX) {point.pageX = 0;}
                        if(!point.pageY) {point.pageY = 0;}
                        if(!point.screenX) {point.screenX = 0;}
                        if(!point.screenY) {point.screenY = 0;}

                        touches.push(document.createTouch(Y.config.win,
                            self.target,
                            point.identifier,
                            point.pageX, point.pageY,
                            point.screenX, point.screenY));
                    });

                    touchList = document.createTouchList.apply(document, touches);
                } else if(Y.UA.ios && Y.UA.ios < 2.0) {
                    Y.error(NAME+': No touch event simulation framework present.');
                } else {
                    // this will inclide android(Y.UA.android && Y.UA.android < 4.0)
                    // and desktops among all others.

                    /*
                     * Touch APIs are broken in androids older than 4.0. We will use
                     * simulated touch apis for these versions.
                     */
                    touchList = [];
                    Y.each(touchPoints, function(point) {
                        if(!point.identifier) {point.identifier = 0;}
                        if(!point.clientX)  {point.clientX = 0;}
                        if(!point.clientY)  {point.clientY = 0;}
                        if(!point.pageX)    {point.pageX = 0;}
                        if(!point.pageY)    {point.pageY = 0;}
                        if(!point.screenX)  {point.screenX = 0;}
                        if(!point.screenY)  {point.screenY = 0;}

                        touchList.push({
                            target: self.target,
                            identifier: point.identifier,
                            clientX: point.clientX,
                            clientY: point.clientY,
                            pageX: point.pageX,
                            pageY: point.pageY,
                            screenX: point.screenX,
                            screenY: point.screenY
                        });
                    });

                    touchList.item = function(i) {
                        return touchList[i];
                    };
                }
            } else {
                Y.error(NAME+': Invalid touchPoints passed');
            }

            return touchList;
        },

        /**
         * @method _simulateEvent
         * @private
         * @param {HTMLElement} target The DOM element that's the target of the event.
         * @param {String} type The type of event or name of the supported gesture to simulate
         *      (i.e., "click", "doubletap", "flick").
         * @param {Object} options (Optional) Extra options to copy onto the event object.
         *      For gestures, options are used to refine the gesture behavior.
         * @return {void}
         */
        _simulateEvent: function(target, type, options) {
            var touches;

            if (touchEvents[type]) {
                if(SUPPORTS_TOUCH) {
                    Y.Event.simulate(target, type, options);
                } else {
                    // simulate using mouse events if touch is not applicable on this platform.
                    // but only single touch event can be simulated.
                    if(this._isSingleTouch(options.touches, options.targetTouches, options.changedTouches)) {
                        type = {
                            touchstart: MOUSE_DOWN,
                            touchmove: MOUSE_MOVE,
                            touchend: MOUSE_UP
                        }[type];

                        options.button = 0;
                        options.relatedTarget = null; // since we are not using mouseover event.

                        // touchend has none in options.touches.
                        touches = (type === MOUSE_UP)? options.changedTouches : options.touches;

                        options = Y.mix(options, {
                            screenX: touches.item(0).screenX,
                            screenY: touches.item(0).screenY,
                            clientX: touches.item(0).clientX,
                            clientY: touches.item(0).clientY
                        }, true);

                        Y.Event.simulate(target, type, options);

                        if(type == MOUSE_UP) {
                            Y.Event.simulate(target, MOUSE_CLICK, options);
                        }
                    } else {
                        Y.error("_simulateEvent(): Event '" + type + "' has multi touch objects that can't be simulated in your platform.");
                    }
                }
            } else {
                // pass thru for all non touch events
                Y.Event.simulate(target, type, options);
            }
        },

        /**
         * Helper method to check the single touch.
         * @method _isSingleTouch
         * @private
         * @param {TouchList} touches
         * @param {TouchList} targetTouches
         * @param {TouchList} changedTouches
         */
        _isSingleTouch: function(touches, targetTouches, changedTouches) {
            return (touches && (touches.length <= 1)) &&
                (targetTouches && (targetTouches.length <= 1)) &&
                (changedTouches && (changedTouches.length <= 1));
        }
    };

    /*
     * A gesture simulation class.
     */
    Y.GestureSimulation = Simulations;

    /*
     * Various simulation default behavior properties. If user override
     * Y.GestureSimulation.defaults, overriden values will be used and this
     * should be done before the gesture simulation.
     */
    Y.GestureSimulation.defaults = DEFAULTS;

    /*
     * The high level gesture names that YUI knows how to simulate.
     */
    Y.GestureSimulation.GESTURES = gestureNames;

    /**
     * Simulates the higher user level gesture of the given name on a target.
     * This method generates a set of low level touch events(Apple specific gesture
     * events as well for the iOS platforms) asynchronously. Note that gesture
     * simulation is relying on `Y.Event.simulate()` method to generate
     * the touch events under the hood. The `Y.Event.simulate()` method
     * itself is a synchronous method.
     *
     * Users are suggested to use `Node.simulateGesture()` method which
     * basically calls this method internally. Supported gestures are `tap`,
     * `doubletap`, `press`, `move`, `flick`, `pinch` and `rotate`.
     *
     * The `pinch` gesture is used to simulate the pinching and spreading of two
     * fingers. During a pinch simulation, rotation is also possible. Essentially
     * `pinch` and `rotate` simulations share the same base implementation to allow
     * both pinching and rotation at the same time. The only difference is `pinch`
     * requires `start` and `end` option properties while `rotate` requires `rotation`
     * option property.
     *
     * The `pinch` and `rotate` gestures can be described as placing 2 fingers along a
     * circle. Pinching and spreading can be described by start and end circles while
     * rotation occurs on a single circle. If the radius of the start circle is greater
     * than the end circle, the gesture becomes a pinch, otherwise it is a spread spread.
     *
     * @example
     *
     *     var node = Y.one("#target");
     *
     *     // double tap example
     *     node.simulateGesture("doubletap", function() {
     *         // my callback function
     *     });
     *
     *     // flick example from the center of the node, move 50 pixels down for 50ms)
     *     node.simulateGesture("flick", {
     *         axis: y,
     *         distance: -100
     *         duration: 50
     *     }, function() {
     *         // my callback function
     *     });
     *
     *     // simulate rotating a node 75 degrees counter-clockwise
     *     node.simulateGesture("rotate", {
     *         rotation: -75
     *     });
     *
     *     // simulate a pinch and a rotation at the same time.
     *     // fingers start on a circle of radius 100 px, placed at top/bottom
     *     // fingers end on a circle of radius 50px, placed at right/left
     *     node.simulateGesture("pinch", {
     *         r1: 100,
     *         r2: 50,
     *         start: 0
     *         rotation: 90
     *     });
     *
     * @method simulateGesture
     * @param {HTMLElement|Node} node The YUI node or HTML element that's the target
     *      of the event.
     * @param {String} name The name of the supported gesture to simulate. The
     *      supported gesture name is one of "tap", "doubletap", "press", "move",
     *      "flick", "pinch" and "rotate".
     * @param {Object} [options] Extra options used to define the gesture behavior:
     *
     *      Valid options properties for the `tap` gesture:
     *
     *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
     *        where the tap should be simulated. Default is the center of the node
     *        element.
     *      @param {Number} [options.hold=10] (Optional) The hold time in milliseconds.
     *        This is the time between `touchstart` and `touchend` event generation.
     *      @param {Number} [options.times=1] (Optional) Indicates the number of taps.
     *      @param {Number} [options.delay=10] (Optional) The number of milliseconds
     *        before the next tap simulation happens. This is valid only when `times`
     *        is more than 1.
     *
     *      Valid options properties for the `doubletap` gesture:
     *
     *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
     *        where the doubletap should be simulated. Default is the center of the
     *        node element.
     *
     *      Valid options properties for the `press` gesture:
     *
     *      @param {Array} [options.point] (Optional) Indicates the [x,y] coordinates
     *        where the press should be simulated. Default is the center of the node
     *        element.
     *      @param {Number} [options.hold=3000] (Optional) The hold time in milliseconds.
     *        This is the time between `touchstart` and `touchend` event generation.
     *        Default is 3000ms (3 seconds).
     *
     *      Valid options properties for the `move` gesture:
     *
     *      @param {Object} [options.path] (Optional) Indicates the path of the finger
     *        movement. It's an object with three optional properties: `point`,
     *        `xdist` and  `ydist`.
     *        @param {Array} [options.path.point] A starting point of the gesture.
     *          Default is the center of the node element.
     *        @param {Number} [options.path.xdist=200] A distance to move in pixels
     *          along the X axis. A negative distance value indicates moving left.
     *        @param {Number} [options.path.ydist=0] A distance to move in pixels
     *          along the Y axis. A negative distance value indicates moving up.
     *      @param {Number} [options.duration=1000] (Optional) The duration of the
     *        gesture in milliseconds.
     *
     *      Valid options properties for the `flick` gesture:
     *
     *      @param {Array} [options.point] (Optional) Indicates the [x, y] coordinates
     *        where the flick should be simulated. Default is the center of the
     *        node element.
     *      @param {String} [options.axis='x'] (Optional) Valid values are either
     *        "x" or "y". Indicates axis to move along. The flick can move to one of
     *        4 directions(left, right, up and down).
     *      @param {Number} [options.distance=200] (Optional) Distance to move in pixels
     *      @param {Number} [options.duration=1000] (Optional) The duration of the
     *        gesture in milliseconds. User given value could be automatically
     *        adjusted by the framework if it is below the minimum velocity to be
     *        a flick gesture.
     *
     *      Valid options properties for the `pinch` gesture:
     *
     *      @param {Array} [options.center] (Optional) The center of the circle where
     *        two fingers are placed. Default is the center of the node element.
     *      @param {Number} [options.r1] (Required) Pixel radius of the start circle
     *        where 2 fingers will be on when the gesture starts. The circles are
     *        centered at the center of the element.
     *      @param {Number} [options.r2] (Required) Pixel radius of the end circle
     *        when this gesture ends.
     *      @param {Number} [options.duration=1000] (Optional) The duration of the
     *        gesture in milliseconds.
     *      @param {Number} [options.start=0] (Optional) Starting degree of the first
     *        finger. The value is relative to the path of the north. Default is 0
     *        (i.e., 12:00 on a clock).
     *      @param {Number} [options.rotation=0] (Optional) Degrees to rotate from
     *        the starting degree. A negative value means rotation to the
     *        counter-clockwise direction.
     *
     *      Valid options properties for the `rotate` gesture:
     *
     *      @param {Array} [options.center] (Optional) The center of the circle where
     *        two fingers are placed. Default is the center of the node element.
     *      @param {Number} [options.r1] (Optional) Pixel radius of the start circle
     *        where 2 fingers will be on when the gesture starts. The circles are
     *        centered at the center of the element. Default is a fourth of the node
     *        element width or height, whichever is smaller.
     *      @param {Number} [options.r2] (Optional) Pixel radius of the end circle
     *        when this gesture ends. Default is a fourth of the node element width or
     *        height, whichever is smaller.
     *      @param {Number} [options.duration=1000] (Optional) The duration of the
     *        gesture in milliseconds.
     *      @param {Number} [options.start=0] (Optional) Starting degree of the first
     *        finger. The value is relative to the path of the north. Default is 0
     *        (i.e., 12:00 on a clock).
     *      @param {Number} [options.rotation] (Required) Degrees to rotate from
     *        the starting degree. A negative value means rotation to the
     *        counter-clockwise direction.
     *
     * @param {Function} [cb] The callback to execute when the asynchronouse gesture
     *      simulation is completed.
     *      @param {Error} cb.err An error object if the simulation is failed.
     * @return {void}
     * @for Event
     * @static
     */
    Y.Event.simulateGesture = function(node, name, options, cb) {

        node = Y.one(node);

        var sim = new Y.GestureSimulation(node);
        name = name.toLowerCase();

        if(!cb && Y.Lang.isFunction(options)) {
            cb = options;
            options = {};
        }

        options = options || {};

        if (gestureNames[name]) {
            switch(name) {
                // single-touch: point gestures
                case 'tap':
                    sim.tap(cb, options.point, options.times, options.hold, options.delay);
                    break;
                case 'doubletap':
                    sim.tap(cb, options.point, 2);
                    break;
                case 'press':
                    if(!Y.Lang.isNumber(options.hold)) {
                        options.hold = DEFAULTS.HOLD_PRESS;
                    } else if(options.hold < DEFAULTS.MIN_HOLD_PRESS) {
                        options.hold = DEFAULTS.MIN_HOLD_PRESS;
                    } else if(options.hold > DEFAULTS.MAX_HOLD_PRESS) {
                        options.hold = DEFAULTS.MAX_HOLD_PRESS;
                    }
                    sim.tap(cb, options.point, 1, options.hold);
                    break;

                // single-touch: move gestures
                case 'move':
                    sim.move(cb, options.path, options.duration);
                    break;
                case 'flick':
                    sim.flick(cb, options.point, options.axis, options.distance,
                        options.duration);
                    break;

                // multi-touch: pinch/rotation gestures
                case 'pinch':
                    sim.pinch(cb, options.center, options.r1, options.r2,
                        options.duration, options.start, options.rotation);
                    break;
                case 'rotate':
                    sim.rotate(cb, options.center, options.r1, options.r2,
                        options.duration, options.start, options.rotation);
                    break;
            }
        } else {
            Y.error(NAME+': Not a supported gesture simulation: '+name);
        }
    };