ASDoc

mx.controls
Class Tree

class Tree
extends mx.controls.List

The Tree control lets a user view hierarchical data arranged as an expandable tree. Each item in a tree is called a node and can be either a leaf or a branch. A leaf node is an end point in the tree. A branch node can contain either leaf or branch nodes.

By default, a leaf is represented by a text label next to a file icon. A branch is represented by a text label next to a folder icon, with a disclosure triangle that a user can open to expose children.

Nodes of the tree are represented by the TreeDataProvider control. For each node in the tree, the TreeDataProvider control can define the following properties:

data - The data to associate with a node, if any.
label - The text to be displayed in the Tree for a node.
isBranch - If true, the node is a branch: if false, it is not a branch. If not specified, the Tree control determines if the node is a branch based on whether it contains any child nodes.

MXML Syntax

The <mx:Tree> tag inherits all the properties of its parent classes, and the following properties:

 <mx:Tree
   alternatingRowColors="No default."
   dataProvider="No default."
   defaultLeafIcon="No default."
   depthColors="No default."
   firstVisibleNode="No default."
   folderOpenIcon="No default."
   folderCloseIcon="No default."
   indentation="8"
   openDuration="250"
   openEasing="No default."
   rollOverColor="0xE3FFD6"
   selectedNode="No default."
   selectionColor=#0xCDFFC1"
   cellEdit="Event handler; no default."
   cellFocusIn="Event handler; no default."
   cellFocusOut="Event handler; no default."
   cellPress="Event handler; no default."
   change="Event handler; no default."
   nodeClose="Event handler; no default."
   nodeOpen="Event handler; no default."
 />

Methods
	`addTreeNode(label, data) : Void` Adds a node to the tree.
	`addTreeNodeAt(index, label, data) : Void` Adds a child node at the specified index on the tree node.
	`calculateWidths(count) : Void` Returns the optimal width of the control based on its content.
	`disposeEditor() : Void` Returns cell to normal state after editing.
	`editField(index:Number, colName:String, data) : Void` Edits a specified field in the tree.
	`getDisplayIndex(node) : Void` Returns the index of the specified node based on the nodes currently visible in the tree.
	`getIsBranch(node) : Void` Returns true if the specified node is a branch node.
	`getIsOpen(node) : Void` Returns true if the specified node branch is open.
	`getNodeDisplayedAt(index) : Void` Returns the node at the specified index.
	`getTreeNodeAt(index) : Void` Returns the node at the specified index.
	`refresh() : Void` Refreshes the tree display.
	`removeAll() : Void` Removes all nodes from the tree.
	`removeTreeNodeAt(index) : Void` Removes the specified node from the tree.
	`setIcon(node, iconID, iconID2) : Void` Sets the associated icon for the node.
	`setIsBranch(node, branch) : Void` Specifies if the node is a branch node.
	`setIsOpen(node, open, animate, fireEvent) : Void` Opens a branch node.

Methods inherited from class mx.controls.listclasses.ScrollSelectList

calculateWidths 
        setPropertiesAt

Methods inherited from class mx.core.ScrollView

setScrollProperties 
        getViewMetrics 
        createChild

Methods inherited from class mx.core.View

init 
        draw 
        createChild 
        getChildAt 
        getChildIndex 
        setChildIndex 
        destroyAllChildren 
        destroyChild 
        destroyChildAt 
        getViewMetrics

Methods inherited from class mx.core.UIComponent

getFocus 
        setFocus 
        getFocusManager

Properties
`static`	`version:String` ComponentVersion is for internal use only.
	`dataProvider:Object` Array of simple types or objects.
	`firstVisibleNode:XMLNode [Read-Only]` First node at the top of the Tree control.
	`selectedNode:XMLNode [Read-Only]` Selected node in the tree.
	`selectedNodes:Array [Read-Only]` Selected nodes.
	`focusedCell:Object [Read/Write]` Cell currently in focus.

Properties inherited from class mx.controls.List

version 
		dataProvider

Properties inherited from class mx.core.ScrollView

version 
		className 
		hScrollPolicy 
		vScrollPolicy 
		hPosition 
		vPosition 
		maxVPosition 
		maxHPosition

Properties inherited from class mx.core.View

version 
		className 
		numChildren

