NAME

       SoPath -

       The SoPath class is a container class for traversal path descriptions.

       SoPath objects contain a list of SoNode pointers and a list of child indices. Indices are
       necessary to disambiguate situations where a node uses the same node as a child multiple
       times.

SYNOPSIS

       #include <Inventor/SoPath.h>

       Inherits SoBase.

       Inherited by SoFullPath, and SoNodeKitPath.

   Public Member Functions
       SoPath (const int approxlength=4)
       SoPath (SoNode *const head)
       SoPath (const SoPath &rhs)
       SoPath & operator= (const SoPath &rhs)
       virtual SoType getTypeId (void) const
           Returns the type identification of an object derived from a class inheriting SoBase.
           This is used for run-time type checking and 'downward' casting.
       void setHead (SoNode *const head)
       SoNode * getHead (void) const
       void append (const int childindex)
       void append (SoNode *const node)
       void append (const SoPath *const frompath)
       void push (const int childindex)
       void pop (void)
       SoNode * getTail (void) const
       SoNode * getNode (const int index) const
       SoNode * getNodeFromTail (const int index) const
       int getIndex (const int index) const
       int getIndexFromTail (const int index) const
       int getLength (void) const
       void truncate (const int length)
       int findFork (const SoPath *const path) const
       int findNode (const SoNode *const node) const
       SbBool containsNode (const SoNode *const node) const
       SbBool containsPath (const SoPath *const path) const
       SoPath * copy (const int startfromnodeindex=0, int numnodes=0) const
       void insertIndex (SoNode *const parent, const int newindex)
       void removeIndex (SoNode *const parent, const int oldindex)
       void replaceIndex (SoNode *const parent, const int index, SoNode *const newchild)
       SbBool isRelevantNotification (SoNotList *const l) const
       virtual void write (SoWriteAction *action)

   Static Public Member Functions
       static void initClass (void)
       static SoType getClassTypeId (void)
       static SoPath * getByName (const SbName name)
       static int getByName (const SbName name, SoPathList &l)

   Protected Member Functions
       virtual ~SoPath ()
       void auditPath (const SbBool flag)

   Friends
       SbBool operator== (const SoPath &lhs, const SoPath &rhs)
       SbBool operator!= (const SoPath &lhs, const SoPath &rhs)

   Additional Inherited Members

Detailed Description

       The SoPath class is a container class for traversal path descriptions.

       SoPath objects contain a list of SoNode pointers and a list of child indices. Indices are
       necessary to disambiguate situations where a node uses the same node as a child multiple
       times.

       Paths can be export and imported to/from file, like other SoBase derived objects. Read the
       documentation on the write() method to see how the file format is.

       It's important to know the difference between this class and SoFullPath when working with
       paths. SoPath::getTail() will return the first node in the path that doesn't inherit
       SoGroup, and getLength() returns the number of nodes down to this node.

       If you need the actual path length, or the actual tail node, you need to cast the path to
       SoFullPath.

Constructor & Destructor Documentation

   SoPath::SoPath (const intapproxlength = 4)
       The default constructor. approxlength is used to indicate in advance the length of the
       path to minimize the number of reallocations.

   SoPath::SoPath (SoNode *consthead)
       A constructor. The argument is set as the head (and only) node of the path.

   SoPath::SoPath (const SoPath &rhs)
       Copy constructor. Not part of the original Open Inventor API.

   SoPath::~SoPath (void) [protected],  [virtual]
       The destructor is protected as destruction of SoPath instances happens through unref() (as
       for all objects derived from classes inheriting SoBase).

