Provided by: inventor-doc_2.1.5-10+dfsg-2.1build2_all bug

NAME

       SoPath — path that points to a list of hierarchical nodes

INHERITS FROM

       SoBase > SoPath

SYNOPSIS

       #include <Inventor/SoPath.h>

          Methods from class SoPath:

                         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()
     SoNode *            getHead() const
     SoNode *            getTail() const
     SoNode *            getNode(int i) const
     int                 getIndex(int i) const
     SoNode *            getNodeFromTail(int i) const
     int                 getIndexFromTail(int i) const
     int                 getLength() const
     void                truncate(int start)
     SbBool              containsNode(const SoNode *node) const
     SbBool              containsPath(const SoPath *path) const
     int                 findFork(const SoPath *path) const
     SoPath *            copy(int startFromNodeIndex = 0, int numNodes = 0) const
     friend int          operator ==(const SoPath &p1, const SoPath &p2)
     static SoPath *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoPathList &list)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     static SoType       getClassTypeId()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const

DESCRIPTION

       A  path  represents  a  scene  graph  or subgraph. It contains a list of pointers to nodes
       forming a chain from some root to some descendent. 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.

       Note that only public children of nodes are accessible from an  SoPath.  Nodes  like  node
       kits  that  limit access to their children may provide other ways to get more information,
       such as by using the SoNodeKitPath class.

METHODS

                         SoPath()
          Constructs an empty path.

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

                         SoPath(SoNode *node)
          Constructs a path and sets the head node to the given node.

     void                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                append(int childIndex)
          Adds  node  to  end  of  chain; the node is the childIndex'th child of the current tail
          node.

     void                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                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.

     void                push(int childIndex)
     void                pop()
          These 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.

     SoNode *            getHead() const
     SoNode *            getTail() const
          These return the first and last nodes in a path chain.

     SoNode *            getNode(int i) const
     int                 getIndex(int i) const
          These  return  a  pointer  to  the  i'th node or the index of the i'th node (within its
          parent) in the chain. Calling getNode(0) is equivalent to calling getHead().

     SoNode *            getNodeFromTail(int i) const
     int                 getIndexFromTail(int i) const
          These return a pointer to the i'th node or 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
          tail node or its index.

     int                 getLength() const
          Returns length of path chain (number of nodes).

     void                truncate(int start)
          Truncates the path chain, removing all nodes from index start on.  Calling  truncate(0)
          empties the path entirely.

     SbBool              containsNode(const SoNode *node) const
          Returns TRUE if the node is found anywhere in the path chain.

     SbBool              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.

     int                 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.

     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.

     friend int          operator ==(const SoPath &p1, const SoPath &p2)
          Returns TRUE if all node pointers in the two path chains are identical.

     static SoPath *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoPathList &list)
          These  methods  lookup  and  return paths with a given name. Paths are named by calling
          their setName() method (defined by the SoBase class). The first form returns  the  last
          path that was given that 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. The  second  form
          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.

FILE FORMAT/DEFAULTS

       SoPath {
          [head node]
          [number of remaining indices]
          [index]
          ...
          [index]
     }

     Note  that  the  indices in a written path are adjusted based on the nodes that are actually
     written to a file. Since nodes in the graph that have no effect on the path  (such  as  some
     separator  nodes)  are not written, the siblings of such nodes must undergo index adjustment
     when written. The actual nodes in the graph remain unchanged.

SEE ALSO

       SoNode, SoRayPickAction, SoSearchAction, SoNodeKitPath

                                                                                    SoPath(3IV)()