Class RapidContext.Widget.Tree

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

The tree widget class. Used to provide a dynamic tree with expandable tree nodes, using a number of <div> HTML elements.

Constructor Summary
Creates a new tree widget.
Method Summary
Adds one or more children to this widget.
Adds a single child tree node widget to this widget.
Adds the specified CSS class names to this HTML DOM node.
Adds a path to the tree as a recursive list of child nodes.
Performs a visual effect animation on this widget.
Blurs (unfocuses) this DOM node and all relevant child nodes.
Recursively collapses all nodes.
The internal widget destructor function.
Disables this widget if it was previously enabled.
Enables this widget if it was previously disabled.
Recursively expands all nodes.
Searches for a tree node from the specified path.
Finds a root tree node with the specified name.
Returns an array with all child DOM nodes.
Checks if this HTML DOM node has the specified CSS class names.
Hides this widget node if it was previously visible.
Checks if this widget is disabled.
Checks if this widget node is hidden.
Marks this tree node and all child nodes recursively.
Removes all children to this widget.
Removes all marked tree nodes.
Removes a single child DOM node from this widget.
Removes the specified CSS class names from this HTML DOM node.
Returns the currently selected tree node.
Updates the widget or HTML DOM node attributes.
Updates the CSS styles of this HTML DOM node.
Shows this widget node if it was previously hidden.
Toggles adding and removing the specified CSS class names to and from this HTML DOM node.
Returns the unique identifier for this DOM node.
Event Summary
Emitted when a tree node is collapsed.
Emitted when a tree node is expanded.
Emitted when a tree node is selected.
Emitted when a tree node selection is removed.

Constructor

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

Creates a new tree widget.

Parameters:
Name Type Attributes Description
attrs {Object} the widget and node attributes
Properties
Name Type Attributes Description
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

var tree = RapidContext.Widget.Tree({ style: { width: "200px", height: "400px" } });
var root = RapidContext.Widget.TreeNode({ folder: true, name: "Root" });
var child = RapidContext.Widget.TreeNode({ name: "Child" });
root.addAll(child);
tree.addAll(root);

User Interface XML

<Tree style="width: 200px; height: 400px;">
  <TreeNode name="Root">
    <TreeNode name="Child" />
  </TreeNode>
</Tree>
Source:
RapidContext_Widget_Tree.js, line 49

Extends

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 570

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_Tree.js, line 98

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 333

addPath(path) → {Widget}

Adds a path to the tree as a recursive list of child nodes. If nodes in the specified path already exists, they will be used instead of creating new nodes.

Parameters:
Name Type Description
path {Array} the tree node path (array of names)
Returns:
{Widget} the last node in the path
Source:
RapidContext_Widget_Tree.js, line 264

animate(opts)

Performs a visual effect animation on this widget. This is implemented using the MochiKit.Visual effect package. All options sent to this function will be passed on to the appropriate MochiKit.Visual function.

Parameters:
Name Type Description
opts {Object} the visual effect options
Properties
Name Type Description
effect {string} the MochiKit.Visual effect name
queue {string} the MochiKit.Visual queue handling, defaults to "replace" and a unique scope for each widget (see MochiKit.Visual for full options)
Inherited From:
RapidContext.Widget#animate
Deprecated:
Use CSS animations instead.
Example:
widget.animate({ effect: "fade", duration: 0.5 });
widget.animate({ effect: "Move", transition: "spring", y: 300 });
Source:
RapidContext_Widget.js, line 492

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 510

collapseAll(depthopt)

Recursively collapses all nodes. If a depth is specified, only nodes below that depth will be collapsed.

Parameters:
Name Type Attributes Description
depth {number} <optional>
the optional minimum depth
Source:
RapidContext_Widget_Tree.js, line 245

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 194

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 424

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 416

expandAll(depthopt)

Recursively expands all nodes. 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_Tree.js, line 229

findByPath(path) → {Widget}

Searches for a tree node from the specified path.

Parameters:
Name Type Description
path {Array} the tree node path (array of names)
Returns:
{Widget} the descendant tree node found, or null if not found
Source:
RapidContext_Widget_Tree.js, line 177

findRoot(name) → {Widget}

Finds a root tree node with the specified name.

Parameters:
Name Type Description
name {string} the root tree node name
Returns:
{Widget} the root tree node found, or null if not found
Source:
RapidContext_Widget_Tree.js, line 159

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 522

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 315

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 470

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 395

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 437

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 on the tree nodes or addPath on the tree). 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:
tree.markAll();
tree.addPath(["Root", "Child"]);
...
tree.removeAllMarked();
Source:
RapidContext_Widget_Tree.js, line 144

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 582

removeAllMarked()

Removes all marked tree nodes. When adding or updating tree nodes, any node modified is automatically unmarked (e.g. by calling setAttrs on the tree nodes or addPath on the tree). 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:
tree.markAll();
tree.addPath(["Root", "Child"]);
...
tree.removeAllMarked();
Source:
RapidContext_Widget_Tree.js, line 119

removeChildNode(child)

Removes a single child DOM node from this widget. This method is sometimes overridden by child widgets in order to hide or control intermediate DOM nodes required by the widget.

Note that this method will NOT destroy the removed child widget, so care must be taken to ensure proper child widget destruction.

Parameters:
Name Type Description
child {Widget|Node} the DOM node to remove
Inherited From:
RapidContext.Widget#removeChildNode
Source:
RapidContext_Widget.js, line 553

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 353

selectedChild() → {Widget}

Returns the currently selected tree node.

Returns:
{Widget} the currently selected tree node, or null if no node is selected
Source:
RapidContext_Widget_Tree.js, line 195

setAttrs(attrs)

Updates the widget or HTML DOM node attributes. This method is sometimes overridden by individual widgets to allow modification of additional widget attributes.

Parameters:
Name Type Description
attrs {Object} the widget and node attributes to set
Properties
Name Type Attributes Description
disabled {boolean} <optional>
the disabled widget flag
hidden {boolean} <optional>
the hidden widget flag
class {string} <optional>
the CSS class names
Inherited From:
RapidContext.Widget#setAttrs
Source:
RapidContext_Widget.js, line 246

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 294

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 460

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 376

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 182

Events

oncollapse

Emitted when a tree node is collapsed.

Source:
RapidContext_Widget_Tree.js, line 70

onexpand

Emitted when a tree node is expanded.

Source:
RapidContext_Widget_Tree.js, line 63

onselect

Emitted when a tree node is selected. It will be emitted after "onunselect" if another node was previously selected.

Source:
RapidContext_Widget_Tree.js, line 77

onunselect

Emitted when a tree node selection is removed. It will be emitted before "onselect" if another node was previously selected.

Source:
RapidContext_Widget_Tree.js, line 85