Linux Certif

Toute la documentation sur la certification Linux LPI

SoPath.3coin2

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

class SoFullPath

class SoNodeKitPath

class SoAction

class SoTempPath

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.

Referenced by copy().

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

References setHead().

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

References operator=().

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

References truncate().

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.

References SoType::badType(), SoType::createType(), and SoBase::getClassTypeId().

Referenced by SoDB::init().

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

References SoChildList::addPathAuditor(), and SoBase::startNotify().

Referenced by append(), and SoPath().

SoType SoPath::getClassTypeId (void) [static]This static method returns the SoType object associated with objects of this class.

Reimplemented from SoBase.

Referenced by getByName(), SoBaseKit::getPartString(), SoDB::read(), SoSFPath::referencesCopy(), SoSFNode::referencesCopy(), and SoSFEngine::referencesCopy().

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
     }
     else if (node->getTypeId().isOfType(SoGroup::getClassTypeId())) {
       SoGroup * group = (SoGroup *)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.

References append(), and truncate().

Referenced by append(), SoNodeKitPath::append(), and SoPath().

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

Referenced by append(), SoPathSensor::attach(), SoSelection::findPath(), isRelevantNotification(), SoSFPath::notify(), SoMFPath::notify(), SoSFPath::referencesCopy(), SoSFNode::referencesCopy(), SoSFEngine::referencesCopy(), SoShape::shouldGLRender(), and write().

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.

References SbPList::getLength(), and SoDebugError::post().

Referenced by append(), copy(), SoBaseKit::createPathToAnyPart(), SoDataSensor::notify(), push(), replaceIndex(), and setHead().

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

References append(), SbPList::find(), SoNode::getChildren(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::post(), and 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.

Reimplemented in SoNodeKitPath.

References append(), SoNode::getChildren(), getHead(), SbPList::getLength(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), operator=(), and SoDebugError::post().

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

References append().

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

Reimplemented in SoFullPath, and SoNodeKitPath.

References truncate().

SoNode * SoPath::getTail (void) constThis method returns the tail node of the path.

Reimplemented in SoFullPath, and SoNodeKitPath.

References SbList< Type >::getLength(), SbPList::getLength(), getLength(), and SoDebugError::postWarning().

Referenced by SoLineHighlightRenderAction::apply(), SoBoxHighlightRenderAction::apply(), SoTransformManip::replaceNode(), SoSpotLightManip::replaceNode(), SoPointLightManip::replaceNode(), SoDirectionalLightManip::replaceNode(), and SoClipPlaneManip::replaceNode().

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

Reimplemented in SoNodeKitPath.

References SoDebugError::post().

Referenced by SoAction::apply(), SoBaseKit::getPartString(), isRelevantNotification(), SoDragger::shouldGrabBasedOnSurrogate(), and SoAction::switchToPathTraversal().

SoNode * SoPath::getNodeFromTail (const int index) constThis 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.

References getLength(), and SoDebugError::post().

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

References SoDebugError::post().

Referenced by isRelevantNotification(), and SoAction::usePathCode().

int SoPath::getIndexFromTail (const int index) constThis 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.

References getLength(), and SoDebugError::post().

int SoPath::getLength (void) constThis 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.

References SbPList::getLength().

Referenced by SoAction::apply(), getIndexFromTail(), getNodeFromTail(), and getTail().

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.

Referenced by pop(), SoFullPath::pop(), removeIndex(), replaceIndex(), setHead(), and ~SoPath().

int SoPath::findFork (const SoPath *const path) constThis 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.

Reimplemented in SoNodeKitPath.

References SbList< Type >::getArrayPtr().

Referenced by SoPathList::uniquify().

int SoPath::findNode (const SoNode *const node) constReturns 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.

References SbPList::getArrayPtr().

Referenced by containsNode(), containsPath(), SoSelection::copyFromThis(), SoTransformerDragger::dragStart(), SoTrackballDragger::dragStart(), SoTabPlaneDragger::dragStart(), SoHandleBoxDragger::dragStart(), SoPickedPoint::getDetail(), SoBaseKit::getPartString(), SoSelection::handleEvent(), insertIndex(), SoSelection::performToggleSelection(), removeIndex(), replaceIndex(), SoPickedPoint::setDetail(), and SoDragger::updateDraggerCache().

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

References findNode().

Referenced by SoBaseKit::createPathToAnyPart(), and SoBaseKit::rayPick().

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

References findNode(), and SbList< Type >::getArrayPtr().

Referenced by SoGetBoundingBoxAction::checkResetAfter(), SoGetBoundingBoxAction::checkResetBefore(), SoLocateHighlight::handleEvent(), SoEventCallback::handleEvent(), SoAction::pushCurPath(), SoDragger::shouldGrabBasedOnSurrogate(), and SoAction::usePathCode().

SoPath * SoPath::copy (const int startfromnodeindex = 0, int numnodes = 0) constThis 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.

References append(), SoDebugError::post(), and SoPath().

Referenced by SoSelection::copyFromThis(), SoBaseKit::createPathToAnyPart(), SoSFPath::fixCopy(), SoMFPath::fixCopy(), SoExtSelection::GLRenderBelowPath(), SoAnnotation::GLRenderBelowPath(), SoAnnotation::GLRenderInPath(), SoLocateHighlight::handleEvent(), SoNode::search(), SoEventCallback::setPath(), SoPickedPoint::SoPickedPoint(), and SoSurroundScale::updateMySurroundParams().

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.

References getClassTypeId(), and SoBase::getNamedBase().

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.

References SoPathList::append(), getClassTypeId(), and SoBase::getNamedBases().

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.

References findNode(), and SoDebugError::postInfo().

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.

References findNode(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::post(), SoDebugError::postInfo(), and truncate().

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.

References append(), findNode(), SoType::getName(), SbName::getString(), SoBase::getTypeId(), SoDebugError::postInfo(), and truncate().

SbBool SoPath::isRelevantNotification (SoNotList *const l) constReturn 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).

References SoNotRec::getBase(), SoNode::getClassTypeId(), getHead(), getIndex(), SoNotList::getLastRec(), getNode(), SoNotRec::getPrevious(), SoNotRec::getType(), and SoBase::isOfType().

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.

References SoBase::addWriteReference(), SoWriteAction::continueToApply(), getHead(), SbList< Type >::getLength(), SoWriteAction::getOutput(), SoOutput::getStage(), SoBase::hasMultipleWriteRefs(), SoOutput::indent(), SoOutput::isBinary(), SoOutput::write(), SoBase::writeFooter(), and SoBase::writeHeader().

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

Author

Generated automatically by Doxygen for Coin from the source code.