Packagecom.flextoolbox.controls
Classpublic class TreeMap
InheritanceTreeMap Inheritance mx.core.UIComponent

A treemap is a space-constrained visualization of hierarchical structures. It is very effective in showing attributes of leaf nodes using size and color coding.

View the examples.

See also

http://code.google.com/p/flex2treemap/
http://en.wikipedia.org/wiki/Treemapping
http://www.cs.umd.edu/hcil/treemap-history/

Public Properties
 PropertyDefined by
  branchesSelectable : Boolean
Indicates if the node's within the TreeMap can be selected by the user.
TreeMap
  branchRenderer : IFactory
The custom branch renderer for the control.
TreeMap
  colorField : String
The name of the field in the data provider items to use as the color.
TreeMap
  colorFunction : Function
A user-supplied function to run on each item to determine its color.
TreeMap
  dataDescriptor : ITreeDataDescriptor
Returns the current ITreeDataDescriptor.
TreeMap
  dataProvider : Object
An object that contains the data to be displayed.
TreeMap
  dataTipField : String
The name of the field in the data provider items to display as the datatip of the data renderer.
TreeMap
  dataTipFunction : Function
A user-supplied function to run on each item to determine its datatip.
TreeMap
  hasRoot : Boolean
[read-only] Indicates that the current dataProvider has a root item; for example, a single top node in a hierarchical structure.
TreeMap
  labelField : String
The name of the field in the data provider items to display as the label of the data renderer.
TreeMap
  labelFunction : Function
A user-supplied function to run on each item to determine its label.
TreeMap
  layoutStrategy : ITreeMapLayoutStrategy
The custom layout algorithm for the control.
TreeMap
  leafRenderer : IFactory
The custom leaf renderer for the control.
TreeMap
  maxDepth : int
If value is >= 0, the treemap will only render branches to a specific depth.
TreeMap
  selectable : Boolean
Indicates if the node's within the TreeMap can be selected by the user.
TreeMap
  selectedItem : Object
The currently selected item.
TreeMap
  showRoot : Boolean
Sets the visibility of the root item.
TreeMap
  weightField : String
The name of the field in the data provider items to use in weight calculations.
TreeMap
  weightFunction : Function
A user-supplied function to run on each item to determine its weight.
TreeMap
  zoomedBranch : Object
The currently zoomed branch.
TreeMap
  zoomEnabled : Boolean
If true, branches may be zoomed in (maximized) to display in the full bounds of the treemap.
TreeMap
  zoomOutType : String
Determines the way that zoom out actions work.
TreeMap
Public Methods
 MethodDefined by
  
TreeMap()
Constructor.
TreeMap
  
itemIsRoot(item:Object):Boolean
Determines if an item is the root node
TreeMap
  
itemToColor(item:Object):uint
Determines the color value for an item from the data provider.
TreeMap
  
itemToDataTip(item:Object):String
Determines the datatip text for an item from the data provider.
TreeMap
  
itemToItemRenderer(item:Object):ITreeMapItemRenderer
Returns the item renderer that displays specific data.
TreeMap
  
itemToLabel(item:Object):String
Determines the label text for an item from the data provider.
TreeMap
  
itemToWeight(item:Object):Number
Determines the weight value for an item from the data provider.
TreeMap
Protected Methods
 MethodDefined by
  
branchLayoutChangeHandler(event:TreeMapLayoutEvent):void
TreeMap
  
itemToUID(item:Object):String
Determines the UID for a data provider item.
TreeMap
Events
 EventSummaryDefined by
  
change
Dispatched when the selectedIndex or selectedItem property changes as a result of user interaction.TreeMap
  
leafClick
Dispatched when the user clicks on a leaf item in the control.TreeMap
  
leafDoubleClick
Dispatched when the user double-clicks on a leaf item in the control.TreeMap
  
leafRollOut
Dispatched when the user rolls the mouse pointer out of a leaf item in the control.TreeMap
  
leafRollOver
Dispatched when the user rolls the mouse pointer over a leaf item in the control.TreeMap
Styles
 StyleDescriptionDefined by
  
branchStyleName
Type: String   CSS Inheritance: no
Sets the style name for all branch nodes. 		TreeMap
  
