/**
 * @version 1.0
 * @author David Dahlstroem | daviddahlstroem.com
 * 
 * 
 * Copyright (c) 2009 David Dahlstroem | daviddahlstroem.com
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 *
 */

package org.tractionas3.display 
{
	import flash.display.DisplayObject;
	import org.tractionas3.core.Destructor;
	import org.tractionas3.core.interfaces.ICoreInterface;
	import org.tractionas3.core.interfaces.IDestructable;
	import org.tractionas3.events.EventReference;
	import org.tractionas3.events.IClearableEventDispatcher;
	import org.tractionas3.reflection.stringify;

	import flash.display.Sprite;
	import flash.events.Event;
	import flash.filters.BitmapFilter;
	/**
	 * CoreSprite is the core DisplayObject class of the TractionAS3 API.
	 */
	public class CoreSprite extends Sprite implements ICoreInterface, IClearableEventDispatcher
	{
		private var _filters:Array;

		private var _eventReferences:Array;

		/**
		 * Creates a new CoreSprite object.
		 */
		public function CoreSprite()
		{
			super();
			
			_eventReferences = [];
			
			addEventListener(Event.ADDED_TO_STAGE, onAddedToStageInternal);

			_filters = [];
		}

		/**
		 * @inheritDoc
		 */
		public function destruct(deepDestruct:Boolean = false):void
		{
			if(deepDestruct)
			{
				destructChildren(deepDestruct);
			}
			
			removeEventListener(Event.ADDED_TO_STAGE, onAddedToStageInternal);
			
			removeEventListener(Event.REMOVED_FROM_STAGE, onRemovedFromStageInternal);
			
			_filters = null;
			
			removeAllEventListeners();
			
			_eventReferences = null;
			
			Destructor.destruct(this, deepDestruct);
		}

		/**
		 * @inheritDoc
		 */
		public function listDestructableProperties():Array
		{
			return ["alpha", "buttonMode", "cacheAsBitmap", "contextMenu", "doubleClickEnabled", "dropTarget", "filters", "focusRect", "graphics", "height", "hitArea", "mask", "mouseChildren", "mouseEnabled", "opaqueBackground", "rotation", "scale9Grid", "scrollRect", "scaleX", "scaleY", "tabIndex", "tabEnabled", "useHandCursor", "visible", "x", "y"];
		}

		/**
		 * Iterates through all the children in the displaylist and calls the <code>destruct()</code> method on them, them removes them from the display list.
		 * Only applies to children implementing the <code>org.tractionas3.core.Destructable</code> interface.
		 * 
		 * @see org.tractionas3.core.Destructable
		 */
		public function destructChildren(deepDestruct:Boolean = false):void
		{
			var child:DisplayObject;
			
			for(var i:int = 0;i < numChildren;++i)
			{
				child = getChildAt(i);
				
				if(child is IDestructable)
				{
					IDestructable(child).destruct(deepDestruct);
				}
			}
			
			removeChildren();
		}

		/**
		 * Returns a string representation of the CoreSprite instance.
		 * Part of the string returned is a display display hierarchy indication.
		 */
		override public function toString():String
		{
			return stringify(this);
		}

		/**
		 * Defines the scale of the CoreSprite instance in aspect ratio 1:1.
		 */
		public function get scale():Number
		{
			return (scaleX >= scaleY) ? scaleX : scaleY;
		}

		public function set scale(value:Number):void
		{
			scaleX = scaleY = value;
		}

		/**
		 * Indicates whether the CoreSprite is a child to application stage. 
		 */
		public function get hasStage():Boolean
		{
			return stage != null;
		}

		/**
		 * Adds multiple chidren to the CoreSprite instance.
		 * 
		 * @param children DisplayObject instances added to CoreSprite display list.
		 */
		public function addChildren(...children:Array):void 
		{
			for (var i:int = 0;i < children.length;++i) 
			{
				addChild(children[i]);
			}
		}

		/**
		 * Removes multiple children to the CoreSprite instance.
		 * 
		 * @param children DisplayObject instances removed to CoreSprite display list.
		 * If no arguments are passed all children are removed.
		 */
		public function removeChildren(...children:Array):void 
		{
			var i:int;
			
			if(children.length > 0) 
			{
				for (i = 0;i < children.length;++i) 
				{
					removeChild(children[i]);
				}
			} 
			else 
			{
				var numChildren:int = numChildren;
				
				for (i = 0;i < numChildren;++i) 
				{
					removeChildAt(0);
				}                       
			}
		}

		/**
		 * Called when the CoreSprite instance is added to stage.
		 * When extending CoreSprite, overriding this method will implement custom functionality.
		 */
		protected function onAddedToStage():void
		{
			return;
		}

		/**
		 * Called when the CoreSprite instance is removed from stage.
		 * When extending CoreSprite, overriding this method will implement custom functionality.
		 */
		protected function onRemovedFromStage():void
		{
			return;
		}

		/**
		 * Dispatches an event into the event flow, <i>only</i> if event property <code>hasEventListener</code> or <code>bubbles</code> are <code>true</code>. 
		 */
		override public function dispatchEvent(evt:Event):Boolean 
		{
			if (hasEventListener(evt.type) || evt.bubbles) 
			{
				return super.dispatchEvent(evt);
			}
			return true;
		}

		/**
		 * Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
		 * 
		 * @param useWeakReference In CoreSprite class this parameter is set to <code>true</code> by default.
		 * This is to more easily mark the CoreSprite instance for garbage collection.
		 */
		override public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = true):void
		{
			_eventReferences.push(new EventReference(type, listener, useCapture));
			
			super.addEventListener(type, listener, useCapture, priority, useWeakReference);
		}

		/**
		 * Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.
		 */
		override public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
		{
			removeEventReference(type, listener, useCapture);
			
			super.removeEventListener(type, listener, useCapture);
		}

		/**
		 * @inheritDoc
		 */
		public function removeAllEventListeners():uint
		{
			var eventReference:EventReference;
			
			var n:uint = 0;
			
			for(var i:int = 0;i < _eventReferences.length;++i)
			{
				eventReference = _eventReferences[i] as EventReference;
				
				super.removeEventListener(eventReference.type, eventReference.listener, eventReference.useCapture);
	
				eventReference.destruct();
				
				eventReference = null;
				
				n++;
			}
			
			_eventReferences = [];
			
			return n;
		}
		
		/**
		 * @inheritDoc
		 */
		public function removeEventListenersWithType(type:String):uint
		{
			var eventReference:EventReference;
			
			var n:uint = 0;
			
			for(var i:int = 0;i < _eventReferences.length;++i)
			{
				eventReference = _eventReferences[i] as EventReference;
				
				if(eventReference.type == type)
				{
					_eventReferences.splice(i, 1);
					
					super.removeEventListener(eventReference.type, eventReference.listener, eventReference.useCapture);
					
					eventReference.destruct();
					
					n++;
				}
			}
			
			return n;
		}
		
		/**
		 * @inheritDoc
		 */
		
		public function removeEventListenersOf(listener:Function):uint
		{
			var eventReference:EventReference;
			
			var n:uint = 0;
			
			for(var i:int = 0;i < _eventReferences.length;++i)
			{
				eventReference = _eventReferences[i] as EventReference;
				
				if(eventReference.listener == listener)
				{
					_eventReferences.splice(i, 1);
					
					super.removeEventListener(eventReference.type, eventReference.listener, eventReference.useCapture);
					
					eventReference.destruct();
					
					n++;
				}
			}
			
			return n;
		}

		/**
		 * @inheritDoc
		 */
		public function get numEventListeners():uint
		{
			return _eventReferences.length;
		}

		/**
		 * An indexed array that contains each filter object currently associated with the CoreSprite.
		 * <p />
		 * CoreSprite implements a modified filter structure allowing you to add and remove any specified filter.
		 * You can explicitly add or remove filters using the <code>adddFilter()</code> or <code>removeFilter()</code> methods.
		 * Changing property of a filter requires an <code>updateFilters()</code> method call, however adding or removing a filter does not.
		 * 
		 * @see #addFilter()
		 * @see #removeFilter()
		 * @see #updateFilters()
		 * @see #hasFilter()
		 * 
		 */
		override public function get filters():Array
		{
			return _filters;
		}

		override public function set filters(value:Array):void
		{
			_filters = value;
			
			super.filters = _filters;
		}

		/**
		 * Adds a new filter to the CoreSprite.
		 */
		public function addFilter(filter:BitmapFilter):BitmapFilter
		{
			_filters.push(filter);
			
			filters = _filters;
			
			return filter;
		}

		/**
		 * Removes specified filter from CoreSprite
		 */
		public function removeFilter(filter:BitmapFilter):void
		{
			for(var i:int = 0;i < _filters.length;++i)
			{
				if(_filters[i] === filter)
				{
					_filters.splice(i, 1);
					break;
				}
			}
			
			filters = _filters;
		}

		/**
		 * Reapplies the filters to the CoreSprite. After changing properties in filters applied to CoreSprite, call this method to update their display.
		 */
		public function updateFilters():void
		{
			filters = filters;
		}

		/**
		 * Indicates whether specified filter is applied to CoreSprite.
		 */
		public function hasFilter(filter:BitmapFilter):Boolean
		{
			return filters.indexOf(filter) > -1;
		}

		/**
		 * @private
		 */
		protected function onAddedToStageInternal(e:Event = null):void
		{
			onAddedToStage();
			
			addEventListener(Event.REMOVED_FROM_STAGE, onRemovedFromStageInternal);
			
			removeEventListener(Event.ADDED_TO_STAGE, onAddedToStageInternal);
		}

		/**
		 * @private
		 */
		protected function onRemovedFromStageInternal(e:Event = null):void
		{
			onRemovedFromStage();
			
			addEventListener(Event.ADDED_TO_STAGE, onAddedToStageInternal);
			
			removeEventListener(Event.REMOVED_FROM_STAGE, onRemovedFromStageInternal);
		}

		private function removeEventReference(type:String, listener:Function, useCapture:Boolean):void
		{
			var eventReference:EventReference;
			
			for(var i:int = 0;i < _eventReferences.length;++i)
			{
				eventReference = _eventReferences[i] as EventReference;
				
				if(eventReference.type === type && eventReference.listener === listener && eventReference.useCapture === useCapture)
				{
					_eventReferences.splice(i, 1);
					
					eventReference.destruct();
					
					removeEventReference(type, listener, useCapture);
					
					return;
				}
			}
		}
	}
}