scaffold.libs_as.starling.events.TouchEvent.as Maven / Gradle / Ivy

Go to download
// =================================================================================================
//
//	Starling Framework
//	Copyright 2011-2015 Gamua. All Rights Reserved.
//
//	This program is free software. You can redistribute and/or modify it
//	in accordance with the terms of the accompanying license agreement.
//
// =================================================================================================

package starling.events
{
    import starling.core.starling_internal;
    import starling.display.DisplayObject;

    use namespace starling_internal;
    
    /** A TouchEvent is triggered either by touch or mouse input.  
     *  
     *  In Starling, both touch events and mouse events are handled through the same class: 
     *  TouchEvent. To process user input from a touch screen or the mouse, you have to register
     *  an event listener for events of the type TouchEvent.TOUCH. This is the only
     *  event type you need to handle; the long list of mouse event types as they are used in
     *  conventional Flash are mapped to so-called "TouchPhases" instead. 
     * 
     *  The difference between mouse input and touch input is that
     *  
     *  
     *    only one mouse cursor can be present at a given moment and
     *    only the mouse can "hover" over an object without a pressed button.
     *   
     *  
     *  Which objects receive touch events?
     * 
     *  In Starling, any display object receives touch events, as long as the  
     *  touchable property of the object and its parents is enabled. There 
     *  is no "InteractiveObject" class in Starling.
     *  
     *  How to work with individual touches
     *  
     *  The event contains a list of all touches that are currently present. Each individual
     *  touch is stored in an object of type "Touch". Since you are normally only interested in 
     *  the touches that occurred on top of certain objects, you can query the event for touches
     *  with a specific target:
     * 
     *  var touches:Vector.<Touch> = touchEvent.getTouches(this);
     *  
     *  This will return all touches of "this" or one of its children. When you are not using 
     *  multitouch, you can also access the touch object directly, like this:
     * 
     *  var touch:Touch = touchEvent.getTouch(this);
     *  
     *  @see Touch
     *  @see TouchPhase
     */ 
    public class TouchEvent extends Event
    {
        /** Event type for touch or mouse input. */
        public static const TOUCH:String = "touch";
        
        private var _shiftKey:Boolean;
        private var _ctrlKey:Boolean;
        private var _timestamp:Number;
        private var _visitedObjects:Vector.;
        
        /** Helper object. */
        private static var sTouches:Vector. = new [];
        
        /** Creates a new TouchEvent instance. */
        public function TouchEvent(type:String, touches:Vector., shiftKey:Boolean=false, 
                                   ctrlKey:Boolean=false, bubbles:Boolean=true)
        {
            super(type, bubbles, touches);
            
            _shiftKey = shiftKey;
            _ctrlKey = ctrlKey;
            _timestamp = -1.0;
            _visitedObjects = new [];
            
            var numTouches:int=touches.length;
            for (var i:int=0; i _timestamp)
                    _timestamp = touches[i].timestamp;
        }
        
        /** Returns a list of touches that originated over a certain target. If you pass an
         *  out-vector, the touches will be added to this vector instead of creating
         *  a new object. */
        public function getTouches(target:DisplayObject, phase:String=null,
                                   out:Vector.=null):Vector.
        {
            if (out == null) out = new [];
            var allTouches:Vector. = data as Vector.;
            var numTouches:int = allTouches.length;
            
            for (var i:int=0; i 0) 
            {
                var touch:Touch = null;
                
                if (id < 0) touch = sTouches[0];
                else
                {
                    for (var i:int=0; i=0; --i)
            {
                if (sTouches[i].phase != TouchPhase.ENDED)
                {
                    result = true;
                    break;
                }
            }
            
            sTouches.length = 0;
            return result;
        }
        
        // custom dispatching
        
        /** @private
         *  Dispatches the event along a custom bubble chain. During the lifetime of the event,
         *  each object is visited only once. */
        internal function dispatch(chain:Vector.):void
        {
            if (chain && chain.length)
            {
                var chainLength:int = bubbles ? chain.length : 1;
                var previousTarget:EventDispatcher = target;
                setTarget(chain[0] as EventDispatcher);
                
                for (var i:int=0; i { return (data as Vector.).concat(); }
        
        /** Indicates if the shift key was pressed when the event occurred. */
        public function get shiftKey():Boolean { return _shiftKey; }
        
        /** Indicates if the ctrl key was pressed when the event occurred. (Mac OS: Cmd or Ctrl) */
        public function get ctrlKey():Boolean { return _ctrlKey; }
    }
}