package flare.vis.operator.label
{
import flare.animate.Transitioner;
import flare.display.TextSprite;
import flare.util.Filter;
import flare.util.IEvaluable;
import flare.util.Property;
import flare.util.Shapes;
import flare.vis.data.Data;
import flare.vis.data.DataSprite;
import flare.vis.operator.Operator;
import flash.display.Sprite;
import flash.text.TextFormat;
/**
* Labeler that adds labels for items in a visualization. By default, this
* operator adds labels that are centered on each data sprite; this can be
* changed by configuring the offset and anchor settings.
*
* <p>Labelers support two different approaches for adding labels:
* <code>CHILD</code> mode (the default) and <code>LAYER</code> mode.
* <ul>
* <li>In <code>CHILD</code> mode, labels are added as children of
* <code>DataSprite</code> instances and so become part of the data
* sprite itself. In this mode, labels will automatically change
* position as data sprites are re-positioned.</li>
* <li>In <code>LAYER</code> mode, labels are instead added to a separate
* layer of the visualization above the
* <code>Visualization.marks</code> layer that contains the data
* sprites. A new layer will be created as needed and can be accessed
* through the <code>Visualization.labels</code> property. This mode
* is particularly useful for ensuring that no labels can be occluded
* by data marks. In <code>LAYER</code> mode, labels will not
* automatically move along with the labeled <code>DataSprite</code>
* instances if they are re-positioned. Instead, the labeler must be
* re-run to keep the layout current.</li>
* </ul></p>
*
* <p>To access created labels after a <code>Labeler</code> has been run,
* use the <code>props.label</code> property of a <code>DataSprite</code>.
* To have labels stored under a different property name, set the
* <code>access</code> property of this class to the desired name.</p>
*/
public class Labeler extends Operator
{
/** Constant indicating that labels be placed in their own layer. */
public static const LAYER:String = "layer";
/** Constant indicating that labels be added as children. */
public static const CHILD:String = "child";
/** @private */
protected var _policy:String;
/** @private */
protected var _labels:Sprite;
/** @private */
protected var _group:String;
/** @private */
protected var _filter:Function;
/** @private */
protected var _source:Property;
/** @private */
protected var _access:Property = Property.$("props.label");
/** @private */
protected var _cacheText:Boolean = true;
/** @private */
protected var _t:Transitioner;
/** The name of the property in which to store created labels.
* The default is "props.label". */
public function get access():String { return _access.name; }
public function set access(s:String):void { _access = Property.$(s); }
/** The name of the data group to label. */
public function get group():String { return _group; }
public function set group(g:String):void { _group = g; setup(); }
/** The source property that provides the label text. This
* property will be ignored if the <code>textFunction<code>
* property is non-null. */
public function get source():String { return _source.name; }
public function set source(s:String):void { _source = Property.$(s); }
/** Boolean function indicating which items to process. Only items
* for which this function return true will be considered by the
* labeler. If the function is null, all items will be considered.
* @see flare.util.Filter */
public function get filter():Function { return _filter; }
public function set filter(f:*):void { _filter = Filter.$(f); }
/** Boolean function indicating whether label text values should be
* cached or not. If set to true then the label text is calculated
* only the first time it's needed and re-used from them on. If set
* to false then the label is recalculated at each update. */
public function get cacheText():Boolean { return _cacheText; }
public function set cacheText(c:Boolean):void { _cacheText = c; }
/** A sprite containing the labels, if a layer policy is used. */
public function get labels():Sprite { return _labels; }
/** The policy for how labels should be applied.
* One of LAYER (for adding a separate label layer) or
* CHILD (for adding labels as children of data objects). */
public function get labelPolicy():String { return _policy; }
/** Optional function for determining label text. */
public var textFunction:Function = null;
/** The text format to apply to labels. */
public var textFormat:TextFormat;
/** The text mode to use for the TextSprite labels.
* @see flare.display.TextSprite */
public var textMode:int = TextSprite.BITMAP;
/** The horizontal alignment for labels.
* @see flare.display.TextSprite */
public var horizontalAnchor:int = TextSprite.CENTER;
/** The vertical alignment for labels.
* @see flare.display.TextSprite */
public var verticalAnchor:int = TextSprite.MIDDLE;
/** The default <code>x</code> value for labels. */
public var xOffset:Number = 0;
/** The default <code>y</code> value for labels. */
public var yOffset:Number = 0;
/**
* Creates a new Labeler.
* @param source the property from which to retrieve the label text.
* If this value is a string or property instance, the label text will
* be pulled directly from the named property. If this value is a
* Function or Expression instance, the value will be used to set the
* <code>textFunction<code> property and the label text will be
* determined by evaluating that function.
* @param group the data group to process
* @param format optional text formatting information for labels
* @param filter a Boolean-valued filter function determining which
* items will be given labels
* @param policy the label creation policy. One of LAYER (for adding a
* separate label layer) or CHILD (for adding labels as children of
* data objects)
*/
public function Labeler(source:*=n