Class RapidContext.Widget.TreeNode

.Widget.TreeNode(attrs, …childopt) → {Widget}

The tree node widget class. Used to provide a tree node in a tree, using a number of <div> HTML elements. Note that events should normally not be listened for on individual tree nodes, but rather on the tree as a whole.

Constructor Summary
	`new TreeNode(attrs, …childopt) → {Widget}` Creates a new tree node widget.

Method Summary
	`addAll(…child)` Adds one or more children to this widget.
	`addChildNode(child)` Adds a single child tree node widget to this widget.
	`addClass(…cls)` Adds the specified CSS class names to this HTML DOM node.
	`blurAll()` Blurs (unfocuses) this DOM node and all relevant child nodes.
	`collapse()` Collapses this node to hide any child nodes.
	`collapseAll(depthopt)` Recursively collapses this node and all its children.
	`destroy()` The internal widget destructor function.
	`disable()` Disables this widget if it was previously enabled.
	`emit(event, optsopt) → {boolean}` Dispatches a single event from this DOM node.
	`enable()` Enables this widget if it was previously disabled.
	`expand()` Expands this node to display any child nodes.
	`expandAll(depthopt)` Recursively expands this node and all its children.
	`findByPath(path) → {Widget}` Searches for a descendant tree node from the specified path.
	`findChild(name) → {Widget}` Finds a child tree node with the specified name.
	`getChildNodes() → {Array}` Returns an array with all child DOM nodes.
	`hasClass(…cls) → {boolean}` Checks if this HTML DOM node has the specified CSS class names.
	`hide()` Hides this widget node if it was previously visible.
	`isDisabled() → {boolean}` Checks if this widget is disabled.
	`isExpanded() → {boolean}` Checks if this folder node is expanded.
	`isFolder() → {boolean}` Checks if this node is a folder.
	`isHidden() → {boolean}` Checks if this widget node is hidden.
	`isSelected() → {boolean}` Checks if this node is selected.
	`markAll()` Marks this tree node and all child nodes recursively.
	`off(eventopt, selectoropt, listeneropt) → {Node}` Removes one or more previously attached event listeners.
	`on(event, selectoropt, listener, optsopt) → {Node}` Attaches a listener function for one or more events.
	`once(event, selectoropt, listener, optsopt) → {Node}` Attaches a single event listener function.
	`parent() → {Widget}` Returns the parent tree node widget.
	`path() → {Array}` Returns the path to this tree node.
	`removeAll()` Removes all children to this widget.
	`removeAllMarked()` Removes all marked tree nodes.
	`removeChildNode(child)` Removes a single child tree node widget from this widget.
	`removeClass(…cls)` Removes the specified CSS class names from this HTML DOM node.
	`select()` Selects this tree node.
	`setAttrs(attrs)` Updates the widget or HTML DOM node attributes.
	`setStyle(styles)` Updates the CSS styles of this HTML DOM node.
	`show()` Shows this widget node if it was previously hidden.
	`toggle()` Toggles expand and collapse for this node.
	`toggleClass(…cls) → {boolean}` Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
	`tree() → {Widget}` Returns the ancestor tree widget.
	`uid() → {string}` Returns the unique identifier for this DOM node.
	`unselect()` Unselects this tree node.

Constructor

new TreeNode(attrs, …childopt) → {Widget}

Creates a new tree node widget.

Parameters:

Name Type Attributes Description

attrs

{Object}

the widget and node attributes

Properties

Name	Type	Attributes	Description
`name`	{string}		the tree node name
`folder`	{boolean}	<optional>	the folder flag, defaults to `false` if no child nodes are provided in constructor call
`icon`	{string}	<optional>	the icon reference to use, defaults to "FOLDER" for folders and "DOCUMENT" otherwise
`tooltip`	{string}	<optional>	the tooltip text when hovering
`hidden`	{boolean}	<optional>	the hidden widget flag, defaults to `false`

child {TreeNode} <optional>
<repeatable> the child tree node widgets

Returns:

{Widget} the widget DOM node

Examples:

JavaScript

let parent = RapidContext.Widget.TreeNode({ folder: true, name: "Parent" });
let child = RapidContext.Widget.TreeNode({ name: "Child" });
parent.addAll(child);

User Interface XML

<TreeNode name="Parent">
  <TreeNode name="Child" />
</TreeNode>

