////////////////////////////////////////////////////////////////////////////////
//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////

package mx.core
{

/**
 *  The DragSource class contains the data being dragged. The data can be in
 *  multiple formats, depending on the type of control that initiated the drag.
 *
 *  <p>Each format of data is identified with a string. The 
 *  <code>hasFormat()</code> method is used to determine if the object has
 *  data in that format. The <code>dataForFormat()</code> method is used
 *  to retrieve the data in the specified format.</p>
 *
 *  <p>Data can be added directly using the <code>addData()</code> method,
 *  or indirectly using the <code>addHandler()</code> method. The 
 *  <code>addHandler()</code> method registers a callback that will be called
 *  if the data is requested. This is useful for adding data in a non-native 
 *  format that may require large computations or conversions. For example, 
 *  if you have raw sound data you can add an MP3 format handler. The MP3 
 *  conversion will only be done if the MP3 data is requested.</p>
 *  
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
public class DragSource
{
	include "../core/Version.as";
	
	//--------------------------------------------------------------------------
	//
	//  Constructor
	//
	//--------------------------------------------------------------------------

	/**
	 *  Constructor.
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function DragSource()
	{
		super();
	}

	//--------------------------------------------------------------------------
	//
	//  Variables
	//
	//--------------------------------------------------------------------------

	/**
	 *  @private
	 */
	private var dataHolder:Object = {};	

	/**
	 *  @private
	 */
	private var formatHandlers:Object = {};

	//--------------------------------------------------------------------------
	//
	//  Properties
	//
	//--------------------------------------------------------------------------

	//----------------------------------
	//  formats
	//----------------------------------
	
	/**
	 *  @private
	 *  Storage for the formats property.
	 */
	private var _formats:Array /* of String */ = [];

	/**
	 *  Contains the formats of the drag data, as an Array of Strings.
	 *  Set this property using the <code>addData()</code>
	 *  or <code>addHandler()</code> methods.
	 *  The default value depends on data added to the DragSource object.
	 *
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function get formats():Array /* of String */
	{
		return _formats;
	}
	
	//--------------------------------------------------------------------------
	//
	//  Methods
	//
	//--------------------------------------------------------------------------

	/**
	 *  Adds data and a corresponding format String to the drag source.
	 *  This method does not return a value.
	 * 
	 *  @param data Object that specifies the drag data.
	 *  This can be any object, such as a String, a DataProvider, and so on.
	 *
	 *  @param format String that specifies a label that describes
	 *  the format for this data.
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function addData(data:Object, format:String):void
	{
		_formats.push(format);
		
		dataHolder[format] = data;
	}
	
	/**
	 *  Adds a handler that is called when data
	 *  for the specified format is requested. 
	 *  This is useful when dragging large amounts of data.
	 *  The handler is only called if the data is requested.
	 *  This method does not return a value.
	 *
	 *  @param handler Function that specifies the handler
	 *  called to request the data.
	 *  This function must return the data in the specified format.
	 *
	 *  @param format String that specifies the format for this data.
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function addHandler(handler:Function,
							   format:String):void
	{
		_formats.push(format);

		formatHandlers[format] = handler;
	}
	
	/**
	 *  Retrieves the data for the specified format.
	 *  If the data was added with the <code>addData()</code> method,
	 *  it is returned directly.
	 *  If the data was added with the <code>addHandler()</code> method,
	 *  the handler function is called to return the data.
	 *
	 *  @param format String that specifies a label that describes
	 *  the format for the data to return. This string can be a custom value
	 *  if you are creating a custom drop target with the <code>addData()</code> method. 
	 *  <p>List-based controls have predefined values 
	 *  for the <code>format</code> parameter. If the control that initiated the
	 *  drag operation is a Tree, then the format is "treeItems" and the items
	 *  implement the ITreeDataProvider interface. For all other List-based
	 *  controls that have built-in drag and drop support, the format is "items" and the items
	 *  implement the IDataProvider interface.</p>
	 *
	 *  @return An Object
	 *  containing the data in the requested format.
	 *  If you drag multiple items, the returned value is an Array. 
	 *  For a List-based control, the returned value is always an Array, 
	 *  even if it contains a single item.
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function dataForFormat(format:String):Object
	{
		var data:Object = dataHolder[format];
		if (data)
			return data;
		
		if (formatHandlers[format])
			return formatHandlers[format]();
		
		return null;
	}
	
	/**
	 *  Returns <code>true</code> if the data source contains
	 *  the requested format; otherwise, it returns <code>false</code>.
	 *
	 *  @param format String that specifies a label that describes the format 
	 *  for the data. 
	 *
	 *  @return <code>true</code> if the data source contains
	 *  the requested format.
	 *  
	 *  @langversion 3.0
	 *  @playerversion Flash 9
	 *  @playerversion AIR 1.1
	 *  @productversion Flex 3
	 */
	public function hasFormat(format:String):Boolean
	{
		var n:int = _formats.length;
		for (var i:int = 0; i < n; i++)
		{
			if (_formats[i] == format)
				return true;
		}
		
		return false;
	}
}

}