SoPath Class Reference
[General]

Path that points to a list of hierarchical nodes. More...

#include <Inventor/SoPath.h>

Inheritance diagram for SoPath:
SoBase SoRefCounter SoTypedObject SoFullPath SoNodeKitPath

List of all members.

Public Member Functions

 SoPath ()
 SoPath (int approxLength)
 SoPath (SoNode *node)
void setHead (SoNode *node)
void append (int childIndex)
void append (SoNode *childNode)
void append (const SoPath *fromPath)
void push (int childIndex)
void pop ()
SoNodegetHead () const
SoNodegetTail () const
SoNodegetNode (int i) const
SoNodegetNode (const SoType type, int &i) const
SoNodegetNodeFromTail (int i) const
int getIndex (int i) const
int getInstanceIndex (int i) const
int getIndexFromTail (int i) const
int getInstanceIndexFromTail (int i) const
int getLength () const
void truncate (int start)
SbBool containsNode (const SoNode *node) const
SbBool containsNode (const SoType type) const
SbBool containsPath (const SoPath *path) const
int findFork (const SoPath *path) const
SoPathcopy (int startFromNodeIndex=0, int numNodes=0) const
virtual SoType getTypeId () const

Static Public Member Functions

static SoType getClassTypeId ()
static SoPathgetByName (const SbName &name)
static int getByName (const SbName &name, SoPathList &list)

Friends

class SoFullPath
class SoTempPath
class SoAction
class SoPathNoRef
class SoTraversalPassImpl
int operator== (const SoPath &p1, const SoPath &p2)
std::ostream & operator<< (std::ostream &os, const SoPath &path)
bool operator< (const SoPath &p1, const SoPath &p2)

Detailed Description

Path that points to a list of hierarchical nodes.

A path represents a scene graph or subgraph. It contains a list of nodes forming a chain from some root to some descendant. Each node in the chain is a child of the previous node. Paths are used to refer to some object in a scene graph precisely and unambiguously, even if there are many instances of the object. Therefore, paths are returned by both the SoRayPickAction and SoSearchAction.

When an action is applied to a path, only the nodes in the subgraph defined by the path are traversed. These include: the nodes in the path chain, all nodes (if any) below the last node in the path, and all nodes whose effects are inherited by any of these nodes.

SoPath attempts to maintain consistency of paths even when the structure of the scene graph changes. For example, removing a child from its parent when both are in a path chain cuts the path chain at that point, leaving the top part intact. Removing the node to the left of a node in a path adjusts the index for that node. Replacing a child of a node when both the parent and the child are in the chain replaces the child in the chain with the new child, truncating the path below the new child.

Hidden children

Note that only public children of nodes are accessible from an SoPath. Nodes like node kits limit access to their children and these "hidden children" will not be visible using the SoPath methods.

For example, if your application does picking and gets a path from SoRayPickAction, the actual last node in the path (tail) will normally be a shape node. But if that shape is part of a node kit, then the getTail() method will return the node kit, not the shape node. To access all hidden children in the path, simply cast the path object to SoFullPath before calling get methods.

To access hidden node kit children (but not all children) in the path, cast the path object to SoNodeKitPath before calling get methods.

[C++] Reference counting:

FILE FORMAT/DEFAULT

SEE ALSO

SoFullPath, SoNode, SoRayPickAction, SoSearchAction, SoNodeKitPath


Constructor & Destructor Documentation

SoPath::SoPath (  ) 

Constructs an empty path.

SoPath::SoPath ( int  approxLength  ) 

Constructs a path with a hint to length (number of nodes in chain).

SoPath::SoPath ( SoNode node  ) 

Constructs a path and sets the head node to the given node.


Member Function Documentation

void SoPath::append ( const SoPath fromPath  ) 

Adds all nodes in fromPath's chain to end of chain; the head node of fromPath must be the same as or a child of the current tail node.

Reimplemented in SoNodeKitPath.

void SoPath::append ( SoNode childNode  ) 

Adds node to end of chain; uses the first occurrence of childNode as child of current tail node.

If the path is empty, this is equivalent to setHead(childNode) .

void SoPath::append ( int  childIndex  ) 

Adds node to end of chain; the node is the childIndex'th child of the current tail node.

SbBool SoPath::containsNode ( const SoType  type  )  const

Returns TRUE if the node type is found anywhere in the path chain.

SbBool SoPath::containsNode ( const SoNode node  )  const

Returns TRUE if the node is found anywhere in the path chain.

SbBool SoPath::containsPath ( const SoPath path  )  const

Returns TRUE if the nodes in the chain in the passed path are contained (in consecutive order) in this path chain.

SoPath* SoPath::copy ( int  startFromNodeIndex = 0,
int  numNodes = 0 
) const

Creates and returns a new path that is a copy of some or all of this path.

