Class: Tree

Constructor

new Tree(root_textopt)

Creates an instance of Tree component object.

Parameters:

Name	Type	Attributes	Description
`root_text`	string	<optional>	Text to be displayed in the root element. Root element may not be visible if not set to be visible with `showRootHandle(true)`.

See: Tree#showRoot

Example

// Format of tree item object (Only "text" is requited, other fields are optional)
{
    text: string,           // Item text (Required)
    [id]: string|number,    // Value that can be used by software logic to identify this item
    [value]: string|number, // Additional value to be stored in the item for later use.
    [icon]: string,         // Absolute or relative path to icon image, base64 encoded image string, or `null` to remove icon.
    [color]: string,        // Item text color as a 6 character hex encoded color string (e.g. #665500)
    [background]: string,   // Item background color as a 6 character hex encoded color string (e.g. #665500)
    [tooltip]: string,      // Tooltip text to show when pointer hover the item. (in List and Tree components only)
    [font]: font object     // Object{name: string, size: number, bold: boolean, ...}. See complete list of font properties in example of font() method.
    [children]:object[]     // An array of children (when adding or recursively retrieving).
}

Classes

Tree

Methods

add(items, index, insertAtopt) → {Tree}

Add an item or array of items to a tree node. To add item to root node use [0] for index argument.

Parameters:

Name	Type	Attributes	Description
`items`	object \| Array.<object>		One item object or an array of item objects.
`index`	Array.<number>		Index of the item to insert the passed items to. To add to the root use [0].
`insertAt`	number \| undefined	<optional>	Indicates at what position to inserted the items. Value -1 means the end of list.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

childCount(indexopt) → {number|undefined}

Returns the amount of child nodes under the node specified by index argument.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Index path of an item in question. Default is the root item.

Returns:

Returns a number of child items the specified item has, or undefined if the index doesn't point to an item.

Type:: number | undefined

clear(indexopt) → {Tree}

Removes all children items of item at specified index. If no index path is specified, [0] root is cleared.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Index path of the item to clear. If omitted, the root node will be cleared.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

clicksToEdit(clicksopt) → {number|Tree}

Gets or sets how many consecutive clicks are required to start editing an item's text. The Tree component is not editable by default, therefore editing should be enabled by UIComponent#editable method for these clicks have effect. See example below.

Parameters:

Name	Type	Attributes	Description
`clicks`	number	<optional>	Amount of rapid clicks required (1 or 2). Default is 2. If omitted, the current value is returned.

Returns:

When called without parameters, current value is returned; otherwise returns this Tree component for method chaining.

Type:: number | Tree

Example

<h2>Enables editing, then sets 1 click to start editing:</h2>
tree.editable(true).clicksToEdit(1);

collapseAll(indexopt) → {Tree}

Collapses all items or a specified item and all if its children. If argument is not supplied, root is used by default.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Item which to collapse with all children items. If omitted, all items will be collapsed.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

editing(indexopt) → {Array.<number>|boolean|Tree|false}

Starts editing a specified item or stops editing all items when null is passed.

If no parameters are passed, it returns currently editing item's index or false if no item is being edited at the moment.

Editing state is when a user can type a new text into the item. Keep in mind that only one item can be editing at a time.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number> \| null	<optional>	Index of the item to start editing. Pass `null` to stop editing currently editing item (if any).

Returns:

If index argument is passed, this Tree component is returned. When no arguments are provided, returns an index of item being edited at the moment (if any), or false if no item is being edited.

Type:: Array.<number> | boolean | Tree | false

Examples

<h2>Starting to edit a specified item:</h2>
tree.editing([0, 2]);

<h2>Stop editing all items:</h2>
tree.editing(null);

<h2>Check which item is editing now:</h2>
let index = tree.editing(); // -> array or false.

expandAll(indexopt) → {Tree}

Expands all items or a specified item and all if its children. If argument is not supplied, root is used by default.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Item which to expand with all children items. If omitted, all items will be expended.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

expanded(index, expandedopt, recursiveopt) → {boolean|undefined|Tree}

Sets or gets the expand state of a specified item that has children. Items without children cannot be expanded. When setting expanded argument and index doesn't point to an item then just nothing will happen.

Parameters:

Name	Type	Attributes	Default	Description
`index`	Array.<number>			Index path of the item in question
`expanded`	boolean	<optional>		Pass `true` or `false` to set the expand state, or omit to get current state.
`recursive`	boolean	<optional>	false	Whether the specified `expand` state should be applied to all children items recursively. Default is `false`.

Returns:

If expanded argument is passed, then this Tree component is returned; otherwise current expand state is returned, or undefined if specified index in not valid.

Type:: boolean | undefined | Tree

Examples

<h2>Expand root node:</h2>
tree.expended([0], true);

<h2>Collapse item at specified index:</h2>
tree.expended([0, 2], false);

<h2>Check if item at specified index is expanded:</h2>
let expanded = tree.expended([0, 2]);

findByID(id) → {Array.<object>}

Finds items whose id property matches the argument. Returns an array of found items.

Parameters:

