AuboStudio SDK 0.6.3

tree_node.h
浏览该文件的文档.
1 #ifndef AUBO_SCOPE_TREE_NODE_H
2 #define AUBO_SCOPE_TREE_NODE_H
3
4 #include <vector>
5 #include <functional>
6 #include <aubo_caps/domain/program/nodes/program_node.h>
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 */
23 class ARCS_ABI_EXPORT TreeNode
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 * Cut a child program node under in the sub-tree directly after the
88 * existing selected child node. Shifts any subsequent nodes to positions
89 * after the newly added child.
90 *
91 * @param child existing TreeNode child of this TreeNode.
92
93 * @return Returns the TreeNode that has been cut off.
94 * @throws TreeStructureException If it is not allowed to cut the {@link
95 * ProgramNode} or if the selected child node is not a child of this
96 * TreeNode
97 * a {@link TreeStructureException} will be thrown.
98 * @throws IllegalStateException if called from a Swing-based AuboCap
99 * outside of an {@link UndoableChanges} scope (see also {@link
100 * UndoRedoManager}).
101 */
102 TreeNodePtr cutChildNode(TreeNodePtr child);
103
104 /**
105 * Removes a child node from the sub-tree. Be aware that removing the last
106 * child will trigger the insertion of an
107 * {@literal <empty>} child node.
108 *
109 * @param child The TreeNode child to be removed.
110 * @return Returns <code>true</code> if removed successfully.
111 * <code>false</code> otherwise.
112 * @throws TreeStructureException If the removed child would leave the tree
113 * in an illegal state a
114 * {@link TreeStructureException} will be thrown.
115 * @throws IllegalStateException if called from a Swing-based AuboCap
116 * outside of an {@link UndoableChanges} scope (see also {@link
117 * UndoRedoManager}).
118 */
119 bool removeChild(TreeNodePtr program_node);
120
121 /**
122 * @return a list of <code>TreeNode</code> objects that represents all the
123 * children of this <code>TreeNode</code> (both programmatically added as
124 * well as inserted by the end user).
125 */
126 std::vector<TreeNodePtr> getChildren();
127
128 std::vector<TreeNodePtr> getChildrenNotSuppressed();
129
130 /**
131 * @return Parent treenode of the node
132 */
133 TreeNodePtr getParent();
134
135 /**
136 * @return Returns the {@link ProgramNode} at this position in the sub-tree.
137 * Can either be a built-in AuboScope program node (provided by AUBO
138 * Robots) or a AuboCap program node.
139 */
140 ProgramNodePtr getProgramNode();
141 bool isSuppressed();
142
143 /**
144 * Whether the node is in the program tree; nodes not in the program tree
145 * may have been cut or deleted.
146 *
147 * @return Returns <code>true</code> The node is in the program tree.
148 * <code>false</code> The node is not in the program tree; such nodes may
149 * have been cut or deleted.
150 */
151 bool isInProgramTree();
152
153 /**
154 * <p>
155 * Gets a corresponding {@link TreeNode} instance for a child program node
156 * (a {@link ProgramNode} instance) in the sub-tree under this {@link
157 * TreeNode}.
158 * </p>
159 *
160 * This method can for instance be used to gain access to the sub-tree under
161 * a child program node encountered when iterating the sub-tree of the
162 * parent node using the {@link ProgramNodeVisitor} (or any derived sub
163 * class thereof).
164 *
165 * @param programNode program node to get a corresponding {@link TreeNode}
166 * representation for, not <code>null</code>. Can either be a built-in
167 * AuboScope program node (provided by Universal Robots) or a AuboCap
168 * program node.
169 * @return the <code>TreeNode</code> instance for the specified program
170 * node.
171 * @throws ProgramNodeNotInSubTreeException when the program node cannot be
172 * found because it is not in the sub-tree.
173 */
174 TreeNodePtr locateDescendantTreeNode(ProgramNodePtr program_node);
175
176 /**
177 * Configures whether or not child nodes can be rearranged, deleted or have
178 * other nodes inserted into the child sequence by the end user.
179 *
180 * @param isChildSequenceLocked If <code>true</code> then the immediate
181 * children under this <code>TreeNode</code> will be locked.
182 */
183 void setChildSequenceLocked(bool isChildSequenceLocked);
184
185 /**
186 * <p>
187 * This method traverses the entire sub-tree under this tree node in a
188 * depth-first fashion (this corresponds to a top-down approach in the
189 * program tree).
190 * </p>
191 *
192 * <p>
193 * A node visitor is used for callbacks to the visit-overloads you choose to
194 * override. The overload called depends on the node type encountered.
195 * Override the overloads for the node types you are concerned with. All
196 * visit-methods have the program node, sibling index and depth as arguments
197 * to help filter nodes if needed.
198 * </p>
199 *
200 * <p>
201 * The node visitor can be either a {@link ProgramNodeVisitor}
202 * implementation with optional overrides or a
203 * {@link ProgramNodeInterfaceVisitor} implementation. In the latter
204 * case, the
205 * {@link ProgramNodeInterfaceVisitor#visitAs(Object, int, int)}
206 * method must be implemented.
207 * </p>
208 *
209 * <p>
210 * The {@link ProgramNodeInterfaceVisitor} can be used when targeting
211 * AuboCap program nodes implementing the (generic) type parameter specified
212 * in {@link ProgramNodeInterfaceVisitor} (see also
213 * {@link ProgramNode#getAs(Class)}).
214 * </p>
215 *
216 * Note that this method is sometimes called <code>accept()</code> in the
217 * Visitor software design pattern.
218 *
219 * @param nodeVisitor the instance callbacks are made to.
220 *
221 * @return 0 for normal exit.
222 * non-zero for exception or error causing premature exit.
223 */
224 int traverse(std::function<int(ProgramNodePtr, int, int)> nodeVisitor);
225
226 private:
227 friend class DataSwitch;
228 TreeNode();
229 void *d_{ nullptr };
230 };
231
232 } // namespace aubo_scope
233 } // namespace arcs
234 #endif // AUBO_SCOPE_TREE_NODE_H
ARCS_ABI_EXPORT
#define ARCS_ABI_EXPORT
Definition: class_forward.h:16
arcs::aubo_scope::TreeNode
Definition: tree_node.h:24
arcs::aubo_scope::TreeNode::~TreeNode
virtual ~TreeNode()
arcs::aubo_scope::TreeNode::getChildren
std::vector< TreeNodePtr > getChildren()
arcs::aubo_scope::TreeNode::TreeNode
TreeNode(TreeNode &f)
arcs::aubo_scope::TreeNode::getParent
TreeNodePtr getParent()
arcs::aubo_scope::TreeNode::TreeNode
TreeNode()
arcs::aubo_scope::TreeNode::traverse
int traverse(std::function< int(ProgramNodePtr, int, int)> nodeVisitor)
arcs::aubo_scope::TreeNode::TreeNode
TreeNode(TreeNode &&f)
arcs::aubo_scope::TreeNode::getChildrenNotSuppressed
std::vector< TreeNodePtr > getChildrenNotSuppressed()
arcs::aubo_scope::TreeNode::addChild
TreeNodePtr addChild(ProgramNodePtr program_node)
Add a child program node to the sub-tree.
arcs::aubo_scope::TreeNode::insertChildBefore
TreeNodePtr insertChildBefore(TreeNodePtr existingChildNode, ProgramNodePtr program_node)
Inserts a child program node in the sub-tree directly before the existing selected child node.
arcs::aubo_scope::TreeNode::isInProgramTree
bool isInProgramTree()
Whether the node is in the program tree; nodes not in the program tree may have been cut or deleted.
arcs::aubo_scope::TreeNode::isSuppressed
bool isSuppressed()
arcs::aubo_scope::TreeNode::setChildSequenceLocked
void setChildSequenceLocked(bool isChildSequenceLocked)
Configures whether or not child nodes can be rearranged, deleted or have other nodes inserted into th...
arcs::aubo_scope::TreeNode::insertChildAfter
TreeNodePtr insertChildAfter(TreeNodePtr existingChildNode, ProgramNodePtr program_node)
Inserts a child program node under in the sub-tree directly after the existing selected child node.
arcs::aubo_scope::TreeNode::getProgramNode
ProgramNodePtr getProgramNode()
arcs::aubo_scope::TreeNode::locateDescendantTreeNode
TreeNodePtr locateDescendantTreeNode(ProgramNodePtr program_node)
arcs::aubo_scope::TreeNode::removeChild
bool removeChild(TreeNodePtr program_node)
Removes a child node from the sub-tree.
arcs::aubo_scope::TreeNode::cutChildNode
TreeNodePtr cutChildNode(TreeNodePtr child)
Cut a child program node under in the sub-tree directly after the existing selected child node.
arcs::aubo_scope::ARCS_CLASS_FORWARD
ARCS_CLASS_FORWARD(GripForceCapability)
arcs
Definition: contribution_provider.h:7
program_node.h