Properties inherited from class mx.core.UIComponent

version 
		enabled 
		tabIndex

Effects

Effects inherited from class mx.core.UIComponent

showEffect 
		hideEffect 
		focusInEffect 
		focusOutEffect

Effects inherited from class mx.core.UIObject

creationCompleteEffect 
		moveEffect 
		resizeEffect 
		mouseDownEffect 
		mouseOverEffect 
		mouseOutEffect 
		mouseUpEffect

Events
`change`	Broadcast when the user selects a tree item. Target contains a reference to the component that triggered the event. Type contains the name of the event.
`nodeOpen`	Handler for branch nodeOpen events. The target property of the event object contains the Tree object that changed. Type contains the name of the event. The event object also contains a node property which contains an object representing the node that opened. Access the label and data properties for the node as: eventobj.node.attributes.label eventobj.node.attributes.data
`nodeClose`	Handler for branch nodeClose events. The target property of the event object contains the Tree object that changed. The event object also contains a node property which contains an object representing the node that closed. Access the label and data properties for the node as: eventobj.node.attributes.label eventobj.node.attributes.data
`cellPress`	Broadcast when a user selects a label with the mouse pointer. The event object contains the following properties: - itemIndex Index of the item. - columnIndex Index of the column. Target contains a reference to the component that triggered the event. Type contains the name of the event.
`cellEdit`	Broadcast when a tree label value changes. The event object contains the following properties: - itemIndex Index of the item. - columnIndex Index of the column. - oldValue Previous value. Target contains a reference to the component that triggered the event. Type contains the name of the event.
`cellFocusIn`	Broadcast when the user selects a label hit area or tabs to it and the label receives focus. The event object contains the following properties: - itemIndex Index of the item. - columnIndex Index of the column. Target contains a reference to the component that triggered the event. Type contains the name of the event.
`cellFocusOut`	Broadcast when a label loses focus. The event object contains the following properties: - itemIndex Index of the item. - columnIndex Index of the column. Target contains a reference to the component that triggered the event. Type contains the name of the event.
`nodeOpen`	Handler for branch nodeOpen events. The target property of the event object contains the Tree object that changed. The event object also contains a node property which contains an object representing the node that opened. Access the label and data properties for the node as: eventobj.node.attributes.label eventobj.node.attributes.data Type contains the name of the event.
`nodeClose`	Handler for branch nodeClose events. The target property of the event object contains the Tree object that changed. The event object also contains a node property which contains an object representing the node that closed. Access the label and data properties for the node as: eventobj.node.attributes.label eventobj.node.attributes.data Type contains the name of the event.

Events inherited from class: mx.controls.listclasses.ScrollSelectList

change 
		itemRollOver 
		itemRollOut

Events inherited from class: mx.core.ScrollView

scroll

Events inherited from class: mx.core.View

childCreated 
		childIndexChanged 
		childDestroyed

Events inherited from class: mx.core.UIComponent

focusIn 
		focusOut 
		keyDown 
		keyUp 
		show 
		hide 
		valid 
		invalid 
		valueCommitted

Styles
`alternatingRowColors`	`Type: Array CSS Inheritance: yes` Colors for rows in an alternating pattern. Value can be an Array of two of more colors.
`depthColors`	`Type: Array CSS Inheritance: yes` Array of colors used in the Tree control, in descending order.
`indentation`	`Type: Number CSS Inheritance: no` Indentation for each tree level, in pixels. The default value is 8.
`openDuration`	`Type: Number Format: Time CSS Inheritance: no` Length of an open or close transition, in milliseconds. The default value is 250.
`openEasing`	`Type: String Format: Time CSS Inheritance: no` Easing function to control component tweening.
`rollOverColor`	`Type: Number Format: Color CSS Inheritance: yes` Color of the background when the user rolls over the link. The default value is #0xE3FFD6.
`selectionColor`	`Type: Number Format: Color CSS Inheritance: yes` Color of the background when the user selects the link. The default value is #0xCDFFC1.

Styles inherited from class mx.controls.List

alternatingRowColors 
		rollOverColor 
		selectionColor 
		selectionEasing 
		textDisabledColor 
		textRollOverColor 
		textSelectedColor

Styles inherited from class mx.core.UIObject