Name	Type	Description
`id`	string \| number	Value of item's `id` property to match when finding items.

Returns:

Returns an array of found items.

Type:: Array.<object>

findByText(text) → {Array.<object>}

Finds items whose text property matches the argument. Returns an array of found items.

Parameters:

Name	Type	Description
`text`	string	Text to match when finding items.

Returns:

Returns an array of found items.

Type:: Array.<object>

findByValue(value) → {Array.<object>}

Finds items whose value property matches the argument. Returns an array of found items.

Parameters:

Name	Type	Description
`value`	string \| number	Value of item's `value` property to match when finding items.

Returns:

Returns an array of found items.

Type:: Array.<object>

focusedItem(indexopt) → {Array.<number>|undefined|Tree}

Gets or sets currently focused item in the tree. Focus is little different than selection. Focus can be controlled by focus traversing keys, such as Tab, and focused item is not always an item being selected. Multiple items may be selected at a time, but only one item can retain focus at a time.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Index of one item (array of numbers).

Returns:

When no parameters are passed, returns currently focused item or undefined when no item is focused. When index is provided, this Tree component is returned.

Type:: Array.<number> | undefined | Tree

icons(icons) → {Tree}

Sets custom icons to be used for open node, closed node, and leaf node.

Example of icons object: {closed:"icons/closed.png", open:"icons/open.png", leaf:"icons/leaf.png"}. Each element is optional.

Note: all properties of this object are optional.

Parameters:

Name	Type	Description
`icons`	Object	An object of icons to set. Each icon is optional. When some icons are omitted, default ones will be used.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

Example

tree.icons({
     closed:"icons/closed.png",
     open:"icons/open.png",
     leaf:"icons/leaf.png"
});

item(index, itemopt)

Updates or gets an item at specified index.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>		Index of the item to get or update.
`item`	object	<optional>	Item object. Omit this argument to get the item instead of updating it.

Returns:

[object|undefined|Tree] If item argument is passed, this Tree component is returned; otherwise an item at specified index is returned, or null if passed index is invalid.

Example

// update an item at index [0,3,5]
tree.item([0,3,5], {text:"New item text"});

// get an item at index [0,3,5]
let item = tree.item([0,3,5]);
console.log(item?.text); // checks if item is not undefined

items(indexopt, items_or_recursiveopt) → {Array.<object>|undefined|Tree}

Sets or gets a list of items for a node at specified index. Setting the list of items will replace current items at specified index before adding new ones. To simply remove existing items pass an empty array as a second parameter.

Parameters:

Name	Type	Attributes	Default	Description
`index`	Array.<number>	<optional>	[0]	Index of target item. Default is [0] tree root node
`items_or_recursive`	boolean \| Array.<object>	<optional>	false	To set items, pass an array of items, or empty array to simply remove all items. When getting items you can specify a `boolean` whether to get all children items recursively or not. Default is `false`.

Returns:

If setting items then this Tree component is returned. If getting items then Array of items is returned, or undefined if index doesn't point to an item in the Tree.

Type:: Array.<object> | undefined | Tree

Examples

<h2> Set items at the root node:</h2>
tree.items([0], [
  { text: "Videos", id: 1, icon: "icons/folder-videos.png" },
  { text: "Photos", id: 2, icon: "icons/folder-images.png" }
]);

<h2>Set items at a child node:</h2>
tree.items([0,0], [
  { text: "Video 1", id: "a1", value: "video1.mp4" },
  { text: "Video 2", id: "a2", value: "video2.mp4", tooltip: "Second video" }
]);

<h2>Get direct children of a node:</h2>
const rootItems = tree.items([0]);
console.log(rootItems); // → [ {text: "Videos", id: 1, ...}, {text: "Photos", id: 2, ...} ]

<h2>Get items recursively from a node:</h2>
const deepItems = tree.items([0,0], true);
console.log(deepItems); // → [ {text: "Video 1", id: "a1", ...}, {text: "Video 2", id: "a2", ...} ]

<h2>Get from a non-existing index:</h2>
const nothing = tree.items([9]);
console.log(nothing); // → undefined

moveItem(index, toIndex, insertAtopt) → {Tree}

Moves one item from one location (index path) to another within the same Tree component.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>		Index path of the item you want to move.
`toIndex`	Array.<number>		Index of a new parent for specified item.
`insertAt`	number	<optional>	Index position at which to insert the item into parent (apply applies only if the parent item already has some items).

Returns:

Returns this Tree component for method chaining.

Type:: Tree

moveItems(indexes, toIndex, insertAtopt) → {Tree}

Moves one or more items from one location (index path) to another within the same Tree component. Items will be inserted in the order they are in the provided indexes array.

Parameters:

Name	Type	Attributes	Description
`indexes`	Array.<Array.<number>>		Array of index arrays of items you want to move.
`toIndex`	Array.<number>		Index of a new parent for specified items.
`insertAt`	number	<optional>	Index position at which to insert the item(s) into parent (apply applies only if the parent item already has some items).

Returns:

Returns this Tree component for method chaining.

Type:: Tree

onItemsEvents(callbackopt, removeopt) → {Array.<function()>|Tree}

