1SoPath(3IV)() SoPath(3IV)()
2
6 SoPath — path that points to a list of hierarchical nodes
7
9 SoBase > SoPath
10
12 #include <Inventor/SoPath.h>
13 Methods from class SoPath:
15 SoPath()
17 SoPath(int approxLength)
18 SoPath(SoNode *node)
19 void setHead(SoNode *node)
20 void append(int childIndex)
21 void append(SoNode *childNode)
22 void append(const SoPath *fromPath)
23 void push(int childIndex)
24 void pop()
25 SoNode * getHead() const
26 SoNode * getTail() const
27 SoNode * getNode(int i) const
28 int getIndex(int i) const
29 SoNode * getNodeFromTail(int i) const
30 int getIndexFromTail(int i) const
31 int getLength() const
32 void truncate(int start)
33 SbBool containsNode(const SoNode *node) const
34 SbBool containsPath(const SoPath *path) const
35 int findFork(const SoPath *path) const
36 SoPath * copy(int startFromNodeIndex = 0, int numNodes = 0)
37 const
38 friend int operator ==(const SoPath &p1, const SoPath &p2)
39 static SoPath * getByName(const SbName &name)
40 static int getByName(const SbName &name, SoPathList &list)
41 Methods from class SoBase:
43 void ref()
45 void unref() const
46 void unrefNoDelete() const
47 void touch()
48 static SoType getClassTypeId()
49 virtual SoType getTypeId() const
50 SbBool isOfType(SoType type) const
51 virtual void setName(const SbName &name)
52 virtual SbName getName() const
53
56 A path represents a scene graph or subgraph. It contains a list of
57 pointers to nodes forming a chain from some root to some descendent.
58 Each node in the chain is a child of the previous node. Paths are used
59 to refer to some object in a scene graph precisely and unambiguously,
60 even if there are many instances of the object. Therefore, paths are
61 returned by both the SoRayPickAction and SoSearchAction.
62 When an action is applied to a path, only the nodes in the subgraph
64 defined by the path are traversed. These include: the nodes in the path
65 chain, all nodes (if any) below the last node in the path, and all
66 nodes whose effects are inherited by any of these nodes.
67 SoPath attempts to maintain consistency of paths even when the struc‐
69 ture of the scene graph changes. For example, removing a child from its
70 parent when both are in a path chain cuts the path chain at that point,
71 leaving the top part intact. Removing the node to the left of a node in
72 a path adjusts the index for that node. Replacing a child of a node
73 when both the parent and the child are in the chain replaces the child
74 in the chain with the new child, truncating the path below the new
75 child.
76 Note that only public children of nodes are accessible from an SoPath.
78 Nodes like node kits that limit access to their children may provide
79 other ways to get more information, such as by using the SoNodeKitPath
80 class.
81
83 SoPath()
84 Constructs an empty path.
85 SoPath(int approxLength)
87 Constructs a path with a hint to length (number of nodes in chain).
88 SoPath(SoNode *node)
90 Constructs a path and sets the head node to the given node.
91 void setHead(SoNode *node)
93 Sets head node (first node in chain). The head node must be set
94 before the append() or push() methods may be called.
95 void append(int childIndex)
97 Adds node to end of chain; the node is the childIndex'th child of
98 the current tail node.
99 void append(SoNode *childNode)
101 Adds node to end of chain; uses the first occurrence of childNode as
102 child of current tail node. If the path is empty, this is equivalent
103 to setHead(childNode).
104 void append(const SoPath *fromPath)
106 Adds all nodes in fromPath's chain to end of chain; the head node of
107 fromPath must be the same as or a child of the current tail node.
108 void push(int childIndex)
110 void pop()
111 These allow a path to be treated as a stack; they push a node at the
112 end of the chain and pop the last node off.
113 SoNode * getHead() const
115 SoNode * getTail() const
116 These return the first and last nodes in a path chain.
117 SoNode * getNode(int i) const
119 int getIndex(int i) const
120 These return a pointer to the i'th node or the index of the i'th
121 node (within its parent) in the chain. Calling getNode(0) is equiva‐
122 lent to calling getHead().
123 SoNode * getNodeFromTail(int i) const
125 int getIndexFromTail(int i) const
126 These return a pointer to the i'th node or the index of the i'th
127 node (within its parent) in the chain, counting backward from the
128 tail node. Passing 0 for i returns the tail node or its index.
129 int getLength() const
131 Returns length of path chain (number of nodes).
132 void truncate(int start)
134 Truncates the path chain, removing all nodes from index start on.
135 Calling truncate(0) empties the path entirely.
136 SbBool containsNode(const SoNode *node) const
138 Returns TRUE if the node is found anywhere in the path chain.
139 SbBool containsPath(const SoPath *path) const
141 Returns TRUE if the nodes in the chain in the passed path are con‐
142 tained (in consecutive order) in this path chain.
143 int findFork(const SoPath *path) const
145 If the two paths have different head nodes, this returns -1. Other‐
146 wise, it returns the path chain index of the last node (starting at
147 the head) that is the same for both paths.
148 SoPath * copy(int startFromNodeIndex = 0, int numNodes = 0)
150 const
151 Creates and returns a new path that is a copy of some or all of this
152 path. Copying starts at the given index (default is 0, which is the
153 head node). A numNodes of 0 (the default) means copy all nodes from
154 the starting index to the end. Returns NULL on error.
155 friend int operator ==(const SoPath &p1, const SoPath &p2)
157 Returns TRUE if all node pointers in the two path chains are identi‐
158 cal.
159 static SoPath * getByName(const SbName &name)
161 static int getByName(const SbName &name, SoPathList &list)
162 These methods lookup and return paths with a given name. Paths are
163 named by calling their setName() method (defined by the SoBase
164 class). The first form returns the last path that was given that
165 name, either by setName() or by reading in a named path from a file.
166 If there is no path with the given name, NULL will be returned. The
167 second form appends all paths with the given name to the given path
168 list and returns the number of paths that were added. If there are
169 no paths with the given name, zero will be returned and nothing will
170 be added to the list.
171
174 SoPath {
175 [head node]
176 [number of remaining indices]
177 [index]
178 ...
179 [index]
180 }
181 Note that the indices in a written path are adjusted based on the nodes
183 that are actually written to a file. Since nodes in the graph that have
184 no effect on the path (such as some separator nodes) are not written, the
185 siblings of such nodes must undergo index adjustment when written. The
186 actual nodes in the graph remain unchanged.
187
189 SoNode, SoRayPickAction, SoSearchAction, SoNodeKitPath
190 SoPath(3IV)()