package flare.vis
{
import flare.animate.ISchedulable;
import flare.animate.Scheduler;
import flare.animate.Transitioner;
import flare.util.Displays;
import flare.vis.axis.Axes;
import flare.vis.axis.CartesianAxes;
import flare.vis.controls.ControlList;
import flare.vis.data.Data;
import flare.vis.data.Tree;
import flare.vis.events.DataEvent;
import flare.vis.events.VisualizationEvent;
import flare.vis.operator.IOperator;
import flare.vis.operator.OperatorList;
import flash.display.DisplayObject;
import flash.display.Sprite;
import flash.events.Event;
import flash.geom.Rectangle;
[Event("update", type="flare.vis.events.VisualizationEvent")]
/**
* The Visualization class represents an interactive data visualization.
* A visualization instance consists of
* <ul>
* <li>A <code>Data</code> instance containing <code>DataSprite</code>
* objects that visually represent individual data elements</li>
* <li>An <code>OperatorList</code> of visualization operators that
* determine visual encodings for position, color, size and other
* properties.</li>
* <li>A <code>ControlList</code> of interactive controls that enable
* interaction with the visualized data.</li>
* <li>An <code>Axes</code> instance for presenting axes for metric
* data visualizations. Axes are often configuring automatically by
* the visualization's operators.</li>
* </ul>
*
* <p>Visual objects are added to the display list within the
* <code>marks</code> property of the visualization, as the
* <code>Data</code> object is not a <code>DisplayObjectContainer</code>.
* </p>
*
* <p>All visual elements are contained within <code>layers</code> Sprite.
* This includes the <code>axes</code>, <code>marks</code>, and
* (optionally) <code>labels</code> layers. Clients who wish to add
* additional layers to a visualization should add them directly to the
* <code>layers</code> sprite. Just take care to maintain the desired order
* of elements to avoid occlusion.</p>
*
* <p>To create a new Visualization, load in a data set, construct
* a <code>Data</code> instance, and instantiate a new
* <code>Visualization</code> with the input data. Then add the series
* of desired operators to the <code>operators</code> property to
* define the visual encodings.</p>
*
* @see flare.vis.operator
*/
public class Visualization extends Sprite
{
protected var _bounds:Rectangle = new Rectangle(0,0,500,500);
protected var _layers:Sprite; protected var _marks:Sprite; protected var _labels:Sprite; protected var _axes:Axes;
protected var _data:Data;
protected var _ops:Object; protected var _operators:OperatorList; protected var _controls:ControlList; protected var _rec:ISchedulable;
/** An object storing extra properties for the visualziation. */
public var props:Object = {};
/** The layout bounds of the visualization. This determines the layout
* region for data elements. For example, with an axis layout, the
* bounds determined the data layout region--this does not include
* space used by axis labels. */
public function get bounds():Rectangle { return _bounds; }
public function set bounds(r:Rectangle):void {
_bounds = r;
if (stage) stage.invalidate();
}
/** Container sprite holding each layer in the visualization. */
public function get layers():Sprite { return _layers; }
/** Sprite containing the <code>DataSprite</code> instances. */
public function get marks():Sprite { return _marks; }
/** Sprite containing a separate layer for labels. Null by default. */
public function get labels():Sprite { return _labels; }
public function set labels(l:Sprite):void {
if (_labels != null)
_layers.removeChild(_labels);
_labels = l;
if (_labels != null) {
_labels.name = "_labels";
_layers.addChildAt(_labels, _layers.getChildIndex(_marks)+1);
}
}
/**
* The axes for this visualization. May be null if no axes are needed.
*/
public function get axes():Axes { return _axes; }
public function set axes(a:Axes):void {
if (_axes != null)
_layers.removeChild(_axes);
_axes = a;
if (_axes != null) {
_axes.visualization = this;
_axes.name = "_axes";
_layers.addChildAt(_axes, 0);
}
}
/** The axes as an x-y <code>CartesianAxes</code> instance. Returns
* null if <code>axes</code> is null or not a cartesian axes instance.
*/
public function get xyAxes():CartesianAxes { return _axes as CartesianAxes; }
/** The visual data elements in this visualization. */
public function get data():Data { return _data; }
/** Tree structure of visual data elements in this visualization.
* Generates a spanning tree over a graph structure, if necessary. */
public function get tree():Tree { return _data.tree; }
public function set data(d:Data):void
{
if (_data != null) {
_data.visit(_marks.removeChild);
_data.removeEventListener(DataEvent.ADD, dataAdded);
_data.removeEventListener(DataEvent.REMOVE, dataRemoved);
}
_data = d;
if (_data != null) {
_data.visit(_marks.addChild);
_data.addEventListener(DataEvent.ADD, dataAdded);
_data.addEventListener(DataEvent.REMOVE, dataRemoved);
}
}
/** The operator list for defining the visual encodings. */
public function get operators():OperatorList { return _operators; }
/** The control list containing interactive controls. */
public function get controls():ControlList { return _controls; }
/** Flag indicating if the visualization should update with every
* frame. False by default. */
public function get continuousUpdates():Boolean { return _rec != null; }
public function set continuousUpdates(b:Boolean):void
{
if (b && _rec==null) {
_rec = new Recurrence(this);
Scheduler.instance.add(_rec);
}
else if (!b && _rec!=null) {
Scheduler.instance.remove(_rec);
_rec = null;
}
}
/**
* Creates a new Visualization with the given data and axes.
* @param data the <code>Data</code> instance containing the
* <code>DataSprite</code> elements in this visualization.
* @param axes the <code>Axes</code> to use with this visualization.
* Null by default; layout operators may re-configure the axes.
*/
public function Visualization(data:Data=null, axes:Axes=null) {
addChild(_layers = new Sprite());
_layers.name = "_layers";
_layers.addChild(_marks = new Sprite());
_marks.name = "_marks";
if (data != null) this.data = data;
if (axes != null) this.axes = axes;
_operators = new OperatorList();
_operators.visualization = this;
_ops = { main:_operators };
_controls = new ControlList();
_controls.visualization = this;
Displays.addStageListener(this, Event.RENDER,
setHitArea, false, int.MIN_VALUE+1);
}
/**
* Update this visualization, re-calculating axis layout and running
* the operator chain. The input transitioner is used to actually
* perform value updates, enabling animated transitions. This method
* also issues a <code>VisualizationEvent.UPDATE</code> event to any
* registered listeners.
* @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.
* @param operators an optional list of named operators to run in the
* update.
* @return the transitioner used to store updated values.
*/
public function update(t:*=n