Source:

RapidContext_Widget_TreeNode.js, line 53

Extends

RapidContext.Widget

Methods

addAll(…child)

Adds one or more children to this widget. This method will flatten any arrays among the arguments and ignores any null or undefined arguments. Any DOM nodes or widgets will be added to the end, and other objects will be converted to a text node first. Subclasses should normally override the addChildNode() method instead of this one, since that is the basis for DOM node insertion.

Parameters:

Name	Type	Attributes	Description
`child`	{string\|Node\|Array}	<repeatable>	the children to add

Inherited From:

RapidContext.Widget#addAll

Source:

RapidContext_Widget.js, line 531

addChildNode(child)

Adds a single child tree node widget to this widget.

Parameters:

Name	Type	Description
`child`	{Widget}	the tree node widget to add

Overrides:

RapidContext.Widget#addChildNode

Source:

RapidContext_Widget_TreeNode.js, line 135

addClass(…cls)

Adds the specified CSS class names to this HTML DOM node.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to add

Inherited From:

RapidContext.Widget#addClass

Source:

RapidContext_Widget.js, line 327

blurAll()

Blurs (unfocuses) this DOM node and all relevant child nodes. This function will recursively blur all <a>, <button>, <input>, <textarea> and <select> child nodes found.

Inherited From:: RapidContext.Widget#blurAll
Source:: RapidContext_Widget.js, line 471

collapse()

Collapses this node to hide any child nodes.

Source:: RapidContext_Widget_TreeNode.js, line 389

collapseAll(depthopt)

Recursively collapses this node and all its children. If a depth is specified, only children below that depth will be collapsed.

Parameters:

Name	Type	Attributes	Description
`depth`	{number}	<optional>	the optional minimum depth

Source:

RapidContext_Widget_TreeNode.js, line 411

destroy()

The internal widget destructor function. This method should only be called by destroyWidget() and may be overridden by subclasses. By default this method does nothing.

Inherited From:: RapidContext.Widget#destroy
Source:: RapidContext_Widget.js, line 197

disable()

Disables this widget if it was previously enabled. This method is equivalent to calling setAttrs({ disabled: true }).

Inherited From:: RapidContext.Widget#disable
Source:: RapidContext_Widget.js, line 416

emit(event, optsopt) → {boolean}

Dispatches a single event from this DOM node. Also creates a new CustomEvent instance if needed.

Parameters:

Name Type Attributes Description

event {string/Event} the event type name or instance

opts

{Object}

the event options

Properties

Name	Type	Attributes	Default	Description
`async`	{boolean}	<optional>	true	the async dispatch flag
`bubbles`	{boolean}	<optional>		the event bubbles flag
`cancelable`	{boolean}	<optional>		the cancellable event flag
`detail`	{Object}	<optional>		the additional event details

Returns:

{boolean} true if event was async or not cancelled

Inherited From:

RapidContext.UI.Event#emit

Source:

rapidcontext/ui/event.mjs, line 26

enable()

Enables this widget if it was previously disabled. This is equivalent to calling setAttrs({ disabled: false }).

Inherited From:: RapidContext.Widget#enable
Source:: RapidContext_Widget.js, line 408

expand()

Expands this node to display any child nodes. If the parent node is not expanded, it will be expanded as well.

Source:: RapidContext_Widget_TreeNode.js, line 347

expandAll(depthopt)

Recursively expands this node and all its children. If a depth is specified, expansions will not continue below that depth.

Parameters:

Name	Type	Attributes	Description
`depth`	{number}	<optional>	the optional maximum depth

Source:

RapidContext_Widget_TreeNode.js, line 373

findByPath(path) → {Widget}

Searches for a descendant tree node from the specified path.

Parameters:

Name	Type	Description
`path`	{Array}	the tree node path (array of node names)

Returns:

{Widget} the descendant tree node found, or null if not found

Source:

RapidContext_Widget_TreeNode.js, line 308

findChild(name) → {Widget}

Finds a child tree node with the specified name.

Parameters:

Name	Type	Description
`name`	{string}	the child tree node name

Returns:

{Widget} the child tree node found, or null if not found

Source:

RapidContext_Widget_TreeNode.js, line 290

getChildNodes() → {Array}

Returns an array with all child DOM nodes. Note that the array is a real JavaScript array, not a dynamic NodeList. This method is sometimes overridden by child widgets in order to hide intermediate DOM nodes required by the widget.

