legend.as

用于flash/flex的 as3的 2D图形图像图表的动态生成

		 *    This value is not required.</li>
		 *  <li><code>label</code>: The text label to place in the legend item.
		 *    If this value is not provided, the method will attempt to
		 *    generate a label string from the <code>value</code> property.</li>
		 *  <li><code>color</code>: The color for the legend item. If missing,
		 *    this legend's default color will be used.</li>
		 *  <li><code>shape</code>: The shape for the legend item. If missing,
		 *    a default circle shape will be used.</li>
		 *  <li><code>size</code>: The size for the legend item. If missing,
		 *    a size value of 1 will be used.</li>
		 * </ul>
		 * When this method is called, any previous values in the legend will
		 * be removed.
		 * @param values an array of value to include in the legend.
		 */
		public function buildFromValues(values:Array):void
		{
			// first, remove all items
			while (_items.numChildren > 0) {
				_items.removeChildAt(_items.numChildren-1);
			}
			_discrete = true;
			if (!_orient) _orient = Orientation.TOP_TO_BOTTOM;
			
			var maxSize:Number = Number.MIN_VALUE;
			for each (var v:Object in values) {
				var value:Object = v.value != undefined ? v.value : null;
				var label:String = v.label ? v.label.toString() : value ? value.toString() : "???";
				var color:uint = v.color != undefined ? uint(v.color) : _defaultColor;
				var shape:String = v.shape ? v.shape as String : null;
				var size:Number = _baseIconSize*(v.size is Number ? v.size : 1);
				if (size > maxSize) maxSize = size;
				
				var item:LegendItem = new LegendItem(label, color, shape, size);
				item.value = value;
				item.margin = margin;
				_items.addChild(item);
			}
			for (var i:uint=0; i<_items.numChildren; ++i)
				LegendItem(_items.getChildAt(i)).maxIconSize = maxSize;
		}
		
		// -- Layout ----------------------------------------------------------
		
		/**
		 * Performs layout, setting the position for all items in the legend.
		 * @param t a transitioner for value updates
		 */
		public function layout(t:Transitioner=null):void
		{
			t = (t ? t : Transitioner.DEFAULT);
			
			var vert:Boolean = Orientation.isVertical(_orient);
			var o:Object;
			var b:Rectangle = bounds;
			var x:Number = b ? b.left : 0;
			var y:Number = b ? b.top : 0;
			var w:Number, h:Number, th:Number = 0;
			
			// layout the title
			o = t.$(_title);
			if (_title.text != null && _title.text.length > 0) {
				o.x = x + _margin;
				o.alpha = 1;
				_title.visible = true;
				y += (th = _title.height + (vert?_spacing:0));
			} else {
				o.alpha = 0;
				o.visible = false;
			}
			
			// layout item container
			o = t.$(_items);
			o.x = x;
			o.y = y;
			
			// layout items
			if (_discrete) {
				layoutDiscrete(t);
			} else {
				layoutContinuous(t);
			}
			
			w = b ? (vert ? b.width : Math.min(_iw, b.width)) : _iw;
			h = b ? (vert ? Math.min(_ih, b.height) : _ih) : _ih;
			
			// size the border
			o = t.$(_border);
			o.x = x;
			o.y = b ? b.top : 0;
			o.w = w;
			o.h = h + th;
			if (t.immediate) _border.render();
			
			// create clipping panel
			t.$(items).scrollRect = new Rectangle(0, 0, 1+w, 1+h);
		}
		
		/**
		 * @private
		 * Layout helper for positioning discrete legend items.
		 * @param t a transitioner for value updates
		 */
		protected function layoutDiscrete(t:Transitioner):void
		{
			var vert:Boolean = Orientation.isVertical(_orient);
			var rev:Boolean = _orient == Orientation.RIGHT_TO_LEFT ||
							  _orient == Orientation.BOTTOM_TO_TOP;
			var x:Number = 0, y:Number = 0, i:uint, j:uint;
			var item:LegendItem, o:Object;
			var bw:Number = vert && bounds ? bounds.width : NaN;
			
			// if needed, compute shared width for legend items
			if (vert && isNaN(bw)) {
				bw = Number.MIN_VALUE;
				for (i=0; i<_items.numChildren; ++i) {
					item = _items.getChildAt(i) as LegendItem;
					bw = Math.max(bw, item.innerWidth);
				}
			}
			
			_iw = _ih = 0;
			for (i=0; i<_items.numChildren; ++i) {
				j = rev ? _items.numChildren-i-1 : i;
				// layout the item
				item = _items.getChildAt(j) as LegendItem;
				o = t.$(item);
				o.x = x;
				o.y = y;
				o.w = isNaN(bw) ? item.innerWidth : bw;
				
				// increment spacing
				if (vert) {
					y += item.innerHeight + _spacing;
					_iw = Math.max(_iw, item.innerWidth);
				}
				else {
					x += item.innerWidth + _spacing;
					_ih = Math.max(_ih, item.innerHeight);
				}
			}
			_iw = vert ? _iw : x-_spacing;
			_ih = vert ? y-_spacing : _ih;
		}
		
		/**
		 * @private
		 * Layout helper for positioning a continous legend range.
		 * @param trans a transitioner for value updates
		 */
		protected function layoutContinuous(t:Transitioner):void
		{
			var lr:LegendRange = _items.getChildAt(0) as LegendRange;
			lr.orientation = _orient;
			if (Orientation.isHorizontal(_orient)) {
				_iw = lr.w = bounds ? bounds.width : 200;
				lr.updateLabels();
				_ih = lr.height + lr.margin;
			} else {
				_ih = lr.h = bounds ? bounds.height : 200;
				lr.updateLabels();
				_iw = lr.width;
			}
		}
		
		// -- Legend Items ----------------------------------------------------
		
		/** @private */
		protected function updateItems() : void
		{
			if (_items.numChildren == 0) {
				return;
			} else if (_discrete) {
				for (var i:uint = 0; i<_items.numChildren; ++i)
					updateItem(_items.getChildAt(i) as LegendItem);
			} else {
				updateRange(_items.getChildAt(0) as LegendRange);
			}
		}
		
		/** @private */
		protected function updateItem(item:LegendItem):void
		{
			item.label.textMode = _labelTextMode;
			item.label.applyFormat(_labelTextFormat);
			item.margin = _margin;
		}
		
		/** @private */
		protected function updateRange(range:LegendRange):void
		{
			range.labelTextMode = _labelTextMode;
			range.labelTextFormat = _labelTextFormat;
			range.margin = _margin;
		}
		
		/**
		 * Sets property values on all legend items. The values
		 * within the <code>vals</code> argument can take a number of forms:
		 * <ul>
		 *  <li>If a value is a <code>Function</code>, it will be evaluated
		 *      for each element and the result will be used as the property
		 *      value for that element.</li>
		 *  <li>If a value is an <code>IEvaluable</code> instance, such as
		 *      <code>flare.util.Property</code> or
		 *      <code>flare.query.Expression</code>, it will be evaluated for
		 *      each element and the result will be used as the property value
		 *      for that element.</li>
		 *  <li>In all other cases, a property value will be treated as a
		 *      literal and assigned for all elements.</li>
		 * </ul>
		 * @param vals an object containing the properties and values to set.
		 * @param t a transitioner or time span for updating object values. If
		 *  the input is a transitioner, it will be used to store the updated
		 *  values. If the input is a number, a new Transitioner with duration
		 *  set to the input value will be used. The input is null by default,
		 *  in which case object values are updated immediately.
		 * @return the transitioner used to update the values
		 */
		public function setItemProperties(vals:Object, t:*=null):Transitioner
		{
			var trans:Transitioner = Transitioner.instance(t);
			Displays.setChildrenProperties(items, vals, trans);
			return trans;
		}
		
		// -- Static Constructors ---------------------------------------------
		
		/**
		 * Generates a legend from a given scale and one or more palettes.  If
		 * multiple palettes of the same type are provided, only the first of
		 * each type will be used for the legend, the others will be ignored.
		 * @param title the title text for the legend
		 * @param scale the scale instance determining the legend values
		 * @param palette a color, shape, or size palette for legend items
		 * @param args one or more additional palettes
		 * @return the generated Legend, or null if a legend could not be built
		 */
		public static function fromScale(title:String, scale:Scale,
			palette:Palette, ...args):Legend
		{
			if (scale == null || palette == null)
				return null;
				
			var colors:ColorPalette;
			var shapes:ShapePalette;
			var sizes:SizePalette;
			
			// construct palette collection
			var palettes:Array = args as Array;
			palettes.unshift(palette);
			for each (var p:Palette in palettes) {
				if (p is ColorPalette && !colors)
					colors = ColorPalette(p);
				else if (p is ShapePalette && !shapes)
					shapes = ShapePalette(p);
				else if (p is SizePalette && !sizes)
					sizes = SizePalette(p);
			}
			if (!colors && !shapes && !sizes)
				return null; // no palette to use
			
			return new Legend(title, scale, colors, shapes, sizes);
		}
		
		/**
		 * Generates a legend from an array of legend item values. This method
		 * simply instantiates a new <code>Legend</code> instance with the
		 * given title and then invokes the <code>buildFromValues</code> method
		 * with the given value array.
  		 * @param title the legend title text, or null for no title.
  		 * @param values an array of values for the legend items. See the
		 *  documentation for the <code>buildFromValues</code> method for more.
		 * @return the generated legend
		 */
		public static function fromValues(title:String, values:Array):Legend
		{
			var legend:Legend = new Legend(title);
			legend.buildFromValues(values);
			legend.update();
			return legend;
		}
		
	} // end of class Legend
}