tree_node.h

Go to the documentation of this file.

#ifndef AUBO_SCOPE_TREE_NODE_H
#define AUBO_SCOPE_TREE_NODE_H
 
#include <vector>
#include <functional>
#include <aubo_caps/domain/program/nodes/program_node.h>
 
namespace arcs {
namespace aubo_scope {
ARCS_CLASS_FORWARD(TreeNode);
 
/**
 * \chinese
 * 树节点
 * 此接口表示程序树中的一个节点，可用于构建以 AuboCap 程序节点为根的子树。
 *
 * 使用 {@link ProgramModel#getRootTreeNode(ProgramNodeContribution)} 获取子树
 * 的根节点后，即可添加子节点。每次调用 {@link TreeNode#addChild(ProgramNode)}
 * 都会返回一个新的 {@link TreeNode}，该节点又可以作为另一个子树的根节点。
 * \endchinese
 * \english
 * TreeNode
 * This interface represents a node in the program tree that can be used to
 * construct a sub-tree rooted in a AuboCap program node.
 *
 * Using the {@link ProgramModel#getRootTreeNode(ProgramNodeContribution)} to
 * obtain a root for the sub-tree, it is possible to add children. For each call
 * to {@link TreeNode#addChild(ProgramNode)}, a new {@link TreeNode} is
 * returned, that can, in turn, act as a root for yet another sub-tree.
 * \endenglish
 */
class ARCS_ABI_EXPORT TreeNode
{
public:
    TreeNode(TreeNode &f);
    TreeNode(TreeNode &&f);
    virtual ~TreeNode();
 
