/*
Copyright (c) 2009 Yahoo! Inc. All rights reserved.
The copyrights embodied in the content of this file are licensed under the BSD (revised) open source license
*/
package com.yahoo.astra.fl.controls {
import com.yahoo.astra.fl.controls.treeClasses.*;
import com.yahoo.astra.fl.events.TreeEvent;
import fl.controls.List;
import fl.controls.listClasses.*;
import fl.core.InvalidationType;
import fl.data.DataProvider;
import fl.events.*;
import flash.display.*;
import flash.events.KeyboardEvent;
import flash.ui.Keyboard;
//--------------------------------------
// Class description
//--------------------------------------
/**
* The Tree class creates a List-based Tree component that displays hierarchical information.
* The Tree rendering is achieved via a custom TreeDataProvider that receives and parses an XML data structure,
* the TreeNode data structure, and a supplied TreeCellRenderer (though other CellRenderers can be used in lieu
* of the default one.)
*
* @author Allen Rabinovich
* @see com.yahoo.astra.fl.controls.treeClasses.TreeDataProvider
* @see com.yahoo.astra.fl.controls.treeClasses.TreeCellRenderer
* @see com.yahoo.astra.fl.controls.treeClasses.TNode
* @see com.yahoo.astra.fl.controls.treeClasses.BranchNode
* @see com.yahoo.astra.fl.controls.treeClasses.LeafNode
*/
public class Tree extends List {
/**
* The name of the field in the data object that contains information about an icon to use for a leaf node
*/
public var leafIconField:String = "leafIcon";
/**
* The name of the field in the data object that contains information about an icon to use for an open branch node
*/
public var openBranchIconField:String = "openBranchIcon";
/**
* The name of the field in the data object that contains information about an icon to use for a closed branch node
*/
public var closedBranchIconField:String = "closedBranchIcon";
//--------------------------------------------------------------------------
//
// Class methods
//
//--------------------------------------------------------------------------
/**
* Creates and returns an instance of the Tree class. The Tree control's content
* is determined by assigning a TreeDataProvider to the dataProvider field of
* the Tree class.
*
* To display the Tree, add it as a child to your current display list or drag an instance
* of the Tree onto Stage.
*
* @return An instance of the Tree class.
*
* @see com.yahoo.astra.fl.controls.treeClasses.TreeDataProvider
*/
public function Tree() {
super();
// The default processor of item click events is nodeClick function
addEventListener(ListEvent.ITEM_CLICK, nodeClick);
addEventListener(ListEvent.ITEM_DOUBLE_CLICK, nodeClick);
setStyle('cellRenderer', TreeCellRenderer);
}
/**
* Opens all nodes at all levels in the Tree.
*
*/
public function openAllNodes () : void {
var visibleNodes:Array = dataProvider.toArray();
for each (var node:TNode in visibleNodes) {
if (!(node is LeafNode) && (node.nodeLevel == 0)) {
node.openAllChildren();
}
}
}
/**
* Closes all nodes at all levels in the Tree.
*
*/
public function closeAllNodes () : void {
var visibleNodes:Array = dataProvider.toArray();
for each (var node:TNode in visibleNodes) {
if (!(node is LeafNode) && (node.nodeLevel == 0)) {
node.closeAllChildren();
}
}
}
/**
* Finds the first instance of the node in the tree where
* the value in the field designated by fieldName
* is equal to fieldValue
*
* @param fieldName The name of the field in the node object to check.
* @param fieldValue The value to look for in the specified field.
*
* @return A node that contains the given value in the specified field; or null if
* no such node is found.
*
*/
public function findNode (fieldName:String, fieldValue:String) : TNode {
var visibleNodes:Array = dataProvider.toArray();
for each (var node:TNode in visibleNodes) {
if (node.nodeLevel == 0) {
var foundNode:TNode = node.checkForValue(fieldName, fieldValue);
if (foundNode != null) {
return foundNode;
}
}
}
return null;
}
/**
* Opens all parent nodes of a specified node, so that the specified
* node becomes visible.
*
* @param foundNode The node to be made visible.
*
* @return The index of the node in the current view of the Tree (this is the
* absolute index: i.e., the number of the nodes visible above the specified node.)
*
*/
public function showNode (foundNode:TNode) : int {
if (foundNode != null) {
var parentPointer:TNode = foundNode.parentNode;
while (!(parentPointer is RootNode)) {
parentPointer.openNode();
parentPointer = parentPointer.parentNode;
}
var foundIndex:int = dataProvider.getItemIndex(foundNode);
return foundIndex;
}
return -1;
}
/**
* Finds the first instance of the node in the tree where
* the value in the field designated by fieldName
* is equal to fieldValue
and opens all parent nodes
* of the found node, so that the found node becomes visible.
*
* @param fieldName The name of the field in the node object to check.
* @param fieldValue The value to look for in the specified field.
*
* @return A node that contains the given value in the specified field; or null if
* no such node is found.
*
*/
public function exposeNode (fieldName:String, fieldValue:String) : TNode {
var foundNode:TNode = findNode(fieldName, fieldValue);
if (foundNode != null) {
showNode(foundNode);
return(foundNode);
}
return null;
}
/**
* Toggles a specified branch node to change state:
* if the node is open, it would close, and vice versa.
*
This method is deprecated. Use BranchNode.openNode()
* and BranchNode.closeNode()
instead.
dataProvider
object
* to be displayed as the label for the TextInput field and drop-down list.
*
* By default, the component displays the label
property
* of each dataProvider
item. If the dataProvider
* items do not contain a label
property, you can set the
* labelField
property to use a different property.
Note: The labelField
property is not used
* if the labelFunction
property is set to a callback function.