Returns:: {Array} the array of child DOM nodes
Inherited From:: RapidContext.Widget#getChildNodes
Source:: RapidContext_Widget.js, line 483

hasClass(…cls) → {boolean}

Checks if this HTML DOM node has the specified CSS class names. Note that more than one CSS class name may be checked, in which case all must be present.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to check

Returns:

{boolean} true if all CSS classes were present, or false otherwise

Inherited From:

RapidContext.Widget#hasClass

Source:

RapidContext_Widget.js, line 310

hide()

Hides this widget node if it was previously visible. This method is equivalent to calling setAttrs({ hidden: true }). It is safe for all types of widgets, since it only adds the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#hide
Source:: RapidContext_Widget.js, line 462

isDisabled() → {boolean}

Checks if this widget is disabled. This method checks both the "widgetDisabled" CSS class and the disabled property. Changes to the disabled status can be made with enable(), disable() or setAttrs().

Returns:: {boolean} true if the widget is disabled, or false otherwise
Inherited From:: RapidContext.Widget#isDisabled
Source:: RapidContext_Widget.js, line 387

isExpanded() → {boolean}

Checks if this folder node is expanded.

Returns:: {boolean} true if this node is expanded, or false otherwise
Source:: RapidContext_Widget_TreeNode.js, line 218

isFolder() → {boolean}

Checks if this node is a folder.

Returns:: {boolean} true if this node is a folder, or false otherwise
Source:: RapidContext_Widget_TreeNode.js, line 208

isHidden() → {boolean}

Checks if this widget node is hidden. This method checks for the existence of the widgetHidden CSS class. It does NOT check the actual widget visibility (the display style property set by animations for example).

Returns:: {boolean} true if the widget is hidden, or false otherwise
Inherited From:: RapidContext.Widget#isHidden
Source:: RapidContext_Widget.js, line 429

isSelected() → {boolean}

Checks if this node is selected.

Returns:: {boolean} true if the node is selected, or false otherwise
Source:: RapidContext_Widget_TreeNode.js, line 229

markAll()

Marks this tree node and all child nodes recursively. When adding or updating tree nodes, any node modified is automatically unmarked (e.g. by calling setAttrs). This makes it easy to prune a tree after an update, by initially marking all tree nodes, inserting or touching all nodes to keep, and finally calling removeAllMarked() to remove the remaining nodes.

Example:

parent.markAll();
parent.setAttrs();
child.setAttrs();
...
parent.removeAllMarked();

Source:

RapidContext_Widget_TreeNode.js, line 194

off(eventopt, selectoropt, listeneropt) → {Node}

Removes one or more previously attached event listeners. If no event details or listeners are specified, all matching handlers are removed.

Parameters:

Name	Type	Attributes	Description
`event`	{string}	<optional>	the event type name (or space separated names)
`selector`	{string}	<optional>	the CSS selector to match for event target
`listener`	{function}	<optional>	the event handler function (or `false`)

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#off

Source:

rapidcontext/ui/event.mjs, line 77

on(event, selectoropt, listener, optsopt) → {Node}

Attaches a listener function for one or more events.

Parameters:

Name Type Attributes Description

event {string} the event type name (or space separated names)

selector {string} <optional> the CSS selector to match for event target

listener {function} the event handler function (or false)

opts

{Object}

the event listener options (see addEventListener)

Properties

Name	Type	Attributes	Description
`delay`	{number}	<optional>	an inactivity delay before calling listener

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#on

Source:

rapidcontext/ui/event.mjs, line 44

once(event, selectoropt, listener, optsopt) → {Node}

Attaches a single event listener function. The listener will be removed the first time an event is triggered.

Parameters:

Name Type Attributes Description

event {string} the event type name (or space separated names)

selector {string} <optional> the CSS selector to match for event target

listener {function} the event handler function (or false)

opts

{Object}

the event listener options (see addEventListener)

Properties

Name	Type	Attributes	Description
`delay`	{number}	<optional>	an inactivity delay before calling listener

Returns:

{Node} the input DOM node (for chaining calls)

Inherited From:

RapidContext.UI.Event#once

Source:

rapidcontext/ui/event.mjs, line 60

parent() → {Widget}

Returns the parent tree node widget.