Copying starts at the given index (default is 0, which is the head node). A numNodes of 0 (the default) means copy all nodes from the starting index to the end. Returns NULL on error.

int SoPath::findFork ( const SoPath path  )  const

If the two paths have different head nodes, this returns -1.

Otherwise, it returns the path chain index of the last node (starting at the head) that is the same for both paths.

Reimplemented in SoNodeKitPath.

static int SoPath::getByName ( const SbName name,
SoPathList list 
) [static]

Method to return paths with a given name.

Paths are named by calling their setName() method (defined by the SoBase class). This method appends all paths with the given name to the given path list and returns the number of paths that were added. If there are no paths with the given name, zero will be returned and nothing will be added to the list.

static SoPath* SoPath::getByName ( const SbName name  )  [static]

Method to return a path with a given name.

Paths are named by calling their setName() method (defined by the SoBase class). This method returns the last path that was given the specified name, either by setName() or by reading in a named path from a file. If there is no path with the given name, NULL will be returned.

static SoType SoPath::getClassTypeId (  )  [static]

Returns type identifier for SoPath class.

Reimplemented from SoBase.

SoNode* SoPath::getHead (  )  const [inline]

Returns the first node in a path chain.

int SoPath::getIndex ( int  i  )  const

Returns the index of the i'th node (within its parent) in the chain.

int SoPath::getIndexFromTail ( int  i  )  const

Returns the index of the i'th node (within its parent) in the chain, counting backward from the tail node.

Passing 0 for i returns the index of the tail node.

Reimplemented in SoFullPath.

int SoPath::getInstanceIndex ( int  i  )  const

Returns the index of the instance inside the parent SoMultipleInstance, SoMultipleCopy or SoArray group.

The returned value is -1 for other parent nodes.

int SoPath::getInstanceIndexFromTail ( int  i  )  const

Returns the index of the i'th node instance (within its parent, if it is a SoMultipleInstance, SoMultipleCopy or SoArray group in the chain, counting backward from the tail node.

Passing 0 for i returns the instance index of the tail node.

Reimplemented in SoFullPath.

int SoPath::getLength (  )  const

Returns length of path chain (number of nodes).

Reimplemented in SoNodeKitPath, and SoFullPath.

SoNode* SoPath::getNode ( const SoType  type,
int &  i 
) const

Returns the first node and its index, from the head of the given type in the chain.

NULL is returned and the index is set to -1 if no node of the given type is found.

SoNode* SoPath::getNode ( int  i  )  const

Returns the i'th node (within its parent) in the chain.

Calling getNode(0) is equivalent to calling getHead().

Reimplemented in SoNodeKitPath.

SoNode* SoPath::getNodeFromTail ( int  i  )  const

Returns the i'th node (within its parent) in the chain, counting backward from the tail node.

Passing 0 for i returns the tail node.

Reimplemented in SoNodeKitPath, and SoFullPath.

SoNode* SoPath::getTail (  )  const

Returns the last node in a path chain.

Reimplemented in SoNodeKitPath, and SoFullPath.

virtual SoType SoPath::getTypeId (  )  const [virtual]

Returns type identifier for path instance.

Implements SoTypedObject.

void SoPath::pop (  ) 

The push() and pop() methods allow a path to be treated as a stack; they push a node at the end of the chain and pop the last node off.

Reimplemented in SoNodeKitPath, and SoFullPath.

void SoPath::push ( int  childIndex  ) 

The push() and pop() methods allow a path to be treated as a stack; they push a node at the end of the chain and pop the last node off.

void SoPath::setHead ( SoNode node  ) 

Sets head node (first node in chain).

The head node must be set before the append() or push() methods may be called.

void SoPath::truncate ( int  start  ) 

Truncates the path chain, removing all nodes from index start on.

Calling truncate(0) empties the path entirely.

Reimplemented in SoNodeKitPath.


Friends And Related Function Documentation

bool operator< ( const SoPath p1,
const SoPath p2 
) [friend]

Returns TRUE is p1 strictly less than p2: to provide a total order operation for SoPath.

std::ostream& operator<< ( std::ostream &  os,
const SoPath path 
) [friend]

Writes the path to the specified output stream.

int operator== ( const SoPath p1,
const SoPath p2 
) [friend]

Returns TRUE if all nodes in the two path chains are identical.

Reimplemented in SoNodeKitPath.

friend class SoAction [friend]
friend class SoFullPath [friend]
friend class SoPathNoRef [friend]
friend class SoTempPath [friend]

Reimplemented in SoFullPath.

friend class SoTraversalPassImpl [friend]

The documentation for this class was generated from the following file:

Open Inventor Toolkit reference manual, generated on 15 Mar 2023
Copyright © Thermo Fisher Scientific All rights reserved.
http://www.openinventor.com/