color
Type: uint   Format: Color   CSS Inheritance: yes
Color of text in the component, including the component label. The default value is 0x0B333C.		TreeMap
  
disabledColor
Type: uint   Format: Color   CSS Inheritance: yes
Color of text in the component if it is disabled. The default value is 0xAAB3B3.		TreeMap
  
fontAntiAliasType
Type: String   CSS Inheritance: yes
Sets the antiAliasType property of internal TextFields. The possible values are "normal" (flash.text.AntiAliasType.NORMAL) and "advanced" (flash.text.AntiAliasType.ADVANCED).

The default value is "advanced", which enables the FlashType renderer if you are using an embedded FlashType font. Set to "normal" to disable the FlashType renderer.

This style has no effect for system fonts.

This style applies to all the text in a TextField subcontrol; you can't apply it to some characters and not others.

The default value is "advanced".		TreeMap
  
fontFamily
Type: String   CSS Inheritance: yes
Name of the font to use. Unlike in a full CSS implementation, comma-separated lists are not supported. You can use any font family name. If you specify a generic font name, it is converted to an appropriate device font. The default value is "Verdana".		TreeMap
  
fontGridFitType
Type: String   CSS Inheritance: yes
Sets the gridFitType property of internal TextFields that represent text in Flex controls. The possible values are "none" (flash.text.GridFitType.NONE), "pixel" (flash.text.GridFitType.PIXEL), and "subpixel" (flash.text.GridFitType.SUBPIXEL).

This property only applies when you are using an embedded FlashType font and the fontAntiAliasType property is set to "advanced".

This style has no effect for system fonts.

This style applies to all the text in a TextField subcontrol; you can't apply it to some characters and not others.

The default value is "pixel".		TreeMap
  
fontSharpness
Type: Number   CSS Inheritance: yes
Sets the sharpness property of internal TextFields that represent text in Flex controls. This property specifies the sharpness of the glyph edges. The possible values are Numbers from -400 through 400.

This property only applies when you are using an embedded FlashType font and the fontAntiAliasType property is set to "advanced".

This style has no effect for system fonts.

This style applies to all the text in a TextField subcontrol; you can't apply it to some characters and not others.

The default value is 0.		TreeMap
  
fontSize
Type: Number   Format: Length   CSS Inheritance: yes
Height of the text, in pixels. The default value is 10 for all controls except the ColorPicker control. For the ColorPicker control, the default value is 11. 		TreeMap
  
fontStyle
Type: String   CSS Inheritance: yes
Determines whether the text is italic font. Recognized values are "normal" and "italic". The default value is "normal".		TreeMap
  
fontThickness
Type: Number   CSS Inheritance: yes
Sets the thickness property of internal TextFields that represent text in Flex controls. This property specifies the thickness of the glyph edges. The possible values are Numbers from -200 to 200.

This property only applies when you are using an embedded FlashType font and the fontAntiAliasType property is set to "advanced".

This style has no effect on system fonts.

This style applies to all the text in a TextField subcontrol; you can't apply it to some characters and not others.

The default value is 0.		TreeMap
  
fontWeight
Type: String   CSS Inheritance: yes
Determines whether the text is boldface. Recognized values are normal and bold. The default value for Button controls is bold. The default value for all other controls is normal. 		TreeMap
  
itemDefaultColor
Type: uint   CSS Inheritance: no
The default "color" value of an item in the treemap. Used if no color provided or the data is invalid; 		TreeMap
  
kerning
Type: Boolean   CSS Inheritance: yes
A Boolean value that indicates whether kerning is enabled (true) or disabled (false). Kerning adjusts the gap between certain character pairs to improve readability, and should be used only when necessary, such as with headings in large fonts. Kerning is supported for embedded FlashType fonts only. Certain fonts, such as Verdana, and monospaced fonts, such as Courier New, do not support kerning. The default value is false.		TreeMap
  
leafStyleName
Type: String   CSS Inheritance: no
Sets the style name for all leaf nodes. 		TreeMap
  