Returns:: {Widget} the parent tree node widget, or null if this is a root node
Source:: RapidContext_Widget_TreeNode.js, line 257

path() → {Array}

Returns the path to this tree node.

Returns:: {Array} the tree node path, i.e an array of node names
Source:: RapidContext_Widget_TreeNode.js, line 271

removeAll()

Removes all children to this widget. This method will also destroy and child widgets and disconnect all signal listeners. This method uses the getChildNodes() and removeChildNode() methods to find and remove the individual child nodes.

Inherited From:: RapidContext.Widget#removeAll
Source:: RapidContext_Widget.js, line 543

removeAllMarked()

Removes all marked tree nodes. When adding or updating tree nodes, any node modified is automatically unmarked (e.g. by calling setAttrs). This makes it easy to prune a tree after an update, by initially marking all tree nodes with markAll(), inserting or touching all nodes to keep, and finally calling this method to remove the remaining nodes.

Example:

parent.markAll();
parent.setAttrs();
child.setAttrs();
...
parent.removeAllMarked();

Source:

RapidContext_Widget_TreeNode.js, line 169

removeChildNode(child)

Removes a single child tree node widget from this widget.

Parameters:

Name	Type	Description
`child`	{Widget}	the tree node widget to remove

Overrides:

RapidContext.Widget#removeChildNode

Source:

RapidContext_Widget_TreeNode.js, line 147

removeClass(…cls)

Removes the specified CSS class names from this HTML DOM node. Note that this method will not remove any class starting with "widget".

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Inherited From:

RapidContext.Widget#removeClass

Source:

RapidContext_Widget.js, line 346

select()

Selects this tree node.

Source:: RapidContext_Widget_TreeNode.js, line 321

setAttrs(attrs)

Updates the widget or HTML DOM node attributes.

Parameters:

Name Type Description

attrs

{Object}

the widget and node attributes to set

Properties

Name	Type	Attributes	Description
`name`	{string}	<optional>	the tree node name
`folder`	{boolean}	<optional>	the folder flag, cannot be reverted to `false` once set (implicitly or explicitly)
`icon`	{Icon\|Object\|string}	<optional>	icon the icon to set, or null to remove
`tooltip`	{string}	<optional>	the tooltip text when hovering
`hidden`	{boolean}	<optional>	the hidden widget flag

Overrides:

RapidContext.Widget#setAttrs

Source:

RapidContext_Widget_TreeNode.js, line 110

setStyle(styles)

Updates the CSS styles of this HTML DOM node. This method is identical to MochiKit.Style.setStyle, but uses "this" as the first argument.

Parameters:

Name	Type	Description
`styles`	{Object}	an object with the styles to set

Inherited From:

RapidContext.Widget#setStyle

Example:

widget.setStyle({ "font-size": "bold", "color": "red" });

Source:

RapidContext_Widget.js, line 287

show()

Shows this widget node if it was previously hidden. This method is equivalent to calling setAttrs({ hidden: false }). It is safe for all types of widgets, since it only removes the widgetHidden CSS class instead of setting the display style property.

Inherited From:: RapidContext.Widget#show
Source:: RapidContext_Widget.js, line 452

toggle()

Toggles expand and collapse for this node.

Source:: RapidContext_Widget_TreeNode.js, line 427

toggleClass(…cls) → {boolean}

Toggles adding and removing the specified CSS class names to and from this HTML DOM node. If all the CSS classes are already set, they will be removed. Otherwise they will be added.

Parameters:

Name	Type	Attributes	Description
`cls`	{string\|Array}	<repeatable>	the CSS class names to remove

Returns:

{boolean} true if the CSS classes were added, or false otherwise

Inherited From:

RapidContext.Widget#toggleClass

Source:

RapidContext_Widget.js, line 368

tree() → {Widget}

Returns the ancestor tree widget.

Returns:: {Widget} the ancestor tree widget, or null if none was found
Source:: RapidContext_Widget_TreeNode.js, line 239

uid() → {string}

Returns the unique identifier for this DOM node. If a node id has already been set, that id will be returned. Otherwise a new id will be generated and assigned to the widget DOM node.

Returns:: {string} the the unique DOM node identifier
Inherited From:: RapidContext.Widget#uid
Source:: RapidContext_Widget.js, line 185

unselect()

Unselects this tree node.

Source:: RapidContext_Widget_TreeNode.js, line 333