Coin  4.0.3
Coin3D core library
Loading...
Searching...
No Matches
SoPath Class Reference

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

#include <Inventor/SoPath.h>

Inheritance diagram for SoPath:
SoBase SoFullPath SoNodeKitPath SoTempPath

Public Member Functions

 SoPath (const int approxlength=4)
 
 SoPath (const SoPath &rhs)
 
 SoPath (SoNode *const head)
 
void append (const int childindex)
 
void append (const SoPath *const frompath)
 
void append (SoNode *const node)
 
SbBool containsNode (const SoNode *const node) const
 
SbBool containsPath (const SoPath *const path) const
 
SoPathcopy (const int startfromnodeindex=0, int numnodes=0) const
 
int findFork (const SoPath *const path) const
 
int findNode (const SoNode *const node) const
 
SoNodegetHead (void) const
 
int getIndex (const int index) const
 
int getIndexFromTail (const int index) const
 
int getLength (void) const
 
SoNodegetNode (const int index) const
 
SoNodegetNodeFromTail (const int index) const
 
SoNodegetTail (void) const
 
virtual SoType getTypeId (void) const
 Returns the type identification of an object derived from a class inheriting SoBase. This is used for runtime type checking and "downward" casting.
 
void insertIndex (SoNode *const parent, const int newindex)
 
SbBool isRelevantNotification (SoNotList *const l) const
 
SoPathoperator= (const SoPath &rhs)
 
void pop (void)
 
void push (const int childindex)
 
void removeIndex (SoNode *const parent, const int oldindex)
 
void replaceIndex (SoNode *const parent, const int index, SoNode *const newchild)
 
void setHead (SoNode *const head)
 
void truncate (const int length)
 
virtual void write (SoWriteAction *action)
 
- Public Member Functions inherited from SoBase
void addAuditor (void *const auditor, const SoNotRec::Type type)
 
virtual void addWriteReference (SoOutput *out, SbBool isfromfield=FALSE)
 
void assertAlive (void) const
 
const SoAuditorListgetAuditors (void) const
 
virtual SbName getName (void) const
 
int32_t getRefCount (void) const
 
SbBool isOfType (SoType type) const
 Returns TRUE if the type of this object is either of the same type or inherited from type.
 
virtual void notify (SoNotList *l)
 
void ref (void) const
 
void removeAuditor (void *const auditor, const SoNotRec::Type type)
 
virtual void setName (const SbName &newname)
 
SbBool shouldWrite (void)
 
virtual void startNotify (void)
 
void touch (void)
 
void unref (void) const
 
void unrefNoDelete (void) const
 

Static Public Member Functions

static SoPathgetByName (const SbName name)
 
static int getByName (const SbName name, SoPathList &l)
 
static SoType getClassTypeId (void)
 This static method returns the SoType object associated with objects of this class.
 
static void initClass (void)
 Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
 
- Static Public Member Functions inherited from SoBase
static void addName (SoBase *const base, const char *const name)
 
static SbBool connectRoute (SoInput *input, const SbName &fromnodename, const SbName &fromfieldname, const SbName &tonodename, const SbName &tofieldname)
 
static void decrementCurrentWriteCounter (void)
 
static SoType getClassTypeId (void)
 This static method returns the SoType object associated with objects of this class.
 
static SoBasegetNamedBase (const SbName &name, SoType type)
 
static int getNamedBases (const SbName &name, SoBaseList &baselist, SoType type)
 
static SbBool getTraceRefs (void)
 
static void incrementCurrentWriteCounter (void)
 
static void initClass (void)
 Sets up initialization for data common to all instances of this class, like submitting necessary information to the Coin type system.
 
static SbBool read (SoInput *input, SoBase *&base, SoType expectedtype)
 
static SbBool readRoute (SoInput *input)
 
static void removeName (SoBase *const base, const char *const name)
 
static void setInstancePrefix (const SbString &c)
 
static void setTraceRefs (SbBool trace)
 

Protected Member Functions

virtual ~SoPath ()
 
void auditPath (const SbBool flag)
 
- Protected Member Functions inherited from SoBase
 SoBase (void)
 
virtual ~SoBase ()
 
virtual SoNotRec createNotRec (void)
 
virtual void destroy (void)
 
virtual const char * getFileFormatName (void) const
 
