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
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)
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.
Constructor & Destructor Documentation
SoPath::SoPath (const int approxlength = 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 *const head) 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
void SoPath::initClass (void) [static] Sets up initialization for data
common to all instances of this class, like submitting necessary
information to the Coin type system.
Reimplemented from SoBase.
SoPath & SoPath::operator= (const SoPath & rhs) Assignment operator, copies
the rhs path into this. Not part of the original Open Inventor API.
SoType SoPath::getClassTypeId (void) [static] This static method returns
the SoType object associated with objects of this class.
Reimplemented from SoBase.
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 *const node) 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 int childindex) 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 *const node) 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 *const frompath) 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 int childindex) [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.
Reimplemented in SoFullPath, and SoNodeKitPath.
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();
Reimplemented in SoFullPath, and SoNodeKitPath.
SoNode * SoPath::getNode (const int index) const This method returns the
node at index in the path, counted from 0 at the head.
Reimplemented in SoNodeKitPath.
SoNode * SoPath::getNodeFromTail (const int index) const This method
returns the node at index in the path, counting from the tail. The
index argument should be zero or positive.
Reimplemented in SoFullPath, and SoNodeKitPath.
int SoPath::getIndex (const int index) const This method returns the child
index of the node at index in the path.
int SoPath::getIndexFromTail (const int index) 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.
Reimplemented in SoFullPath.
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.
Reimplemented in SoFullPath, and SoNodeKitPath.
void SoPath::truncate (const int length) 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).
Reimplemented in SoNodeKitPath.
int SoPath::findFork (const SoPath *const path) 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 *const node) 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 *const node) 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 *const path) const This method
returns TRUE if path is contained in the path, and FALSE otherwise.
SoPath * SoPath::copy (const int startfromnodeindex = 0, int numnodes = 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 SbName name) [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 SbName name, 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 *const parent, const int newindex) 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 *const parent, const int oldindex) 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 *const parent, const int index, SoNode
*const newchild) 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 *const l) 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’...
}
}
SoSeparator * root = new SoSeparator;
root->addChild([ptr to path_switch]);
root->addChild([ptr to top_sep]);
SoWriteAction wa;
wa.apply(root);
Separator {
DEF path_switch PathSwitch {
path Path {
DEF top_sep Separator {
DEF a_sphere Sphere {
}
}
1
0
}
}
USE top_sep
}
This is why we do full subgraph export for head nodes in paths.
void SoPath::auditPath (const SbBool flag) [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.