Member Function Documentation

   SoPath & SoPath::operator= (const SoPath &rhs)
       Assignment operator, copies the rhs path into this. Not part of the original Open Inventor
       API.

   SoType SoPath::getTypeId (void) const [virtual]
       Returns the type identification of an object derived from a class inheriting SoBase. This
       is used for run-time type checking and 'downward' casting. Usage example:

       void foo(SoNode * node)
       {
         if (node->getTypeId() == SoFile::getClassTypeId()) {
           SoFile * filenode = (SoFile *)node;  // safe downward cast, knows the type
         }
       }

       For application programmers wanting to extend the library with new nodes, engines,
       nodekits, draggers or others: this method needs to be overridden in all subclasses. This
       is typically done as part of setting up the full type system for extension classes, which
       is usually accomplished by using the pre-defined macros available through for instance
       Inventor/nodes/SoSubNode.h (SO_NODE_INIT_CLASS and SO_NODE_CONSTRUCTOR for node classes),
       Inventor/engines/SoSubEngine.h (for engine classes) and so on.

       For more information on writing Coin extensions, see the class documentation of the
       toplevel superclasses for the various class groups.

       Implements SoBase.

   void SoPath::setHead (SoNode *constnode)
       This method sets the head of the path to node. If the object already has a path set, it
       will be truncated.

   SoNode * SoPath::getHead (void) const
       This method returns the head of the path, or NULL if the path is empty.

   void SoPath::append (const intchildindex)
       This function appends the childindex child of the path's tail to the end of the path. It
       can only be used after the head is set.

   void SoPath::append (SoNode *constnode)
       This function adds node to the end if it is a child of the current tail. If path is empty,
       this is equivalent to calling setHead().

   void SoPath::append (const SoPath *constfrompath)
       This method appends the path to the end of the path if the head of frompath is either the
       tail of the path or a child of the path's tail. If the head of frompath is used multiple
       times as a child of the path tail, the lowest child index is used.

   void SoPath::push (const intchildindex) [inline]
       This method pushes the child at childindex on the tail on the path.

   void SoPath::pop (void) [inline]
       This method pops the tail off the path.

   SoNode * SoPath::getTail (void) const
       This method returns the tail node of the path. Please note that this method only considers
       group nodes without hidden children (nodes inheriting SoGroup) when finding the tail.

       If you want to find the real tail node (also below node kits and VRML nodes with hidden
       children), you have to use SoFullPath::getTail(). You don't have to create an SoFullPath
       instance to do this, just cast the SoPath instance to SoFullPath before gettting the tail
       node:

       SoNode * tail = static_cast<SoFullPath*>(path)->getTail();

   SoNode * SoPath::getNode (const intindex) const
       This method returns the node at index in the path, counted from 0 at the head.

   SoNode * SoPath::getNodeFromTail (const intindex) const
       This method returns the node at index in the path, counting from the tail. The index
       argument should be zero or positive.

   int SoPath::getIndex (const intindex) const
       This method returns the child index of the node at index in the path.

   int SoPath::getIndexFromTail (const intindex) const
       This method returns the child index of the node at index in the path, counting from the
       tail. The index argument should be zero or positive.

   int SoPath::getLength (void) const
       This method returns the number of nodes in the path. Only the 'visible' nodes are counted,
       i.e. hidden nodes of e.g. nodekits are not included.

       If you need the actual path length, you need to cast your path to SoFullPath and use
       SoFullPath::getLength().

   void SoPath::truncate (const intlength)
       This method truncates the path to the given length (i.e. all nodes in the path list from
       index length and onwards will be removed from the path list).

   int SoPath::findFork (const SoPath *constpath) const
       This method returns the index of the last node that is the same for both paths, or -1 if
       the paths don't even start on the same node.

   int SoPath::findNode (const SoNode *constnode) const
       Returns the index of node if found in the full path (possibly also in the normally hidden
       parts), or -1 otherwise.

       Note that this method is not part of the original Open Inventor API.

   SbBool SoPath::containsNode (const SoNode *constnode) const
       This method returns TRUE is node is contained somewhere in the full path (possibly also in
       the normally hidden parts), and FALSE otherwise.

   SbBool SoPath::containsPath (const SoPath *constpath) const
       This method returns TRUE if path is contained in the path, and FALSE otherwise.

   SoPath * SoPath::copy (const intstartfromnodeindex = 0, intnumnodes = 0) const
       This method returns a copy of the path starting at startfromnodeindex with length
       numnodes. If numnodes is 0 (default) the path will be copied to the end.

       The returned SoPath instance will have an initial reference count of 0. It is the caller's
       responsibility to ref() and unref() it according to use.

   SoPath * SoPath::getByName (const SbNamename) [static]
       This static method is for retrieving an SoPath by it's name. The last registered SoPath
       with the given name is returned, or NULL if no SoPath by name exists.

   int SoPath::getByName (const SbNamename, SoPathList &l) [static]
       This static method is for finding all the paths with a given name and append them to the l
       list. The number of SoPath instances with name found is returned.

   void SoPath::insertIndex (SoNode *constparent, const intnewindex)
       This method is called when a node in the path chain has a child added, to update the index
       of it's child.

       newindex is the index of the child which was inserted. If newindex is lower than the index
       value of the child node stored in the path, the path is updated accordingly.

   void SoPath::removeIndex (SoNode *constparent, const intoldindex)
       This method is called when a node in the path chain has a child removed, to update the
       index of it's child.

       oldindex was the index of the removed child. If oldindex is lower than or equal to the
       index value of the child node stored in the path, the path is updated accordingly.

   void SoPath::replaceIndex (SoNode *constparent, const intindex, SoNode *constnewchild)
       This method is called when a node newchild replaces a node in the path. index is the
       position of the child which has been replaced.

   SbBool SoPath::isRelevantNotification (SoNotList *constl) const
       Return TRUE if the notification chain l will affect the path. l will affect the path
       either if the notification is in the path (the notification started on a field in a node
       in the path), or off the path (the notification started in a non-separator node that is
       left of the path's node).

   void SoPath::write (SoWriteAction *action) [virtual]
       This method is used to write the contents of an SoPath.

       A path is written as:

       Path {
         HEAD-NODE-OF-SUBGRAPH
         NUMBER-OF-INDICES
         INDEX0
         INDEX1
         ...
       }

       [The rest of the documentation for this method only explains the reason behind a mismatch
       in behavior between the original Open Inventor and Coin. Don't read it if you're not
       taking a particular interest. (Short version: we do SoPath export in a somewhat more
       inefficient way to avoid the potential for bugs).]

       Note that unlike Open Inventor, we write the complete subgraph below the head node. Only
       writing the parts of the subgraph affecting the state for nodes within the path is error
       prone if a subgraph is written out as part of path before it is written out 'properly'.
       Consider writing a scene graph which looks like this (in memory):

       DEF top_sep Separator {
         Cone { }
         DEF a_sphere Sphere { }
         Cube { }
       }

       DEF path_switch PathSwitch {
         path Path {
           ...path from "top_sep" to "a_sphere"...
         }
       }

       ..if we now do:

       SoSeparator * root = new SoSeparator;
       root->addChild([ptr to path_switch]);
       root->addChild([ptr to top_sep]);
       SoWriteAction wa;
       wa.apply(root);

       ..we would get the scene graph exported like this:

       Separator {
         DEF path_switch PathSwitch {
           path Path {
             DEF top_sep Separator {
               DEF a_sphere Sphere {
               }
             }
             1
             0
           }
         }
         USE top_sep
       }

       ..and as you can see, both the Cone and the Cube nodes has vanished, as they was not
       important for the part per se, and not written as part of it.

       This is why we do full subgraph export for head nodes in paths.

   void SoPath::auditPath (const SbBoolflag) [protected]
       Set whether or not to audit the nodes in the path to detect changes.

Friends And Related Function Documentation

   SbBool operator== (const SoPath &lhs, const SoPath &rhs) [friend]
       Compares contents of path lhs and path rhs, and returns TRUE if they are equal.

   SbBool operator!= (const SoPath &lhs, const SoPath &rhs) [friend]
       Returns TRUE if paths lhs and rhs does not contain the same nodes in the same order.

Author

       Generated automatically by Doxygen for Coin from the source code.