    /**
     * \chinese
     * 向子树添加一个子程序节点。
     *
     * @param program_node 使用 ProgramNodeFactory 构建的 ProgramNode
     * @return 返回一个 TreeNode，可用于向新添加的子节点添加子节点。
     * @throws TreeStructureException 如果不允许在此位置插入 ProgramNode
     * @throws IllegalStateException 如果在 UndoableChanges 范围外从基于 Qt 的
     * AuboCap 调用
     * \endchinese
     * \english
     * Add a child program node to the sub-tree.
     *
     * @param program_node the {@link ProgramNode} constructed using the {@link
     * ProgramNodeFactory}
     * @return 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 {@link
     * ProgramNode} at this position a
     * {@link TreeStructureException} will be thrown.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    TreeNodePtr addChild(ProgramNodePtr program_node);
 
    /**
     * \chinese
     * 在子树中，在现有选中子节点之前插入一个子程序节点。将选中子节点及其后的节点
     * 移到新添加子节点之后的位置。
     *
     * @param existingChildNode 此 TreeNode 的现有 TreeNode 子节点
     * @param program_node 使用 ProgramNodeFactory 构建的 ProgramNode
     * @return 返回一个 TreeNode，可用于向新添加的子节点添加子节点。
     * @throws TreeStructureException 如果不允许在此位置插入或选中子节点不是
     * 此 TreeNode 的子节点
     * @throws IllegalStateException 如果在 UndoableChanges 范围外调用
     * \endchinese
     * \english
     * 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.
     *
     * @param existingChildNode existing TreeNode child of this TreeNode.
     * @param program_node the {@link ProgramNode} constructed using the {@link
     * ProgramNodeFactory}.
     * @return 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 {@link
     * ProgramNode} at this position or if the selected child node is not a
     * child of this TreeNode a {@link TreeStructureException} will be thrown.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    TreeNodePtr insertChildBefore(TreeNodePtr existingChildNode,
                                  ProgramNodePtr program_node);
 
    /**
     * \chinese
     * 在子树中，在现有选中子节点之后插入一个子程序节点。将后续节点移到新添加
     * 子节点之后的位置。
     *
     * @param existingChildNode 此 TreeNode 的现有 TreeNode 子节点
     * @param program_node 使用 ProgramNodeFactory 构建的 ProgramNode
     * @return 返回一个 TreeNode，可用于向新添加的子节点添加子节点。
     * @throws TreeStructureException 如果不允许在此位置插入或选中子节点不是
     * 此 TreeNode 的子节点
     * @throws IllegalStateException 如果在 UndoableChanges 范围外调用
     * \endchinese
     * \english
     * 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.
     *
     * @param existingChildNode existing TreeNode child of this TreeNode.
     * @param program_node the {@link ProgramNode} constructed using the {@link
     * ProgramNodeFactory}.
     * @return 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 {@link
     * ProgramNode} at this position or if the selected child node is not a
     * child of this TreeNode a {@link TreeStructureException} will be thrown.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    TreeNodePtr insertChildAfter(TreeNodePtr existingChildNode,
                                 ProgramNodePtr program_node);
 
    /**
     * \chinese
     * 剪切子树中的一个子程序节点。
     *
     * @param child 此 TreeNode 的现有 TreeNode 子节点
     * @return 返回被剪切掉的 TreeNode
     * @throws TreeStructureException 如果不允许剪切此 ProgramNode 或子节点不是
     * 此 TreeNode 的子节点
     * @throws IllegalStateException 如果在 UndoableChanges 范围外调用
     * \endchinese
     * \english
     * Cut 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.
     *
     * @param child existing TreeNode child of this TreeNode.
     * @return Returns the TreeNode that has been cut off.
     * @throws TreeStructureException If it is not allowed to cut the {@link
     * ProgramNode} or if the selected child node is not a child of this
     * TreeNode a {@link TreeStructureException} will be thrown.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    TreeNodePtr cutChildNode(TreeNodePtr child);
 
    /**
     * \chinese
     * 从子树中移除子节点。注意：移除最后一个子节点将触发插入一个
     * {@literal <empty>} 子节点。
     *
     * @param program_node 要移除的 TreeNode 子节点
     * @return 成功移除返回 <code>true</code>，否则返回 <code>false</code>
     * @throws TreeStructureException 如果移除子节点会使树处于非法状态
     * @throws IllegalStateException 如果在 UndoableChanges 范围外调用
     * \endchinese
     * \english
     * Removes a child node from the sub-tree. Be aware that removing the last
     * child will trigger the insertion of an
     * {@literal <empty>} child node.
     *
     * @param program_node The TreeNode child to be removed.
     * @return Returns <code>true</code> if removed successfully.
     * <code>false</code> otherwise.
     * @throws TreeStructureException If the removed child would leave the tree
     * in an illegal state a
     * {@link TreeStructureException} will be thrown.
     * @throws IllegalStateException if called from a Qt-based AuboCap
     * outside of an {@link UndoableChanges} scope (see also {@link
     * UndoRedoManager}).
     * \endenglish
     */
    bool removeChild(TreeNodePtr program_node);
 
    /**
     * \chinese
     * @return TreeNode 对象列表，表示此 TreeNode 的所有子节点（包括以编程方式
     * 添加的和终端用户插入的）
     * \endchinese
     * \english
     * @return a list of <code>TreeNode</code> objects that represents all the
     * children of this <code>TreeNode</code> (both programmatically added as
     * well as inserted by the end user).
     * \endenglish
     */
    std::vector<TreeNodePtr> getChildren();
 
    std::vector<TreeNodePtr> getChildrenNotSuppressed();
 
    /**
     * \chinese
     * @return 节点的父 TreeNode
     * \endchinese
     * \english
     * @return Parent treenode of the node
     * \endenglish
     */
    TreeNodePtr getParent();
 
    /**
     * \chinese
     * @return 返回子树中此位置的 ProgramNode。可以是内置 AuboScope 程序节点
     * 或 AuboCap 程序节点。
     * \endchinese
     * \english
     * @return Returns the {@link ProgramNode} at this position in the sub-tree.
     * Can either be a built-in AuboScope program node (provided by AUBO
     * Robots) or a AuboCap program node.
     * \endenglish
     */
    ProgramNodePtr getProgramNode();
    bool isSuppressed();
 
    /**
     * \chinese
     * 节点是否在程序树中；不在程序树中的节点可能已被剪切或删除。
     *
     * @return <code>true</code> 节点在程序树中，
     * <code>false</code> 节点不在程序树中（可能已被剪切或删除）
     * \endchinese
     * \english
     * Whether the node is in the program tree; nodes not in the program tree
     * may have been cut or deleted.
     *
     * @return Returns <code>true</code> The node is in the program tree.
     * <code>false</code> The node is not in the program tree; such nodes may
     * have been cut or deleted.
     * \endenglish
     */
    bool isInProgramTree();
 
