class TreeView
package feathers.controls
extends BaseScrollContainer › FeathersControl › MeasureSprite › ValidatingSprite
implements IFocusContainer, IDataSelector<Dynamic>
Displays a hierarchical tree of items. Supports scrolling, custom item renderers, and custom layouts.
The following example creates a tree, gives it a data provider, tells the item renderer how to interpret the data, and listens for when the selection changes:
var treeView = new TreeView();
var collection = new ArrayHierarchicalCollection([
{
text: "Node 1",
children: [
{
text: "Node 1A",
children: [
{text: "Node 1A-I"},
{text: "Node 1A-II"},
{text: "Node 1A-III"},
{text: "Node 1A-IV"}
]
},
{text: "Node 1B"},
{text: "Node 1C"}
]
},
{
text: "Node 2",
children: [
{text: "Node 2A"},
{text: "Node 2B"},
{text: "Node 2C"}
]
},
{text: "Node 3"},
{
text: "Node 4",
children: [
{text: "Node 4A"},
{text: "Node 4B"},
{text: "Node 4C"},
{text: "Node 4D"},
{text: "Node 4E"}
]
}
]);
collection.itemToChildren = (item:Dynamic) -> {
return item.children;
};
treeView.dataProvider = collection;
treeView.itemToText = (item:Dynamic) -> {
return item.text;
};
treeView.addEventListener(Event.CHANGE, (event:Event) -> {
var treeView = cast(event.currentTarget, TreeView);
trace("TreeView changed: " + treeView.selectedLocation + " " + treeView.selectedItem.text);
});
this.addChild(treeView);Events:
openfl.events.Event.CHANGE | Dispatched when either
|
|---|---|
feathers.events.TreeViewEvent.ITEM_TRIGGER | Dispatched when the user taps or clicks an item renderer in the tree view. The pointer must remain within the bounds of the item renderer on release, and the tree view cannot scroll before release, or the gesture will be ignored. |
feathers.events.TreeViewEvent.BRANCH_OPEN | Dispatched when a branch is opened. |
feathers.events.TreeViewEvent.BRANCH_CLOSE | Dispatched when a branch is closed. |
1.0.0
.See also:
Static variables
staticfinalread onlyCHILD_VARIANT_ITEM_RENDERER:String = "treeView_itemRenderer"
The variant used to style the tree view's item renderers in a theme.
To override this default variant, set the
TreeView.customItemRendererVariant property.
1.0.0
.See also:
staticfinalread onlyVARIANT_BORDER:String = "border"
A variant used to style the tree view with a border. This variant is used by default on desktop.
The following example uses this variant:
var treeView = new TreeView();
treeView.variant = TreeView.VARIANT_BORDER;1.0.0
.See also:
staticfinalread onlyVARIANT_BORDERLESS:String = "borderless"
A variant used to style the tree view without a border. The variant is used by default on mobile.
The following example uses this variant:
var treeView = new TreeView();
treeView.variant = TreeView.VARIANT_BORDERLESS;1.0.0
.See also:
Constructor
new(?dataProvider:IHierarchicalCollection<Dynamic>, ?changeListener:Event ‑> Void)
Creates a new TreeView object.
1.0.0
.Variables
customItemRendererVariant:String
A custom variant to set on all item renderers, instead of
TreeView.CHILD_VARIANT_ITEM_RENDERER.
The customItemRendererVariant will be not be used if the result of
itemRendererRecycler.create() already has a variant set.
1.0.0
.See also:
dataProvider:IHierarchicalCollection<Dynamic>
The collection of data displayed by the tree view.
Items in the collection must be class instances or anonymous structures. Do not add primitive values (such as strings, booleans, or numeric values) directly to the collection.
Additionally, all items in the collection must be unique object instances. Do not add the same instance to the collection more than once because a runtime exception will be thrown.
The following example passes in a data provider and tells the item renderer how to interpret the data:
var collection = new ArrayHierarchicalCollection([
{
text: "Node 1",
children: [
{
text: "Node 1A",
children: [
{text: "Node 1A-I"},
{text: "Node 1A-II"},
{text: "Node 1A-III"},
{text: "Node 1A-IV"}
]
},
{text: "Node 1B"},
{text: "Node 1C"}
]
},
{
text: "Node 2",
children: [
{text: "Node 2A"},
{text: "Node 2B"},
{text: "Node 2C"}
]
},
{text: "Node 3"},
{
text: "Node 4",
children: [
{text: "Node 4A"},
{text: "Node 4B"},
{text: "Node 4C"},
{text: "Node 4D"},
{text: "Node 4E"}
]
}
]);
collection.itemToChildren = (item:Dynamic) -> {
return item.children;
};
treeView.dataProvider = collection;
treeView.itemToText = (item:Dynamic) -> {
return item.text;
};1.0.0
.See also:
forceItemStateUpdate:Bool
Forces the itemRendererRecycler.update() method to be called with the
TreeViewItemState when the tree view validates, even if the item's
state has not changed since the previous validation.
Before Feathers UI 1.2, update() was called more frequently, and this
property is provided to enable backwards compatibility, temporarily, to
assist in migration from earlier versions of Feathers UI.
In general, when this property needs to be enabled, its often because of
a missed call to dataProvider.updateAt() (preferred) or
dataProvider.updateAll() (less common).
The forceItemStateUpdate property may be removed in a future major
version, so it is best to avoid relying on it as a long-term solution.
1.2.0
.itemRendererRecycler:AbstractDisplayObjectRecycler<Dynamic, TreeViewItemState, DisplayObject>
Manages item renderers used by the tree view.
In the following example, the tree view uses a custom item renderer class:
treeView.itemRendererRecycler = DisplayObjectRecycler.withClass(CustomItemRenderer);1.0.0
.See also:
layout:ILayout
The layout algorithm used to position and size the tree view's items.
By default, if no layout is provided by the time that the tree view initializes, a default layout that displays items vertically will be created.
The following example tells the tree view to use a horizontal layout:
var layout = new HorizontalListLayout();
layout.gap = 20.0;
layout.padding = 20.0;
treeView.layout = layout;1.0.0
.pointerSelectionEnabled:Bool = true
Indicates if selection is changed with MouseEvent.CLICK or
TouchEvent.TOUCH_TAP when the item renderer does not implement the
IToggle interface. If set to false, all item renderers must control
their own selection manually (not only ones that implement IToggle).
The following example disables pointer selection:
treeView.pointerSelectionEnabled = false;1.0.0
.selectable:Bool
Determines if items in the tree view may be selected. By default only a single item may be selected at any given time. In other words, if item A is already selected, and the user selects item B, item A will be deselected automatically.
The following example disables selection of items in the tree view:
treeView.selectable = false;1.0.0
.See also:
selectedLocation:Array<Int>
The currently selected location. Returns null if no location is
selected.
The following example selects a specific location:
treeView.selectedLocation = [2, 0];The following example clears the currently selected location:
treeView.selectedLocation = null;The following example listens for when the selection changes, and it prints the new selected location to the debug console:
var treeView = new TreeView();
function changeHandler(event:Event):Void
{
var treeView = cast(event.currentTarget, TreeView);
trace("selection change: " + treeView.selectedLocation);
}
treeView.addEventListener(Event.CHANGE, changeHandler);1.0.0
.virtualLayout:Bool
Indicates if the tree view's layout is allowed to virtualize items or not.
The following example disables virtual layouts:
treeView.virtualLayout = false;1.0.0
.itemRendererRecyclerIDFunction:(state:TreeViewItemState) ‑> String
When a tree view requires multiple item renderer types, this function is
used to determine which type of item renderer is required for a specific
item. Returns the ID of the item renderer recycler to use for the item,
or null if the default itemRendererRecycler should be used.
The following example provides an itemRendererRecyclerIDFunction:
var regularItemRecycler = DisplayObjectRecycler.withClass(HierarchicalItemRenderer);
var firstItemRecycler = DisplayObjectRecycler.withClass(MyCustomItemRenderer);
treeView.setItemRendererRecycler("regular-item", regularItemRecycler);
treeView.setItemRendererRecycler("first-item", firstItemRecycler);
treeView.itemRendererRecyclerIDFunction = function(state:TreeViewItemState):String {
if(state.location.length == 1 && state.location[0] == 0) {
return "first-item";
}
return "regular-item";
};1.0.0
.See also:
`TreeView.itemRendererRecycler
Methods
getItemRendererRecycler(id:String):DisplayObjectRecycler<Dynamic, TreeViewItemState, DisplayObject>
Returns the item renderer recycler associated with a specific ID.
Returns null if no recycler is associated with the ID.
1.0.0
.See also:
isBranchOpen(branch:Dynamic):Bool
Indicates if a branch is currently opened or closed. If the object is
not a branch, or does not exist in the data provider, returns false.
1.0.0
.itemRendererToItem(itemRenderer:DisplayObject):Dynamic
Returns the current item from the data provider that is rendered by a specific item renderer.
1.0.0
.dynamicitemToEnabled(data:Dynamic):Bool
Determines if an item should be enabled or disabled. By default, all
items are enabled, unless the TreeView is disabled. This method
may be replaced to provide a custom value for enabled.
For example, consider the following item:
{ text: "Example Item", disable: true }If the TreeView should disable an item if the disable field is
true, a custom implementation of itemToEnabled() might look like
this:
treeView.itemToEnabled = (item:Dynamic) -> {
return !item.disable;
};1.2.0
.itemToItemRenderer(item:Dynamic):DisplayObject
Returns the current item renderer used to render a specific item from
the data provider. May return null if an item doesn't currently have
an item renderer.
Note: Most tree views use "virtual" layouts, which means that only the currently-visible subset of items will have an item renderer. As the tree view scrolls, the items with item renderers will change, and item renderers may even be re-used to display different items.
1.0.0
.itemToItemState(item:Dynamic):TreeViewItemState
Returns a TreeViewItemState representing a specific item.
1.3.0
.dynamicitemToText(data:Dynamic):String
Converts an item to text to display within tree view. By default, the
toString() method is called to convert an item to text. This method
may be replaced to provide custom text.
For example, consider the following item:
{ text: "Example Item" }If the TreeView should display the text "Example Item", a custom
implementation of itemToText() might look like this:
treeView.itemToText = (item:Dynamic) -> {
return item.text;
};1.0.0
.locationToItemRenderer(location:Array<Int>):DisplayObject
Returns the current item renderer used to render the item at the
specified location in the data provider. May return null if an item
doesn't currently have an item renderer.
Note: Most tree views use "virtual" layouts, which means that only the currently-visible subset of items will have an item renderer. As the tree view scrolls, the items with item renderers will change, and item renderers may even be re-used to display different items.
1.0.0
.scrollToLocation(location:Array<Int>, ?animationDuration:Float):Void
Scrolls the tree view so that the specified item renderer is completely visible. If the item renderer is already completely visible, does not update the scroll position.
A custom animation duration may be specified. To update the scroll
position without animation, pass a value of 0.0 for the duration.
1.0.0
.setItemRendererRecycler(id:String, recycler:AbstractDisplayObjectRecycler<Dynamic, TreeViewItemState, DisplayObject>):Void
Associates an item renderer recycler with an ID to allow multiple types
of item renderers may be displayed in the tree view. A custom
itemRendererRecyclerIDFunction may be specified to return the ID of
the recycler to use for a specific item in the data provider.
To clear a recycler, pass in null for the value.
1.0.0
.See also:
toggleChildrenOf(branch:Dynamic, open:Bool):Void
Opens or closes all children of a branch recursively.
1.0.0
.