package flare.scale
{
	/**
	 * Interface used by classes which support mapping between
	 * spatial (x,y) coordinates and values in a data scale. For example,
	 * both an axis or legend range should provide this functionality.
	 */
	public interface IScaleMap
	{
		/**
		 * Returns the x-coordinate corresponding to the lower end of the scale.
		 * @return the x-coordinate for the minimum value
		 */
		function get x1():Number;
		
		/**
		 * Returns the y-coordinate corresponding to the lower end of the scale.
		 * @return the y-coordinate for the minimum value
		 */
		function get y1():Number;
		
		/**
		 * Returns the x-coordinate corresponding to the upper end of the scale.
		 * @return the x-coordinate for the maximum value
		 */
		function get x2():Number;
		
		/**
		 * Returns the y-coordinate corresponding to the upper end of the scale.
		 * @return the y-coordinate for the maximum value
		 */
		function get y2():Number;
		
		/**
		 * Returns the scale value corresponding to a given coordinate.
		 * @param x the x-coordinate
		 * @param y the y-coordinate
		 * @param stayInBounds if true, x,y values outside the current layout
		 * bounds will be snapped to the bounds. If false, the value lookup
		 * will attempt to extrapolate beyond the scale bounds. This value
		 * is true be default.
		 * @return the scale value corresponding to the given coordinate.
		 */		
		function value(x:Number, y:Number, stayInBounds:Boolean=true):Object;
        
        /**
         * Returns the x-coordinate corresponding to the given scale value
         * @param val the scale value to lookup
         * @return the x-coordinate at which that scale value is placed
         */        
        function X(val:Object):Number;
        
        /**
         * Returns the y-coordinate corresponding to the given scale value
         * @param val the scale value to lookup
         * @return the y-coordinate at which that scale value is placed
         */
        function Y(val:Object):Number;
        
	} // end of interface IScaleMap
}