TreeNode
According to Wikipedia a “tree” is a widely used abstract data type that simulates a hierarchical tree structure, with a root value and subtrees of children with a parent node, represented as a set of linked nodes. A TreeNode is one element in the chain of nodes that make up a tree.
Some of the terms used by both the TreeNode and Item classes incorporate terms that define hierarchical human relationships mixed with those terms defining the elements of actual trees. Here is a list of common terms used by both classes:
Root • The top node in a tree.
Child • A node directly connected to another node when moving away from the Root.
Parent • The converse notion of a child.
Siblings • A group of nodes with the same parent.
Descendant • A node reachable by repeated proceeding from parent to child.
Ancestor • A node reachable by repeated proceeding from child to parent.
Leaf • A node with no children.
However, in terms of Omni Automation and OmniOutliner, a TreeNode represents a row in an OmniOutliner outline document. The following documentation describes the properties and functions of the TreeNode class.
TreeNode Properties
Here are the properties of an instance of the TreeNode class:
canCollapse (boolean r/o) • Returns true if this TreeNode can be collapsed.
canExpand (boolean r/o) • Returns true if this TreeNode can be expanded.
children (TreeNodes r/o) • Returns the array of children that are visible under this node, according to any filtering that is being done, and in the order specified by any sorting rules that have been established.
index (Number r/o) • Returns the index of this TreeNode among its siblings, or zero for the rootNode.
isExpanded (boolean r/o) • Returns true if this TreeNode is currently expanded.
isNoteExpanded (boolean r/o) • Returns true if the note of this TreeNode is currently expanded.
isRevealed (boolean r/o) • Returns true if the TreeNode is the rootNode or all of its ancestor nodes are expanded.
isRootNode (boolean r/o) • Returns true if this node is the rootNode of its tree.
isSelectable (boolean r/o) • Returns true if this TreeNode can be selected. The rootNode cannot be selected, nor can nodes that aren’t revealed.
isSelected (boolean) • Set to true if this TreeNode is in the list of selected nodes for its tree. Attempting to set this to true will do nothing if the node is not revealed (or is the root node).
level (Number r/o) • Returns the nesting level of the TreeNode, relative to the root of the tree. The rootNode of an Outline has level zero, its children have level one, and so on. Note that if only a portion of the model is being shown, this level may not match the level of the underlying object.
object (Object r/o) • The model object (Item) which this node wraps.
parent (TreeNode or nil r/o) • Returns the TreeNode that contains this node, or null if this is the rootNode.
rootNode (TreeNode r/o) • Returns the root TreeNode for the tree that this node belongs to.
TreeNode Functions
Here are the methods used with an instance of the TreeNode class:
expand(completely:Boolean or nil) • Attempts to expand the TreeNode. If the value of the completely parameter is true, then all the child nodes will be expanded as they allow.
collapse(completely:Boolean or nil) • Attempts to collapse the TreeNode. If completely is passed, all the child nodes will be collapse as they allow.
expandNote(completely:Boolean or nil) • Attempts to expand the inline note of the TreeNode. If completely is passed, all the child node notes will be expanded.
collapseNote(completely:Boolean or nil) • Attempts to collapse the inline note of the TreeNode. If completely is passed, all the child node notes will be collapsed.
nodeForObject(object:Object) (TreeNode or null) • Returns the TreeNode that represents the object in this Tree, or null if it cannot be found (possibly filtered out).
nodesForObjects(object:Array of Object) (Array of TreeNode) • Returns an array of TreeNodes for the objects that are currently in the Tree, according to the same filters as nodeForObject(). The size of the resulting node array may be smaller (even empty) than the passed in objects array.
reveal() • Expands all the ancestors
apply(Function) • Calls the supplied function for each TreeNode in the receiver (including the receiver), passing that node as the single argument.
Here’s how to convert an item (row) reference into a node reference:
Node for Item | ||
01 | var row = rootItem.children[0] | |
02 | var editor = document.editors[0] | |
03 | var node = editor.nodeForObject(row) |
Here are two scripts that use the rootNode property of the Editor class to expand or collapse the top-level items in an outline:
Expand Top-Level Items | ||
01 | var editor = document.editors[0] | |
02 | editor.rootNode.children.forEach(function(node){ | |
03 | if(node.canExpand){node.expand()} | |
04 | }) |
Collapse Top-Level Items | ||
01 | var editor = document.editors[0] | |
02 | editor.rootNode.children.forEach(function(node){ | |
03 | if(node.canCollapse){node.collapse()} | |
04 | }) |
To completely expand the top-level items, including their children, pass a boolean value of true into the expand() function:
Expand Top-Level Items | ||
01 | var editor = document.editors[0] | |
02 | editor.rootNode.children.forEach(function(node){ | |
03 | if(node.canExpand){node.expand(true)} | |
04 | }) |
ItemTreeNode
An ItemTreeNode is an instance of the TreeNode class. The ItemTreeNode class is designed to serve as an mechanism for retrieving and setting the values for the state property and the contents of columns, providing parity with the functionality of the Item class.
Here are the properties of an instance of the ItemTreeNode class:
state (State or nil) • The computed status value for this node (which maps to the Outline’s statusColumn). Setting the state on a parent node will propagate the state down to the children, skipping any children that have their state disabled by having a null applied locally.
The properties of the State class are used as the value for the state property of the ItemTreeNode class:
Checked • The checkbox value is checked.
Mixed • The checkbox value has a mixed state, due to child items having a combination of Checked and Unchecked states.
Unchecked • The checkbox value is not checked.
State of Selected Item | ||
01 | var node = document.editors[0].selectedNodes[0] | |
02 | if(node.state == State.Checked){ | |
03 | var message = "Selected row status is checked." | |
04 | } else if (node.state == State.Mixed){ | |
05 | var message = "Selected row status is mixed." | |
06 | } else { | |
07 | var message = "Selected row status is unchecked." | |
08 | } | |
09 | new Alert('STATUS',message).show() |
Here are the methods used with an instance of the ItemTreeNode class:
setValueForColumn(value:Object or nil, column:Column) • This method is used to set the value of the specified column to the provided value.
valueForColumn(column:Column) --> Object or nil • This method is used to get the value of the specified column.
An example script using the Editor’s selection property to get the topic text of the first selected node:
Get Topic for Selected Node | ||
01 | var editor = document.editors[0] | |
02 | var topicColumn = document.outline.outlineColumn | |
03 | var node = editor.selection.nodes[0] | |
04 | if(node){ | |
05 | var topic = node.valueForColumn(topicColumn) | |
06 | var topicStr = (topic === null) ? '':topic.string | |
07 | console.log(topicStr) | |
08 | } |
An example script using the Editor’s selectedNodes property to get the topic text of the first selected node:
Get Topic for Selected Node | ||
01 | var editor = document.editors[0] | |
02 | var topicColumn = document.outline.outlineColumn | |
03 | var node = editor.selectedNodes[0] | |
04 | if(node){ | |
05 | var topic = node.valueForColumn(topicColumn) | |
06 | var topicStr = (topic === null) ? '':topic.string | |
07 | console.log(topicStr) | |
08 | } |
An example script for appending to the note of the first selected node:
Append to Note of Selected Row | ||
01 | var editor = document.editors[0] | |
02 | var notesColumn = document.outline.noteColumn | |
03 | var node = editor.selection.nodes[0] | |
04 | if(node){ | |
05 | var note = node.valueForColumn(notesColumn) | |
06 | if (note === null){ | |
07 | var newNote = "How now brown cow." | |
08 | } else { | |
09 | var newNote = note.string + " " + "How now brown cow." | |
10 | } | |
11 | node.setValueForColumn(newNote, notesColumn) | |
12 | } |
This webpage is in the process of being developed. Any content may change and may not be accurate or complete at this time.