Packageflare.vis.legend
Classpublic class Legend
InheritanceLegend Inheritance flash.display.Sprite

A legend describing the visual encoding of a data property. Legends support both discrete legends that list individual items and range legends the convey a continuous range of values. Discrete legends consist of a collection of LegendItem instances stored in the items sprite. Range legends consist of a single LegendRange instance stored in the items sprite.

There are multiple ways to generate a legend. To build a legend based on an existing visual encoding, use the static fromScale constructor. This method takes a data scale and one more or more palettes (e.g., color, shape, or size palettes) and uses them to generate an appropriate legend. If the data scale is a quantitative scale and only a color palette is provided, a continuous range legend will be generated. Otherwise, a discrete legend will be created.

Legends can also be created from a collection of independent values using the static fromValues constructor. This method takes an array of legend item descriptions and uses them to generate a legend. For example, consider this code:

  var legend:Legend = Legend.fromValues("Legend Title", [
    {color: 0xff0000, shape:Shapes.X, label:"Red X"},
    {color: 0x00ff00, shape:Shapes.SQUARE, label:"Green Square"},
    {color: 0x0000ff, shape:Shapes.CIRCLE, label:"Blue Circle"}
  ]);
  

This example will create a legend with the described values. See the documentation for the buildFromValues method for more details.



Public Properties
 PropertyDefined by
  baseIconSize : Number
Base icon size, corresponding to a size factor of 1.
Legend
  border : RectSprite
[read-only] Sprite defining the border of the legend.
Legend
  bounds : Rectangle
The layout bounds for this legend instance.
Legend
  colorPalette : ColorPalette
The color palette used to encode values (may be null).
Legend
  defaultColor : uint
The default color to use for legend items.
Legend
  discrete : Boolean
[read-only] Flag indicating if this legend is discrete or continuous.
Legend
  items : Sprite
[read-only] Sprite containing the legend items.
Legend
  labelTextFormat : TextFormat
TextFormat (font, size, style) of legend item labels.
Legend
  labelTextMode : int
Label text mode.
Legend
  margin : Number
Margins within legend items.
Legend
  orientation : String
The desired orientation of this legend.
Legend
  range : LegendRange
[read-only] The legend range, if this legend is continuous.
Legend
  scale : Scale
Scale instance used to define the legend mapping.
Legend
  shapePalette : ShapePalette
The shape palette used to encode values (may be null).
Legend
  sizePalette : SizePalette
The size palette used to encode values (may be null).
Legend
  spacing : Number
Spacing between legend items.
Legend
  title : TextSprite
[read-only] TextSprite containing the legend title.
Legend
Public Methods
 MethodDefined by
  
Legend(title:String, scale:Scale = null, colors:ColorPalette = null, shapes:ShapePalette = null, sizes:SizePalette = null)
Creates a new Legend for the given data field.
Legend
  
Builds the contents of this legend from the current scale values.
Legend
  
buildFromValues(values:Array):void
Populates the contents of this legend from a list of value objects.
Legend
  
fromScale(title:String, scale:Scale, palette:Palette, ... args):Legend
[static] Generates a legend from a given scale and one or more palettes.
Legend
  
fromValues(title:String, values:Array):Legend
[static] Generates a legend from an array of legend item values.
Legend
  
layout(t:Transitioner = null):void
Performs layout, setting the position for all items in the legend.
Legend
  
setItemProperties(vals:Object, t:* = null):Transitioner
Sets property values on all legend items.
Legend
  
Update the legend, recomputing layout of items.
Legend
Property detail
baseIconSizeproperty
baseIconSize:Number  [read-write]

Base icon size, corresponding to a size factor of 1.

Implementation
    public function get baseIconSize():Number
    public function set baseIconSize(value:Number):void
borderproperty 
border:RectSprite  [read-only]

Sprite defining the border of the legend.

Implementation
    public function get border():RectSprite
boundsproperty 
bounds:Rectangle  [read-write]

The layout bounds for this legend instance.

Implementation
    public function get bounds():Rectangle
    public function set bounds(value:Rectangle):void
colorPaletteproperty 
colorPalette:ColorPalette  [read-write]

The color palette used to encode values (may be null).

Implementation
    public function get colorPalette():ColorPalette
    public function set colorPalette(value:ColorPalette):void
defaultColorproperty 
defaultColor:uint  [read-write]

The default color to use for legend items.

Implementation
    public function get defaultColor():uint
    public function set defaultColor(value:uint):void
discreteproperty 
discrete:Boolean  [read-only]