SbBool hasMultipleWriteRefs (void) const
 
void writeFooter (SoOutput *out) const
 
SbBool writeHeader (SoOutput *out, SbBool isgroup, SbBool isengine) const
 

Additional Inherited Members

- Protected Types inherited from SoBase
enum  BaseFlags { IS_ENGINE = 0x01 , IS_GROUP = 0x02 }
 
- Static Protected Member Functions inherited from SoBase
static uint32_t getCurrentWriteCounter (void)
 
static void staticDataLock (void)
 
static void staticDataUnlock (void)
 

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() [1/3]

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() [2/3]

SoPath::SoPath ( SoNode *const head)

A constructor. The argument is set as the head (and only) node of the path.

◆ SoPath() [3/3]

SoPath::SoPath ( const SoPath & rhs)

Copy constructor. Not part of the original Open Inventor API.

◆ ~SoPath()

SoPath::~SoPath ( void )
protectedvirtual

The destructor is protected as destruction of SoPath instances happens through unref() (as for all objects derived from classes inheriting SoBase).

Member Function Documentation

◆ append() [1/3]

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.

◆ append() [2/3]

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.

◆ append() [3/3]

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().

◆ auditPath()

void SoPath::auditPath ( const SbBool flag)
protected

Set whether or not to audit the nodes in the path to detect changes.

◆ containsNode()

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.

◆ containsPath()

SbBool SoPath::containsPath ( const SoPath *const path) const

This method returns TRUE if path is contained in the path, and FALSE otherwise.

◆ copy()

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.

◆ findFork()

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.

◆ findNode()

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.

◆ getByName() [1/2]

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

This static method is for retrieving an SoPath by its name. The last registered SoPath with the given name is returned, or NULL if no SoPath by name exists.

◆ getByName() [2/2]

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.

◆ getHead()

SoNode * SoPath::getHead ( void ) const

This method returns the head of the path, or NULL if the path is empty.

◆ getIndex()

int SoPath::getIndex ( const int index) const

This method returns the child index of the node at index in the path.

◆ getIndexFromTail()

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.

◆ getLength()

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().

◆ getNode()

SoNode * SoPath::getNode ( const int index) const

This method returns the node at index in the path, counted from 0 at the head.

◆ getNodeFromTail()

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.

◆ getTail()

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 getting the tail node:

SoNode * tail = static_cast<SoFullPath*>(path)->getTail();
The SoFullPath class allows examination of hidden children in paths.
Definition SoFullPath.h:38
The SoNode class is the base class for nodes used in scene graphs.
Definition SoNode.h:56
SoNode * getTail(void) const
Definition SoPath.cpp:405

◆ getTypeId()

SoType SoPath::getTypeId ( void ) const
virtual

Returns the type identification of an object derived from a class inheriting SoBase. This is used for runtime 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
}
}
The SbList class is a template container class for lists.
Definition SbList.h:70
virtual SoType getTypeId(void) const =0
Returns the type identification of an object derived from a class inheriting SoBase....
The SoFile class is node container for another model file.
Definition SoFile.h:43
static SoType getClassTypeId(void)
Definition SoFile.cpp:100

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 predefined 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 top level superclasses for the various class groups.

Implements SoBase.

◆ insertIndex()

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

◆ isRelevantNotification()

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

◆ operator=()

SoPath & SoPath::operator= ( const SoPath & rhs)

Assignment operator, copies the rhs path into this. Not part of the original Open Inventor API.

◆ pop()

void SoPath::pop ( void )
inline

This method pops the tail off the path.

◆ push()

void SoPath::push ( const int childindex)
inline

This method pushes the child at childindex on the tail on the path.

◆ removeIndex()

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

◆ replaceIndex()

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.

◆ setHead()

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.

◆ truncate()

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

◆ write()

void SoPath::write ( SoWriteAction * action)
virtual

This method is used to write the contents of an SoPath.

A path is written as:

[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):

Cone { }
Cube { }
}
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]);
wa.apply(root);
virtual void addChild(SoNode *node)
Definition SoGroup.cpp:453
The SoSeparator class is a state-preserving group node.
Definition SoSeparator.h:44
The SoWriteAction class writes a scene graph to file.
Definition SoWriteAction.h:42

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

..and as you can see, both the Cone and the Cube nodes have vanished, as they were 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.


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