letterSpacing
Type: Number   CSS Inheritance: yes
The number of additional pixels to appear between each character. A positive value increases the character spacing beyond the normal spacing, while a negative value decreases it. The default value is 0.		TreeMap
  
textAlign
Type: String   CSS Inheritance: yes
Alignment of text within a container. Possible values are "left", "right", or "center".

The default value for most components is "left". For the FormItem component, the default value is "right". For the Button, LinkButton, and AccordionHeader components, the default value is "center", and this property is only recognized when the labelPlacement property is set to "left" or "right". If labelPlacement is set to "top" or "bottom", the text and any icon are centered.

TreeMap
  
textDecoration
Type: String   CSS Inheritance: yes
Determines whether the text is underlined. Possible values are "none" and "underline". The default value is "none".		TreeMap
  
textIndent
Type: Number   Format: Length   CSS Inheritance: yes
Offset of first line of text from the left side of the container, in pixels. The default value is 0.		TreeMap
Property detail
branchesSelectableproperty
branchesSelectable:Boolean  [read-write]

Indicates if the node's within the TreeMap can be selected by the user.

This property can be used as the source for data binding.

Implementation
    public function get branchesSelectable():Boolean
    public function set branchesSelectable(value:Boolean):void
branchRendererproperty 
branchRenderer:IFactory  [read-write]

The custom branch renderer for the control. You can specify a drop-in, inline, or custom branch renderer. Unlike the renderers used by Tree components, nodes and branches in a TreeMap are quite different visually and functionally. As a result, it's easier to specify and customize seperate renderers for either type.

The default branch renderer is TreeMapBranchRenderer.

This property can be used as the source for data binding.

Implementation
    public function get branchRenderer():IFactory
    public function set branchRenderer(value:IFactory):void
colorFieldproperty 
colorField:String  [read-write]

The name of the field in the data provider items to use as the color.

This property can be used as the source for data binding.

Implementation
    public function get colorField():String
    public function set colorField(value:String):void
colorFunctionproperty 
colorFunction:Function  [read-write]

A user-supplied function to run on each item to determine its color.

The color function takes one argument, the item in the data provider. It returns a uint.

colorFunction(item:Object):uint

This property can be used as the source for data binding.

Implementation
    public function get colorFunction():Function
    public function set colorFunction(value:Function):void
dataDescriptorproperty 
dataDescriptor:ITreeDataDescriptor  [read-write]

Returns the current ITreeDataDescriptor.

The default value is DefaultDataDescriptor.

This property can be used as the source for data binding.

Implementation
    public function get dataDescriptor():ITreeDataDescriptor
    public function set dataDescriptor(value:ITreeDataDescriptor):void
dataProviderproperty 
dataProvider:Object  [read-write]

An object that contains the data to be displayed. When you assign a value to this property, the TreeMap class handles the source data object as follows:

The default value is an empty ArrayCollection.

Implementation
    public function get dataProvider():Object
    public function set dataProvider(value:Object):void
dataTipFieldproperty 
dataTipField:String  [read-write]

The name of the field in the data provider items to display as the datatip of the data renderer.

This property can be used as the source for data binding.

Implementation
    public function get dataTipField():String
    public function set dataTipField(value:String):void
dataTipFunctionproperty 
dataTipFunction:Function  [read-write]

A user-supplied function to run on each item to determine its datatip.

The datatip function takes one argument, the item in the data provider. It returns a String.

dataTipFunction(item:Object):String

This property can be used as the source for data binding.

Implementation
    public function get dataTipFunction():Function
    public function set dataTipFunction(value:Function):void
hasRootproperty 
hasRoot:Boolean  [read-only]

Indicates that the current dataProvider has a root item; for example, a single top node in a hierarchical structure. XML and Object are examples of types that have a root. Lists and arrays do not.

Implementation
    public function get hasRoot():Boolean

See also

showRoot
labelFieldproperty 
labelField:String  [read-write]

The name of the field in the data provider items to display as the label of the data renderer. As a special case, if the nodes are TreeMap components, this function applies to the TreeMap label.

This property can be used as the source for data binding.

Implementation
    public function get labelField():String
    public function set labelField(value:String):void
labelFunctionproperty 
labelFunction:Function  [read-write]

