CLASS:: TreeView
summary:: A view displaying a tree of items with columns
categories:: GUI>Views

DESCRIPTION::

A view that displays a hierarchy of items. It is divided into rows and column: each row represents an item, and each column represents a different data field of the items.

The items are represented in code by instances of link::Classes/TreeViewItem::, returned by the various TreeView methods. Top level items are added via the TreeView interface, while child items are added via the TreeViewItem interface, which also allows to manipulate items in more detail after their creation.

Items can be visually sorted with link::#-sort::, or by clicking on one of the column headers, if link::#-canSort:: is enabled.

Each item can hold other views in each of its data fields, which allows for rich graphical interaction. See link::Classes/TreeViewItem#-setView::.


CLASSMETHODS::

PRIVATE:: key

INSTANCEMETHODS::

PRIVATE:: prForEachColumnDataPair
PRIVATE:: prValidItem


SUBSECTION:: Data

METHOD:: columns
	Gets or sets the number of columns (data fields) and their names. When setting a smaller number of columns than the current the extra columns will be removed, and hence all the data stored stored in those columns.

	ARGUMENT::
		An array of Strings for column names.

METHOD:: numColumns
	The total number of columns (data fields).

METHOD:: addItem
	Append a new top-level item.

	ARGUMENT:: strings
		An array of Strings (or nil), each for the text of one data field.
	RETURNS::
		An instance of TreeViewItem representing the new item.

METHOD:: insertItem
	Insert a new top-level item at code::index::.

	ARGUMENT:: index
		The position at which to insert the item.
	ARGUMENT:: strings
		An array of Strings (or nil), each for the text of one data field.
	RETURNS::
		An instance of TreeViewItem representing the new item.

METHOD:: removeItem
	Remove the given code::item::. After the item is removed, any usage of the related TreeViewItems will have no effect.

	ARGUMENT::
		An instance of TreeViewItem.

METHOD:: numItems
	The total number of items.

METHOD:: clear
    Removes all items.

METHOD:: currentItem
	Gets or sets the currently selected item.

	ARGUMENT::
		An instance of TreeViewItem.
	RETURNS::
		An instance of TreeViewItem or nil, if no current item.

METHOD:: itemAt
	The item at code::index::.

METHOD:: childAt
	Alias for link::#-itemAt::, provided for compatibility with TreeViewItem.

METHOD:: addChild
	Alias for link::#-addItem::, provided for compatibility with TreeViewItem.

METHOD:: insertChild
	Alias for link::#-addChild::, provided for compatibility with TreeViewItem.

SUBSECTION:: Appearance

METHOD:: sort
	Sort items by data in code::column::. This works regardless of link::#-canSort::.

	NOTE:: Sorting has no effect on the logical order of the items, it only affects how they are displayed. ::

	ARGUMENT:: column
		The integer column index to sort by.
	ARGUMENT:: descending
		Whether to sort in descending or ascending fashion. The default is ascending.

METHOD:: columnWidth

	ARGUMENT:: column
		The integer index of a column
	RETURNS::
		Integer width of column in pixels. If code::column:: is not in the range
		code::0..(numColumns-1)::, returns code::-1::.

METHOD:: setColumnWidth

Sets the width of a column. The rightmost column must extend at least to the right bound of the
TreeView.

	ARGUMENT:: column
		The integer index of the column to modify
	ARGUMENT:: width
		Integer width in pixels

PRIVATE:: background


SUBSECTION:: Interaction

METHOD:: canSort
	Whether the user can sort the items by clicking on a column header.

	When setting to code::true::, the items will be sorted immediately according to the current sorting column. While code::true::, the view will also automatically sort new items.

	The default is code::false::.

	See also: link::#-sort::.




SUBSECTION:: Actions

METHOD:: itemPressedAction
	The object to be evaluated when a mouse button is pressed on an item, passing this view as the argument.

METHOD:: onItemChanged
	The object to be evaluated whenever the current item changes, passing this view as the argument.


EXAMPLES::

CODE::

(
var t = TreeView().front;
t.columns_(["a", "b", "c", "d"]);
t.addItem(["A1", "B1", "C1", "D1"]);
t.addItem(["A2", "B2", "C2"]);
t.addItem(["A3", "B3"]);
t.addItem(["A4"]);
)


//sorting example
(
var names = ["black", "white", "red", "green", "blue", "cyan", "magenta", "yellow"];
var colors = names.collect{|str| Color.perform(str.asSymbol)};
var window, tree, popup;
window = Window.new("TreeView example - RGBA colors").front;
window.view.layout_(VLayout(
	tree = TreeView()
));
tree.columns_(["Index", "Name", "Int", "Hex"]);
tree.font = Font.defaultMonoFace;
tree.setColumnWidth(0, 60);
tree.setColumnWidth(2, 130);
names.do{|str, i|
	var intString = "% % % %".format(*(colors[i].asArray*255).asInteger);
	tree.addItem([i, str, intString, colors[i].hexString]);
};
tree.numItems.do{|i|
	var c = [Color.clear, colors[i], Color.clear, Color.clear];
	tree.itemAt(i).colors_(c).textColors_(Color.grey);
};
tree.onItemChanged_({|view|
	view.currentItem.strings.postln;
});
tree.canSort = true;
)
::
