com.ur.urcap.api.domain.program.structure

Interface TreeNode

@ProviderType
public interface TreeNode

This interface represents a node in the program tree that can be used to construct a sub-tree rooted in a URCap program node.

Using the ProgramModel.getRootTreeNode(ProgramNodeContribution) to obtain a root for the sub-tree, it is possible to add children. For each call to addChild(ProgramNode), a new TreeNode is returned, that can, in turn, act as a root for yet another sub-tree.

Method Summary

Modifier and Type	Method and Description
TreeNode	addChild(ProgramNode programNode) Add a child program node to the sub-tree.
List<TreeNode>	getChildren()
ProgramNode	getProgramNode()
TreeNode	insertChildAfter(TreeNode existingChildNode, ProgramNode programNode) Inserts a child program node under in the sub-tree directly after the existing selected child node.
TreeNode	insertChildBefore(TreeNode existingChildNode, ProgramNode programNode) Inserts a child program node in the sub-tree directly before the existing selected child node.
TreeNode	locateDescendantTreeNode(ProgramNode programNode) Gets a corresponding TreeNode instance for a child program node (a ProgramNode instance) in the sub-tree under this TreeNode.
boolean	removeChild(TreeNode child) Removes a child node from the sub-tree.
TreeNode	setChildSequenceLocked(boolean isChildSequenceLocked) Configures whether or not child nodes can be rearranged, deleted or have other nodes inserted into the child sequence by the end user.
void	traverse(ProgramNodeVisitor nodeVisitor) This method traverses the entire sub-tree under this tree node in a depth-first fashion (this corresponds to a top-down approach in the program tree).

Method Detail

addChild

TreeNode addChild(ProgramNode programNode)
           throws TreeStructureException

Add a child program node to the sub-tree.

Parameters:

programNode - the ProgramNode constructed using the ProgramNodeFactory

Returns:

Returns a TreeNode that can be used to add children to the newly added child.

Throws:

TreeStructureException - If it is not allowed to insert the ProgramNode at this position a TreeStructureException will be thrown.

IllegalStateException - if called from a Swing-based URCap outside of an UndoableChanges scope (see also UndoRedoManager).

insertChildBefore

TreeNode insertChildBefore(TreeNode existingChildNode,
                           ProgramNode programNode)
                    throws TreeStructureException

Inserts a child program node in the sub-tree directly before the existing selected child node. Shifts the selected child node and any subsequent nodes to positions after the newly added child.

Parameters:

existingChildNode - existing TreeNode child of this TreeNode.

programNode - the ProgramNode constructed using the ProgramNodeFactory.

Returns:

Returns a TreeNode that can be used to add children to the newly added child.

Throws:

TreeStructureException - If it is not allowed to insert the ProgramNode at this position or if the selected child node is not a child of this TreeNode a TreeStructureException will be thrown.

IllegalStateException - if called from a Swing-based URCap outside of an UndoableChanges scope (see also UndoRedoManager).

insertChildAfter

TreeNode insertChildAfter(TreeNode existingChildNode,
                          ProgramNode programNode)
                   throws TreeStructureException

Inserts a child program node under in the sub-tree directly after the existing selected child node. Shifts any subsequent nodes to positions after the newly added child.

Parameters:

existingChildNode - existing TreeNode child of this TreeNode.

programNode - the ProgramNode constructed using the ProgramNodeFactory.

Returns:

Returns a TreeNode that can be used to add children to the newly added child.

Throws:

TreeStructureException - If it is not allowed to insert the ProgramNode at this position or if the selected child node is not a child of this TreeNode a TreeStructureException will be thrown.

IllegalStateException - if called from a Swing-based URCap outside of an UndoableChanges scope (see also UndoRedoManager).

removeChild

boolean removeChild(TreeNode child)
             throws TreeStructureException

Removes a child node from the sub-tree. Be aware that removing the last child will trigger the insertion of an <empty> child node.

Parameters:

child - The TreeNode child to be removed.

Returns:

Returns true if removed successfully. false otherwise.

Throws:

TreeStructureException - If the removed child would leave the tree in an illegal state a TreeStructureException will be thrown.

IllegalStateException - if called from a Swing-based URCap outside of an UndoableChanges scope (see also UndoRedoManager).

getChildren

List<TreeNode> getChildren()

Returns:

a list of TreeNode objects that represents all the children of this TreeNode (both programmatically added as well as inserted by the end user).

getProgramNode

ProgramNode getProgramNode()

Returns:

Returns the ProgramNode at this position in the sub-tree. Can either be a built-in PolyScope program node (provided by Universal Robots) or a URCap program node.

locateDescendantTreeNode

TreeNode locateDescendantTreeNode(ProgramNode programNode)

Gets a corresponding TreeNode instance for a child program node (a ProgramNode instance) in the sub-tree under this TreeNode.

This method can for instance be used to gain access to the sub-tree under a child program node encountered when iterating the sub-tree of the parent node using the ProgramNodeVisitor (or any derived sub class thereof).

Parameters:

programNode - program node to get a corresponding TreeNode representation for, not null. Can either be a built-in PolyScope program node (provided by Universal Robots) or a URCap program node.

Returns:

the TreeNode instance for the specified program node.

Throws:

ProgramNodeNotInSubTreeException - when the program node cannot be found because it is not in the sub-tree.

setChildSequenceLocked

TreeNode setChildSequenceLocked(boolean isChildSequenceLocked)

Configures whether or not child nodes can be rearranged, deleted or have other nodes inserted into the child sequence by the end user.

Parameters:

isChildSequenceLocked - If true then the immediate children under this TreeNode will be locked.

Returns:

The same TreeNode.

traverse

void traverse(ProgramNodeVisitor nodeVisitor)

This method traverses the entire sub-tree under this tree node in a depth-first fashion (this corresponds to a top-down approach in the program tree).

A node visitor is used for callbacks to the visit-overloads you choose to override. The overload called depends on the node type encountered. Override the overloads for the node types you are concerned with. All visit-methods have the program node, sibling index and depth as arguments to help filter nodes if needed.

The node visitor can be either a ProgramNodeVisitor implementation with optional overrides or a URCapProgramNodeInterfaceVisitor implementation. In the latter case, the URCapProgramNodeInterfaceVisitor.visitURCapAs(Object, int, int) method must be implemented.

The URCapProgramNodeInterfaceVisitor can be used when targeting URCap program nodes implementing the (generic) type parameter specified in URCapProgramNodeInterfaceVisitor (see also URCapProgramNode.getAs(Class)).

Note that this method is sometimes called accept() in the Visitor software design pattern.

Parameters:

nodeVisitor - the instance callbacks are made to.