A user-supplied function to run on each item to determine its label.

The label function takes one argument, the item in the data provider. It returns a String.

labelFunction(item:Object):String

This property can be used as the source for data binding.

Implementation
    public function get labelFunction():Function
    public function set labelFunction(value:Function):void
layoutStrategyproperty 
layoutStrategy:ITreeMapLayoutStrategy  [read-write]

The custom layout algorithm for the control.

The default alogrithm is Squarify.

This property can be used as the source for data binding.

Implementation
    public function get layoutStrategy():ITreeMapLayoutStrategy
    public function set layoutStrategy(value:ITreeMapLayoutStrategy):void
leafRendererproperty 
leafRenderer:IFactory  [read-write]

The custom leaf renderer for the control. You can specify a drop-in, inline, or custom leaf renderer.

The default node renderer is TODO.

This property can be used as the source for data binding.

Implementation
    public function get leafRenderer():IFactory
    public function set leafRenderer(value:IFactory):void
maxDepthproperty 
maxDepth:int  [read-write]

If value is >= 0, the treemap will only render branches to a specific depth.

This property can be used as the source for data binding.

Implementation
    public function get maxDepth():int
    public function set maxDepth(value:int):void
selectableproperty 
selectable:Boolean  [read-write]

Indicates if the node's within the TreeMap can be selected by the user.

This property can be used as the source for data binding.

Implementation
    public function get selectable():Boolean
    public function set selectable(value:Boolean):void
selectedItemproperty 
selectedItem:Object  [read-write]

The currently selected item.

This property can be used as the source for data binding.

Implementation
    public function get selectedItem():Object
    public function set selectedItem(value:Object):void
showRootproperty 
showRoot:Boolean  [read-write]

Sets the visibility of the root item. If the dataProvider data has a root node, and this is set to false, the TreeMap control does not display the root item. Only the decendants of the root item are displayed. This flag has no effect on non-rooted dataProviders, such as List and Array.

The default value is true.

This property can be used as the source for data binding.

Implementation
    public function get showRoot():Boolean
    public function set showRoot(value:Boolean):void

See also

hasRoot
weightFieldproperty 
weightField:String  [read-write]

The name of the field in the data provider items to use in weight calculations.

This property can be used as the source for data binding.

Implementation
    public function get weightField():String
    public function set weightField(value:String):void
weightFunctionproperty 
weightFunction:Function  [read-write]

A user-supplied function to run on each item to determine its weight.

The weight function takes one arguments, the item in the data provider. It returns a Number.

weightFunction(item:Object):Number

This property can be used as the source for data binding.

Implementation
    public function get weightFunction():Function
    public function set weightFunction(value:Function):void
zoomedBranchproperty 
zoomedBranch:Object  [read-write]

The currently zoomed branch.

This property can be used as the source for data binding.

Implementation
    public function get zoomedBranch():Object
    public function set zoomedBranch(value:Object):void
zoomEnabledproperty 
zoomEnabled:Boolean  [read-write]

If true, branches may be zoomed in (maximized) to display in the full bounds of the treemap.

This property can be used as the source for data binding.

Implementation
    public function get zoomEnabled():Boolean
    public function set zoomEnabled(value:Boolean):void
zoomOutTypeproperty 
zoomOutType:String  [read-write]

Determines the way that zoom out actions work. Values are defined by the constants in the TreeMapZoomOutType class.

This property can be used as the source for data binding.

Implementation
    public function get zoomOutType():String
    public function set zoomOutType(value:String):void
Constructor detail
TreeMap()constructor
public function TreeMap()

Constructor.

Method detail
branchLayoutChangeHandler()method
protected function branchLayoutChangeHandler(event:TreeMapLayoutEvent):voidParameters
event:TreeMapLayoutEvent
itemIsRoot()method 
public function itemIsRoot(item:Object):Boolean

Determines if an item is the root node

Parameters
item:Object — the data for which to check against the root

Returns
Boolean — true if the item is the root data, false if not
itemToColor()method 
public function itemToColor(item:Object):uint

Determines the color value for an item from the data provider. If color not available, returns black (0x000000).

Parameters
item:Object