color 
		fontFamily 
		fontSize 
		fontStyle 
		fontWeight 
		textAlign 
		textDecoration 
		textIndent 
		marginLeft 
		marginRight 
		horizontalGap 
		verticalGap

Method Detail

addTreeNode

addTreeNode(label, data) : 
		Void

Adds a node to the tree.

Parameters
label - Text for the node.
data - Data for the node.

Returns
The new node.

addTreeNodeAt

addTreeNodeAt(index, label, data) : 
		Void

Adds a child node at the specified index on the tree node.

Parameters
     index - Position (in the tree`s root node`s children) for the node.
     label - Text for the node.
     data - Data for the node.

Returns
The new node.

calculateWidths

calculateWidths(count) : 
		Void

Returns the optimal width of the control based on its content. You can calculate this width for all the contents of the control, or for a subset of items. The signature of this method is

calculateWidth([start, length])

start - First index of data at which to start measuring. This parameter is optional.
length - Number of items to measure. This parameter is optional.

Parameters
count - Number of nodes to measure.

disposeEditor

disposeEditor() : Void

Returns cell to normal state after editing.

editField

editField(index:Number, colName:String, data) : Void

Edits a specified field in the tree.

Parameters
     index - Index of the item to edit.
     colName - Name of the field to edit.
     data - New data to put in the edited field.

getDisplayIndex

getDisplayIndex(node) : 
		Void

Returns the index of the specified node based on the nodes currently visible in the tree.

Parameters
node - Node to query.

Returns
Index on the tree's display list.

getIsBranch

getIsBranch(node) : 
		Void

Returns true if the specified node is a branch node.

Parameters
node - Node to inspect.

Returns
True if a branch, false if not.

getIsOpen

getIsOpen(node) : 
		Void

Returns true if the specified node branch is open.

Parameters
node - Node to inspect.

Returns
True if open, false if not.

getNodeDisplayedAt

getNodeDisplayedAt(index) : 
		Void

Returns the node at the specified index.

Parameters
index - Position of the node in the tree`s list of displayed nodes.

Returns
Node.

getTreeNodeAt

getTreeNodeAt(index) : 
		Void

Returns the node at the specified index.

Parameters
index - Position of the node in the tree`s DataProvider`s children.

Returns
Node.

refresh

refresh() : 
		Void

Refreshes the tree display. This is commonly used when you update the tree nodes at runtime using a data provider.

removeAll

removeAll() : 
		Void

Removes all nodes from the tree.

removeTreeNodeAt

removeTreeNodeAt(index) : 
		Void

Removes the specified node from the tree.

Parameters
index - Position of the node in the tree`s root.

Returns
The node.

setIcon

setIcon(node, iconID, iconID2) : 
		Void

Sets the associated icon for the node.

Parameters
     node - Node to affect.
     iconID - Linkage ID for the closed (or leaf) icon.
     iconID2 - Linkage ID for the open (or leaf) icon.

setIsBranch

setIsBranch(node, branch) : 
		Void

Specifies if the node is a branch node. Nodes are automatically configured as branch nodes when they have children. You only need to call this when you create an empty branch node.

Parameters
node - Node to affect.
branch - True if it is a branch, false if not.

setIsOpen

setIsOpen(node, open, animate, fireEvent) : 
		Void

Opens a branch node.

Parameters
     node - Node to affect.
     open - True to open, false to close.
     animate - True to animate the transition, false to not.
     fireEvent - Controls whether the tree fires an open event after the open animation is complete.

Property Detail

dataProvider

dataProvider:Object

Array of simple types or objects.

firstVisibleNode

firstVisibleNode:XMLNode  
    	[Read-Only]

First node at the top of the Tree control. Setting this property is analogous to setting the vPosition of the List control. The default is the first node in the Tree control. If the node isn`t currently viewable, for example, because it is under a nonexpanded node, setting this property has no effect.

focusedCell

focusedCell:Object  
    	[Read/Write]

Cell currently in focus.

selectedNode

selectedNode:XMLNode  
    	[Read-Only]

Selected node in the tree. You can specify a single node, or an array of nodes.

selectedNodes

selectedNodes:Array  
    	[Read-Only]

Selected nodes.

version

static version:String

ComponentVersion is for internal use only.

mx.controls Class Tree