////////////////////////////////////////////////////////////////////////////////
//
//  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.charts.chartClasses
{

import flash.events.Event;
import flash.events.EventDispatcher;
	
import mx.charts.LinearAxis;
import mx.core.mx_internal;
import mx.events.FlexEvent;

use namespace mx_internal;

//--------------------------------------
//  Events
//--------------------------------------

/**
 *  Dispatched when the transformation from data space to screen space
 *  has changed, typically either because the axes that make up
 *  the transformation have changed in some way,
 *  or the data transform itself has size.
 *
 *  @eventType mx.events.FlexEvent.TRANSFORM_CHANGE
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
[Event(name="transformChange", type="mx.events.FlexEvent")]

/**
 *  The DataTransform object represents a portion of a chart
 *  that contains glyphs and can transform values
 *  to screen coordinates and vice versa.
 *  Each DataTransform object has a horizontal axis, a vertical axis,
 *  and a set of glyphs (background, data, and overlay) to render.  
 *  
 *  <p>In theory, a chart can contain multiple overlaid DataTransform objects.
 *  This allows you to display a chart with multiple data sets
 *  rendered in the same area but with different ranges.
 *  For example, you might want to show monthly revenues
 *  compared to the number of units sold. 
 *  If revenue was typically in millions while units was typically
 *  in the thousands, it would be difficult to render these effectively
 *  along the same range.
 *  Overlaying them in different DataTransform objects allows
 *  the end user to compare trends in the values
 *  when they are rendered with different ranges.</p>
 *
 *  <p>Charts can only contain one set of DataTransform.</p>
 *  
 *  <p>Most of the time, you will use the ChartBase object,
 *  which hides the existance of the DataTransform object
 *  between the chart and its contained glyphs and axis objects.
 *  If you create your own ChartElement objects, you must understand
 *  the methods of the DataTransform class to correctly implement their element.</p>
 *  
 *  @langversion 3.0
 *  @playerversion Flash 9
 *  @playerversion AIR 1.1
 *  @productversion Flex 3
 */
public class DataTransform extends EventDispatcher
{
    include "../../core/Version.as";

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

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

    //----------------------------------
    //  axes
    //----------------------------------

    /**
     *  @private
     *  Storage for the axes property.
     */
    private var _axes:Object = {};
    
    [Inspectable(environment="none")]

    /**
     *  The set of axes associated with this transform.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function get axes():Object
    {
        return _axes;
    }

    //----------------------------------
    //  elements
    //----------------------------------

    /**
     *  @private
     */
    private var _elements:Array /* of ChartElement */ = [];

    [Inspectable(environment="none")]

    /**
     *  The elements that are associated with this transform.
     *  This Array includes background, series, and overlay elements
     *  associated with the transform.
     *  This value is assigned by the enclosing chart object.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function get elements():Array /* of ChartElement */
    {
        return _elements;
    }

    /**
     *  @private
     */
    public function set elements(value:Array /* of ChartElement */):void
    {
        _elements = value;  
    }

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Maps a set of numeric values representing data to screen coordinates. 
     *  This method assumes the values are all numbers,
     *  so any non-numeric values must have been previously converted
     *  with the <code>mapCache()</code> method.
     *
     *  @param cache An array of objects containing the data values
     *  in their fields. This is also where this function
     *  will store the converted numeric values.
     *
     *  @param xField The field where the data values for the x axis
     *  can be found.
     *
     *  @param xConvertedField The field where the mapped x screen coordinate
     *  will be stored.
     *
     *  @param yField The field where the data values for the y axis
     *  can be found.
     *
     *  @param yConvertedField The field where the mapped y screen coordinate
     *  will be stored.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */     
    public function transformCache(cache:Array /* of Object */,
                                   xField:String, xConvertedField:String,
                                   yField:String, yConvertedField:String):void
    {
    }

    /**
     *  Transforms x and y coordinates relative to the DataTransform
     *  coordinate system into a two-dimensional value in data space.
     *  
     *  @param ...values The x and y positions (in that order).
     *  
     *  @return An Array containing the transformed values.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */     
    public function invertTransform(...values):Array
    {
        return null;
    }

    /**
     *  Informs the DataTransform that some of the underlying data
     *  being represented on the chart has changed.
     *  The DataTransform generally has no knowledge of the source
     *  of the underlying data being represented by the chart,
     *  so glyphs should call this when their data changes
     *  so that the DataTransform can recalculate range scales
     *  based on their data.
     *  This does <b>not</b> invalidate the DataTransform,
     *  because there is no guarantee the data has changed.
     *  The axis objects (or range objects) must trigger an invalidate event.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function dataChanged():void
    {
        for (var p:String in _axes)
        {
            if (_axes[p])
                _axes[p].dataChanged();
        }
    }
    
    /**
     *  Collects important displayed values for all elements
     *  associated with this data transform.
     *  Axis instances call this method to collect the values
     *  they need to consider when auto-generating appropriate ranges.
     *  This method returns an Array of BoundedValue objects.
     *  
     *  <p>To collect important values for the horizontal axis
     *  of a CartesianTransform, pass 0.
     *  To collect values for the vertical axis, pass 1.</p>
     * 
     *  @param dimension The dimension to collect values for.
     *
     *  @param requiredFields Defines the data that are required
     *  by this transform.
     *  
     *  @return A Array of BoundedValue objects.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function describeData(dimension:String, requiredFields:uint):Array /* of BoundedValue */
    {
        var results:Array /* of BoundedValue */ = [];
        
        var n:int = elements.length;
        for (var i:int = 0; i < n; i++)
        {
            var dataGlyph:IChartElement = (elements[i] as IChartElement);
            if (!dataGlyph)
                continue;
            
            results = results.concat(
                dataGlyph.describeData(dimension, requiredFields));         
        }

        return results;
    }       
    
    /**
     *  Retrieves the axis instance responsible for transforming
     *  the data dimension specified by the <code>dimension</code> parameter.
     *  If no axis has been previously assigned, a default axis is created.
     *  The default axis for all dimensions is a LinearAxis
     *  with the <code>autoAdjust</code> property set to <code>false</code>. 
     *
     *  @param dimension The dimension whose axis is responsible
     *  for transforming the data.
     *  
     *  @return The axis instance.
     *  
     *  @see mx.charts.LinearAxis
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function getAxis(dimension:String):IAxis
    {
        if (!(_axes[dimension]))
        {
            var newAxis:LinearAxis = new LinearAxis();
            newAxis.autoAdjust = false;
            setAxisNoEvent(dimension,newAxis);
        }

        return _axes[dimension];
    }

    /**
     *  Assigns an axis instance to a particular dimension of the transform.
     *  Axis objects are assigned by the enclosing chart object.
     *  
     *  @param dimension The dimension of the transform.
     *  @param v The target axis instance.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function setAxis(dimension:String, v:IAxis):void
    {
			if(setAxisNoEvent(dimension, v))
        mappingChangeHandler();
    }

    /**
     *  @private
     */
		private function setAxisNoEvent(dimension:String, v:IAxis):Boolean
    {   
        var oldV:IAxis = _axes[dimension];
			if(oldV != v)
			{

        if (oldV)
        {
            oldV.unregisterDataTransform(this);
            oldV.removeEventListener("mappingChange", mappingChangeHandler);
        }

        _axes[dimension] = v;

        {
            v.registerDataTransform(this, dimension);
            v.addEventListener("mappingChange", mappingChangeHandler, false, 0, true);
        }       
				return true;
			}
			return false;
    }
    
    //--------------------------------------------------------------------------
    //
    //  Event handlers
    //
    //--------------------------------------------------------------------------

    /**
     *  @private 
     */
    private function mappingChangeHandler(event:Event = null):void
    {
        var n:int = elements.length;
        for (var i:int = 0; i < n; i++)
        {
            var g:IChartElement = elements[i] as IChartElement;
            if (g)
                g.mappingChanged();
        }
    }
}

}