Flag indicating if this legend is discrete or continuous.

Implementation
    public function get discrete():Boolean
itemsproperty 
items:Sprite  [read-only]

Sprite containing the legend items.

Implementation
    public function get items():Sprite
labelTextFormatproperty 
labelTextFormat:TextFormat  [read-write]

TextFormat (font, size, style) of legend item labels.

Implementation
    public function get labelTextFormat():TextFormat
    public function set labelTextFormat(value:TextFormat):void
labelTextModeproperty 
labelTextMode:int  [read-write]

Label text mode.

Implementation
    public function get labelTextMode():int
    public function set labelTextMode(value:int):void
marginproperty 
margin:Number  [read-write]

Margins within legend items.

Implementation
    public function get margin():Number
    public function set margin(value:Number):void
orientationproperty 
orientation:String  [read-write]

The desired orientation of this legend.

Implementation
    public function get orientation():String
    public function set orientation(value:String):void
rangeproperty 
range:LegendRange  [read-only]

The legend range, if this legend is continuous. This value is null if the legend is discrete.

Implementation
    public function get range():LegendRange
scaleproperty 
scale:Scale  [read-write]

Scale instance used to define the legend mapping.

Implementation
    public function get scale():Scale
    public function set scale(value:Scale):void
shapePaletteproperty 
shapePalette:ShapePalette  [read-write]

The shape palette used to encode values (may be null).

Implementation
    public function get shapePalette():ShapePalette
    public function set shapePalette(value:ShapePalette):void
sizePaletteproperty 
sizePalette:SizePalette  [read-write]

The size palette used to encode values (may be null).

Implementation
    public function get sizePalette():SizePalette
    public function set sizePalette(value:SizePalette):void
spacingproperty 
spacing:Number  [read-write]

Spacing between legend items.

Implementation
    public function get spacing():Number
    public function set spacing(value:Number):void
titleproperty 
title:TextSprite  [read-only]

TextSprite containing the legend title.

Implementation
    public function get title():TextSprite
Constructor detail
Legend()constructor
public function Legend(title:String, scale:Scale = null, colors:ColorPalette = null, shapes:ShapePalette = null, sizes:SizePalette = null)

Creates a new Legend for the given data field.

Parameters
title:String — the data field to describe with the legend
 
scale:Scale (default = null) — the visualization corresponding to this legend
 
colors:ColorPalette (default = null) — the scale value used to map the data field to visual variables
 
shapes:ShapePalette (default = null)
 
sizes:SizePalette (default = null)
Method detail
buildFromScale()method
public function buildFromScale():void

Builds the contents of this legend from the current scale values. This method will remove all items from the legend and rebuild the legend using the current scale and palette settings.

buildFromValues()method 
public function buildFromValues(values:Array):void

Populates the contents of this legend from a list of value objects. This method will create a legend with discrete entries determined by the contents of the input values array. This should be an array of objects containing the following properties:

When this method is called, any previous values in the legend will be removed.

Parameters
values:Array — an array of value to include in the legend.
fromScale()method 
public static function fromScale(title:String, scale:Scale, palette:Palette, ... args):Legend

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.

Parameters
title:String — the title text for the legend
 
scale:Scale — the scale instance determining the legend values
 
palette:Palette — a color, shape, or size palette for legend items
 
... args — one or more additional palettes

Returns
Legend — the generated Legend, or null if a legend could not be built
fromValues()method 
public static function fromValues(title:String, values:Array):Legend

Generates a legend from an array of legend item values. This method simply instantiates a new Legend instance with the given title and then invokes the buildFromValues method with the given value array.

Parameters
title:String — the legend title text, or null for no title.
 
values:Array — an array of values for the legend items. See the documentation for the buildFromValues method for more.

Returns
Legend — the generated legend
layout()method 
public function layout(t:Transitioner = null):void

Performs layout, setting the position for all items in the legend.

Parameters
t:Transitioner (default = null) — a transitioner for value updates
setItemProperties()method 
public function setItemProperties(vals:Object, t:* = null):Transitioner

Sets property values on all legend items. The values within the vals argument can take a number of forms:

Parameters
vals:Object — an object containing the properties and values to set.
 
t:* (default = null) — 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.

Returns
Transitioner — the transitioner used to update the values
update()method 
public function update(t:Transitioner = null):Transitioner

Update the legend, recomputing layout of items.

Parameters
t:Transitioner (default = null) — a transitioner for value updates

Returns
Transitioner — the input transitioner