SoSearchAction(3IV)

NAME
SoSearchAction — searches for nodes in a scene graph

INHERITS FROM
SoAction > SoSearchAction

SYNOPSIS
#include <Inventor/actions/SoSearchAction.h>

enum LookFor {
SoSearchAction::NODE
Search for a particular node (by pointer)
SoSearchAction::TYPE
Search for a particular type of node
SoSearchAction::NAME
Search for a node with a particular name
}

enum Interest {
SoSearchAction::FIRST
Return only the first path found
SoSearchAction::LAST
Return only the last path found
SoSearchAction::ALL
Return all paths found
}

Methods from class SoSearchAction:

SoSearchAction()
void
setNode(SoNode *n)
SoNode *
getNode() const
void
setType(SoType t, SbBool derivedIsOk = TRUE)
SoType
getType(SbBool &derivedIsOk) const
void
setName(const SbName &n)
const SbName &
getName() const
void
setFind(int what)
int
getFind()
void
setInterest(Interest interest)
Interest
getInterest() const
void
setSearchingAll(SbBool flag)
SbBool
isSearchingAll() const
SoPath *
getPath() const
SoPathList &
getPaths()
void
reset()

Methods from class SoAction:

virtual void
apply(SoNode *node)
virtual void
apply(SoPath *path)
virtual void
apply(const SoPathList &pathList, SbBool obeysRules = FALSE)
static SoType
getClassTypeId()
virtual SoType
getTypeId()
virtual SbBool
isOfType(SoType type)
virtual void
invalidateState()

DESCRIPTION
This class is used to search scene graphs for specific nodes, nodes of a specific type, nodes with a specific name, or any combination of these. It can search for just the first or last node satisfying the criteria or for all such nodes. The actions return paths to each node found.

Note that by default nodekits do not search their children when a search action is applied. The man page for SoBaseKit discusses the methods SoBaseKit::isSearchingChildren() and SoBaseKit::setSearchingChildren(), which allow you to query and control this behavior.

METHODS

SoSearchAction()
Constructor.

void
setNode(SoNode *n)
SoNode *
getNode() const
Sets/returns the node to search for.

void
setType(SoType t, SbBool derivedIsOk = TRUE)
SoType
getType(SbBool &derivedIsOk) const
Sets/returns the node type to search for. If derivedIsOk is TRUE, a node that is of a type that is derived from t will pass this search criterion.

void
setName(const SbName &n)
const SbName &
getName() const
Sets/returns the name of the node to search for.

void
setFind(int what)
int
getFind()
Sets/returns what to look for; what is a bitmask of LookFor enum values. Default is no flags at all. Note that setting a node, type, and/or name to search for activates the relevant flag, so you may never need to call this method directly.

void
setInterest(Interest interest)
Interest
getInterest() const
Sets/returns which paths to return. Default is FIRST.

void
setSearchingAll(SbBool flag)
SbBool
isSearchingAll() const
Sets/returns whether searching uses regular traversal or whether it traverses every single node. For example, if this flag is FALSE, an SoSwitch node will traverse only the child or children it would normally traverse for an action. If the flag is TRUE, the switch would always traverse all of its children. The default is FALSE.

SoPath *
getPath() const
Returns resulting path, or NULL if no path was found. This should be used if the interest is FIRST or LAST.

SoPathList &
getPaths()
Returns resulting path list. This should be used if the interest is ALL.

void
reset()
Resets options back to default values; clears list of returned paths. This can be used to apply the action again with a different set of search criteria.

SEE ALSO
SoPath, SoBaseKit