Gets, registers or unregisters an event handler function for events triggered by adding, removing, updating items and when the Tree structure is changed.

Parameters:

Name	Type	Attributes	Default	Description
`callback`	function	<optional>		The event handler function. Receives an event object.
`remove`	boolean	<optional>	false	Set to `true` to unregister the event handler.

Returns:

When called without parameters, an array of handler functions is returned, otherwise this Tree component is returned for method chaining.

Type:: Array.<function()> | Tree

Examples

<h2>Event object format:</h2>
Object {
    target: Tree,        // The component that triggered the event
    type: string,        // "add", "update", "remove", or "restructure".
    items: object[],     // Items effected by the action that triggered the event
    interactive: boolean // Only when type is "update". Indicates if the update was made by the user interacting with the item in GUI. `false` when updated programmatically.
}

<h2>Registering an event handler:</h2>
tree.onItemsEvents(e=>{alert(e.type);}); // shows the event type in a new message dialog window

<h2>Unregistering all registered event handlers:</h2>
let _handlers = tree.onItemsEvents(); // gets all handlers

for(let handler of _handlers) tree.onItemsEvents(handler, false); // unregisters each handler

remove(indexopt) → {Tree}

Removes item at specified index argument or removes this Tree component from its parent if no argument is passed.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number>	<optional>	Index if the item to remove. Omit this argument to remove this Tree from its parent.

Returns:

Returns this Tree component for method chaining.

Type:: Tree

selectAll(selectedopt) → {Tree}

Selects/Deselects all items in the Tree

Parameters:

Name	Type	Attributes	Default	Description
`selected`	boolean	<optional>	true	`true` to select all items, `false` to deselect all items.

Returns:

Returns an instance of this Tree for method chaining.

Type:: Tree

selected(index, selectedopt) → {boolean|Tree}

Sets or get a whether item or items at specified index or array o indexes are selected. This adds or removes items to/from current selection instead of replacing current selection like selection() method does. If "selected" argument is supplied, it will select or deselect specified items.

Parameters:

Name	Type	Attributes	Description
`index`	Array.<number> \| Array.<Array.<number>>		Index path of one item as array, or multiple items as array of arrays. When getting selection status, only first item is used.
`selected`	boolean	<optional>	If supplied, it will indicate if specified items should be selected or not.

Returns:

If selected arguments is passed, this Tree component is returned; otherwise a selection status of first specified item is returned, or undefined if index doesn't point to an item.

Type:: boolean | Tree

Examples

<h2>Add one item to current selection:</h2>
tree.selected([0,2], true);

<h2>Add two items to current selection:</h2>
tree.selected([[0,3], [0,4]], true);

<h2>Deselect one item:</h2>
tree.selected([0,3], false);

<h2>Check if one item is selected:</h2>
let selected = tree.selected([0,4]); // -> true

selection(indexesopt) → {Array.<Array.<number>>|Tree}

Gets or sets the selected items in the tree. When setting selection, items that were previously selected but are not in the passed array will get deselected.

To get the current selection, call without arguments.
To set the selection, pass an array of index paths (array of arrays of numbers).

Parameters:

Name	Type	Attributes	Description
`indexes`	Array.<Array.<number>>	<optional>	An array of index paths to select. (array of arrays)

Returns:

Returns the current selection when called without arguments, or this Tree instance when setting.

Type:: Array.<Array.<number>> | Tree

selectionMode(modeopt) → {SelectionMode|Tree}

Sets or gets a selection mode of the tree items, which defines how items can be selected (only one item, a multiple items as a range, or any combination of items).

Parameters:

Name	Type	Attributes	Description
`mode`	SelectionMode	<optional>	One of: SelectionMode.Single, SelectionMode.Multiple, SelectionMode.Range. See SelectionMode

See: SelectionMode

Returns:

If no arguments are supplied, current selection mode is returned; otherwise this Tree component is returned.

Type:: SelectionMode | Tree

Example

<h2>Setting a selection mode:</h2>
tree.selectionMode(SelectionMode.Single);

showIcons(showopt) → {boolean|Tree}

Shows or hides all icons in the tree.

Parameters:

Name	Type	Attributes	Description
`show`	boolean	<optional>	`true` to show, `false` to hide.

Returns:

If no arguments are passed, current value is returned; otherwise this Tree component is returned for method chaining.

Type:: boolean | Tree

showRoot(showopt) → {boolean|Tree}

Sets or gets visibility of a root node of the tree.

Parameters:

Name	Type	Attributes	Description
`show`	boolean	<optional>	`true` to show, `false` to hide.

Returns:

If no arguments are passed, current value is returned; otherwise this Tree component is returned for method chaining.

Type:: boolean | Tree

showRootHandle(showopt) → {boolean|Tree}

Sets or gets visibility of a root node handle (the one that's used to expand/collapse the node to show/hide child nodes).

Parameters:

Name	Type	Attributes	Description
`show`	boolean	<optional>	`true` to show, `false` to hide.

Returns:

If no arguments are passed, current value is returned; otherwise this Tree component is returned for method chaining.

Type:: boolean | Tree