    /**
     * \chinese
     * <p>获取此 TreeNode 下子树中子程序节点（ProgramNode 实例）对应的 TreeNode
     * 实例。</p>
     * 此方法可用于在遍历父节点子树时，获取遇到子程序节点下的子树访问权限。
     *
     * @param program_node 需要获取对应 TreeNode 表示的程序节点，不能为
     * <code>null</code>
     * @return 指定程序节点的 TreeNode 实例
     * @throws ProgramNodeNotInSubTreeException 当程序节点不在子树中时
     * \endchinese
     * \english
     * <p>
     * Gets a corresponding {@link TreeNode} instance for a child program node
     * (a {@link ProgramNode} instance) in the sub-tree under this {@link
     * TreeNode}.
     * </p>
     * 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 {@link ProgramNodeVisitor} (or any derived sub
     * class thereof).
     *
     * @param program_node program node to get a corresponding {@link TreeNode}
     * representation for, not <code>null</code>. Can either be a built-in
     * AuboScope program node (provided by AUBO Robots) or a AuboCap
     * program node.
     * @return the <code>TreeNode</code> instance for the specified program
     * node.
     * @throws ProgramNodeNotInSubTreeException when the program node cannot be
     * found because it is not in the sub-tree.
     * \endenglish
     */
    TreeNodePtr locateDescendantTreeNode(ProgramNodePtr program_node);
 
    /**
     * \chinese
     * 配置子节点是否可被终端用户重新排列、删除或将其他节点插入到子节点序列中。
     *
     * @param isChildSequenceLocked 如果为 <code>true</code>，则此
     * TreeNode 下的直接子节点将被锁定
     * \endchinese
     * \english
     * Configures whether or not child nodes can be rearranged, deleted or have
     * other nodes inserted into the child sequence by the end user.
     *
     * @param isChildSequenceLocked If <code>true</code> then the immediate
     * children under this <code>TreeNode</code> will be locked.
     * \endenglish
     */
    void setChildSequenceLocked(bool isChildSequenceLocked);
 
    /**
     * \chinese
     * <p>此方法以深度优先方式遍历此树节点下的整个子树（对应于程序树中的自顶向下方式）。</p>
     * <p>使用节点访问器进行回调，回调的重载取决于遇到的节点类型。</p>
     * <p>所有 visit 方法都具有程序节点、兄弟索引和深度作为参数，以便在需要时过滤节点。</p>
     *
     * @param nodeVisitor 回调实例
     * @return 0 表示正常退出，非零表示异常或错误导致提前退出
     * \endchinese
     * \english
     * <p>
     * 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).
     * </p>
     * <p>
     * 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.
     * </p>
     * <p>
     * The node visitor can be either a {@link ProgramNodeVisitor}
     * implementation with optional overrides or a
     * {@link ProgramNodeInterfaceVisitor} implementation. In the latter
     * case, the
     * {@link ProgramNodeInterfaceVisitor#visitAs(Object, int, int)}
     * method must be implemented.
     * </p>
     * <p>
     * The {@link ProgramNodeInterfaceVisitor} can be used when targeting
     * AuboCap program nodes implementing the (generic) type parameter specified
     * in {@link ProgramNodeInterfaceVisitor} (see also
     * {@link ProgramNode#getAs(Class)}).
     * </p>
     * Note that this method is sometimes called <code>accept()</code> in the
     * Visitor software design pattern.
     *
     * @param nodeVisitor the instance callbacks are made to.
     * @return 0 for normal exit.
     *         non-zero for exception or error causing premature exit.
     * \endenglish
     */
    int traverse(std::function<int(ProgramNodePtr, int, int)> nodeVisitor);
 
private:
    friend class DataSwitch;
    TreeNode();
    void *d_{ nullptr };
};
 
} // namespace aubo_scope
} // namespace arcs
#endif // AUBO_SCOPE_TREE_NODE_H