AuboCaps  0.5.0
tree_node.h
Go to the documentation of this file.
1 #ifndef AUBO_SCOPE_TREE_NODE_H
2 #define AUBO_SCOPE_TREE_NODE_H
3 
4 #include <vector>
5 #include <functional>
7 
8 namespace arcs {
9 namespace aubo_scope {
10 ARCS_CLASS_FORWARD(TreeNode);
11 
12 /**
13  * <p>
14  * This interface represents a node in the program tree that can be used to
15  * construct a sub-tree rooted in a AuboCap program node.
16  * </p>
17  *
18  * Using the {@link ProgramModel#getRootTreeNode(ProgramNodeContribution)} to
19  * obtain a root for the sub-tree, it is possible to add children. For each call
20  * to {@link TreeNode#addChild(ProgramNode)}, a new {@link TreeNode} is
21  * returned, that can, in turn, act as a root for yet another sub-tree.
22  */
24 {
25 public:
26  TreeNode(TreeNode &f);
27  TreeNode(TreeNode &&f);
28  virtual ~TreeNode();
29 
30  /**
31  * Add a child program node to the sub-tree.
32  *
33  * @param programNode the {@link ProgramNode} constructed using the {@link
34  * ProgramNodeFactory}
35  * @return Returns a TreeNode that can be used to add children to the newly
36  * added child.
37  * @throws TreeStructureException If it is not allowed to insert the {@link
38  * ProgramNode} at this position a
39  * {@link TreeStructureException} will be thrown.
40  * @throws IllegalStateException if called from a Swing-based AuboCap
41  * outside of an {@link UndoableChanges} scope (see also {@link
42  * UndoRedoManager}).
43  */
44  TreeNodePtr addChild(ProgramNodePtr program_node);
45 
46  /**
47  * Inserts a child program node in the sub-tree directly before the existing
48  * selected child node. Shifts the selected child node and any subsequent
49  * nodes to positions after the newly added child.
50  *
51  * @param existingChildNode existing TreeNode child of this TreeNode.
52  * @param programNode the {@link ProgramNode} constructed using the {@link
53  * ProgramNodeFactory}.
54  * @return Returns a TreeNode that can be used to add children to the newly
55  * added child.
56  * @throws TreeStructureException If it is not allowed to insert the {@link
57  * ProgramNode} at this position or if the selected child node is not a
58  * child of this TreeNode a {@link TreeStructureException} will be thrown.
59  * @throws IllegalStateException if called from a Swing-based AuboCap
60  * outside of an {@link UndoableChanges} scope (see also {@link
61  * UndoRedoManager}).
62  */
63  TreeNodePtr insertChildBefore(TreeNodePtr existingChildNode,
64  ProgramNodePtr program_node);
65 
66  /**
67  * Inserts a child program node under in the sub-tree directly after the
68  * existing selected child node. Shifts any subsequent nodes to positions
69  * after the newly added child.
70  *
71  * @param existingChildNode existing TreeNode child of this TreeNode.
72  * @param programNode the {@link ProgramNode} constructed using the {@link
73  * ProgramNodeFactory}.
74  * @return Returns a TreeNode that can be used to add children to the newly
75  * added child.
76  * @throws TreeStructureException If it is not allowed to insert the {@link
77  * ProgramNode} at this position or if the selected child node is not a
78  * child of this TreeNode a {@link TreeStructureException} will be thrown.
79  * @throws IllegalStateException if called from a Swing-based AuboCap
80  * outside of an {@link UndoableChanges} scope (see also {@link
81  * UndoRedoManager}).
82  */
83  TreeNodePtr insertChildAfter(TreeNodePtr existingChildNode,
84  ProgramNodePtr program_node);
85 
86  /**
87  * Removes a child node from the sub-tree. Be aware that removing the last
88  * child will trigger the insertion of an
89  * {@literal <empty>} child node.
90  *
91  * @param child The TreeNode child to be removed.
92  * @return Returns <code>true</code> if removed successfully.
93  * <code>false</code> otherwise.
94  * @throws TreeStructureException If the removed child would leave the tree
95  * in an illegal state a
96  * {@link TreeStructureException} will be thrown.
97  * @throws IllegalStateException if called from a Swing-based AuboCap
98  * outside of an {@link UndoableChanges} scope (see also {@link
99  * UndoRedoManager}).
100  */
101  bool removeChild(TreeNodePtr program_node);
102 
103  /**
104  * @return a list of <code>TreeNode</code> objects that represents all the
105  * children of this <code>TreeNode</code> (both programmatically added as
106  * well as inserted by the end user).
107  */
108  std::vector<TreeNodePtr> getChildren();
109 
110  /**
111  * @return Parent treenode of the node
112  */
113  TreeNodePtr getParent();
114 
115  /**
116  * @return Returns the {@link ProgramNode} at this position in the sub-tree.
117  * Can either be a built-in AuboScope program node (provided by AUBO
118  * Robots) or a AuboCap program node.
119  */
120  ProgramNodePtr getProgramNode();
121 
122  /**
123  * <p>
124  * Gets a corresponding {@link TreeNode} instance for a child program node
125  * (a {@link ProgramNode} instance) in the sub-tree under this {@link
126  * TreeNode}.
127  * </p>
128  *
129  * This method can for instance be used to gain access to the sub-tree under
130  * a child program node encountered when iterating the sub-tree of the
131  * parent node using the {@link ProgramNodeVisitor} (or any derived sub
132  * class thereof).
133  *
134  * @param programNode program node to get a corresponding {@link TreeNode}
135  * representation for, not <code>null</code>. Can either be a built-in
136  * AuboScope program node (provided by Universal Robots) or a AuboCap
137  * program node.
138  * @return the <code>TreeNode</code> instance for the specified program
139  * node.
140  * @throws ProgramNodeNotInSubTreeException when the program node cannot be
141  * found because it is not in the sub-tree.
142  */
143  TreeNodePtr locateDescendantTreeNode(ProgramNodePtr program_node);
144 
145  /**
146  * Configures whether or not child nodes can be rearranged, deleted or have
147  * other nodes inserted into the child sequence by the end user.
148  *
149  * @param isChildSequenceLocked If <code>true</code> then the immediate
150  * children under this <code>TreeNode</code> will be locked.
151  */
152  void setChildSequenceLocked(bool isChildSequenceLocked);
153 
154  /**
155  * <p>
156  * This method traverses the entire sub-tree under this tree node in a
157  * depth-first fashion (this corresponds to a top-down approach in the
158  * program tree).
159  * </p>
160  *
161  * <p>
162  * A node visitor is used for callbacks to the visit-overloads you choose to
163  * override. The overload called depends on the node type encountered.
164  * Override the overloads for the node types you are concerned with. All
165  * visit-methods have the program node, sibling index and depth as arguments
166  * to help filter nodes if needed.
167  * </p>
168  *
169  * <p>
170  * The node visitor can be either a {@link ProgramNodeVisitor}
171  * implementation with optional overrides or a
172  * {@link ProgramNodeInterfaceVisitor} implementation. In the latter
173  * case, the
174  * {@link ProgramNodeInterfaceVisitor#visitURCapAs(Object, int, int)}
175  * method must be implemented.
176  * </p>
177  *
178  * <p>
179  * The {@link ProgramNodeInterfaceVisitor} can be used when targeting
180  * AuboCap program nodes implementing the (generic) type parameter specified
181  * in {@link ProgramNodeInterfaceVisitor} (see also
182  * {@link ProgramNode#getAs(Class)}).
183  * </p>
184  *
185  * Note that this method is sometimes called <code>accept()</code> in the
186  * Visitor software design pattern.
187  *
188  * @param nodeVisitor the instance callbacks are made to.
189  */
190  int traverse(std::function<int(ProgramNodePtr, int, int)> nodeVisitor);
191 
192 private:
193  friend class DataSwitch;
194  TreeNode();
195  void *d_{ nullptr };
196 };
197 
198 } // namespace aubo_scope
199 } // namespace arcs
200 #endif // AUBO_SCOPE_TREE_NODE_H
ARCS_CLASS_FORWARD(GripForceCapability)
#define ARCS_ABI_EXPORT
Definition: class_forward.h:16