Returns
uint
itemToDataTip()method 
public function itemToDataTip(item:Object):String

Determines the datatip text for an item from the data provider. If no datatip is specified, returns an empty string.

Parameters
item:Object

Returns
String
itemToItemRenderer()method 
public function itemToItemRenderer(item:Object):ITreeMapItemRenderer

Returns the item renderer that displays specific data.

Parameters
item:Object — the data for which to find a matching item renderer

Returns
ITreeMapItemRenderer — the item renderer that matches the data
itemToLabel()method 
public function itemToLabel(item:Object):String

Determines the label text for an item from the data provider. If no label is specfied, returns the result of the item's toString() method. If item is null, returns an empty string.

Parameters
item:Object

Returns
String
itemToUID()method 
protected function itemToUID(item:Object):String

Determines the UID for a data provider item. All items in a data provider must either have a unique ID (UID) or one will be generated and associated with it. This means that you cannot have an object or scalar value appear twice in a data provider. For example, the following data provider is not supported because the value "foo" appears twice and the UID for a string is the string itself

var sampleDP:Array = ["foo", "bar", "foo"]
Simple dynamic objects can appear twice if they are two separate instances. The following is supported because each of the instances will be given a different UID because they are different objects.
var sampleDP:Array = [{label: "foo"}, {label: "foo"}]
Note that the following is not supported because the same instance appears twice.
var foo:Object = {label: "foo"}; sampleDP:Array = [foo, foo];

Parameters
item:Object — The data provider item

Returns
String — The UID as a string
itemToWeight()method 
public function itemToWeight(item:Object):Number

Determines the weight value for an item from the data provider.

Parameters
item:Object

Returns
Number
Event detail
changeevent 
Event object type: flash.events.Event

Dispatched when the selectedIndex or selectedItem property changes as a result of user interaction.

leafClickevent  
Event object type: com.flextoolbox.events.TreeMapEvent

Dispatched when the user clicks on a leaf item in the control.

leafDoubleClickevent  
Event object type: com.flextoolbox.events.TreeMapEvent

Dispatched when the user double-clicks on a leaf item in the control.

leafRollOutevent  
Event object type: com.flextoolbox.events.TreeMapEvent

Dispatched when the user rolls the mouse pointer out of a leaf item in the control.

leafRollOverevent  
Event object type: com.flextoolbox.events.TreeMapEvent

Dispatched when the user rolls the mouse pointer over a leaf item in the control.

Examples
TreeMapExample
<?xml version="1.0" encoding="utf-8"?>
<!-- TreeMap control example. -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    xmlns:toolbox="http://www.flextoolbox.com/2006/mxml">

    <mx:Script>
        <![CDATA[

            [Bindable]
            public var selectedNode:XML;

            // Event handler for the TreeMap control change event.
            public function treeChanged(event:Event):void
            {
                selectedNode=TreeMap(event.target).selectedItem as XML;
            }
        ]]>
    </mx:Script>

    <mx:XMLList id="treeData">
        <node label="Mail Box">
            <node label="Inbox">
                <node label="Marketing"/>
                <node label="Product Management"/>
                <node label="Personal"/>
            </node>
            <node label="Outbox">
                <node label="Professional"/>
                <node label="Personal"/>
            </node>
            <node label="Spam"/>
            <node label="Sent"/>
        </node>    
    </mx:XMLList>

    <mx:Panel title="TreeMap Control Example" height="75%" width="75%" 
        paddingTop="10" paddingLeft="10" paddingRight="10" paddingBottom="10">

        <mx:Label width="100%" color="blue" 
            text="Select a node in the TreeMap control."/>

        <mx:HDividedBox width="100%" height="100%">
            <toolbox:TreeMap id="myTreeMap" width="50%" height="100%" labelField="@label"
                dataProvider="{treeData}" selectable="true" branchesSelectable="true"
                change="treeChanged(event)"/>
            <mx:TextArea height="100%" width="50%"
                text="Selected Item: {selectedNode.@label}"/>
        </mx:HDividedBox>

    </mx:Panel>
</mx:Application>



Access flextreemap on Google Groups for feedback and support
Copyright 2008 Josh Tynjala. All rights reserved.