SoSearchAction Class Reference
[Actions]

Searches for nodes in a scene graph. More...

#include <Inventor/actions/SoSearchAction.h>

Inheritance diagram for SoSearchAction:
SoAction SoTypedObject SoSearchPathAction SoSearchStepAction

List of all members.

Public Types

enum  LookFor {
  NODE = 0x01,
  TYPE = 0x02,
  NAME = 0x04
}
enum  Interest {
  FIRST,
  LAST,
  ALL
}

Public Member Functions

virtual SoType getTypeId () const
 SoSearchAction ()
virtual void reset ()
virtual void clearApplyResult ()
void setFind (int what)
int getFind ()
SoNodegetNode () const
void setNode (SoNode *n)
SoType getType (SbBool &derivedIsOk) const
void setType (SoType t, SbBool derivedIsOk=TRUE)
const SbNamegetName () const
void setName (const SbName &n)
Interest getInterest () const
void setInterest (Interest i)
SbBool isSearchingAll () const
void setSearchingAll (SbBool flag)
SoPathgetPath () const
SoPathListgetPaths ()

Static Public Member Functions

static SoType getClassTypeId ()

Detailed Description

Searches for nodes in a scene graph.

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 action returns a path (SoPath) to each node found. The searched for node is the "tail" of each path.

Note that the search criteria are cumulative. For example, if you do a search by name (setName()), then reuse the same SoSearchAction object to do a search by type (setType()), the action will actually search for a node that satisfies both criteria. To avoid this problem, call reset() before reusing the action object.

By default SoSearchAction only searches nodes that are actually traversed. For example it would not search all the children of an SoSwitch node unless the whichChild field is set to SO_SWITCH_ALL. To search all nodes in the scene graph (except nodekits - see next paragraph) call setSearchingAll(TRUE).

Nodekits:

Hidden references:

SoSearchAction creates one or more SoPath objects when applied to the scene graph. An SoPath object calls ref() on each node in the path. This reference will prevent the node from being destroyed for as long as the SoPath object exists. These SoPath objects are stored internally in the action and exist until the action object itself is destroyed or reset.


Efficiency:

SoSearchAction is convenient for finding one or many nodes in the scene graph. However it may be an inefficient solution for finding a large number of nodes because it uses CPU time and memory to create an SoPath for every node found. If you expect to find many nodes, especially if you just need the node object and not a path, then you should consider using SoCallbackAction instead.
For example, if you want to count all the shape nodes in the scene graph, you could use an SoSearchAction similar to the second example below. The number of shapes would conveniently be the number of paths created by the action, but you wouldn't actually make any use of the path information. Using SoCallbackAction would be a little more work, because you have to implement a counter in a callback method. But it would be much more efficient because the action simply calls your callback when each shape node is visited during the traversal.

EXAMPLE

SEE ALSO

SoPath, SoBaseKit, SoSearchPathAction, SoSearchStepAction


Member Enumeration Documentation

Enum that defines which paths to return.

Enumerator:
FIRST 

Return only the first path found (default).

LAST 

Return only the last path found.

ALL 

Return all paths found.

Enum that defines the search criterion.

Enumerator:
NODE 

Search for a particular node instance.

TYPE 

Search for a particular type of node.

NAME 

Search for a node with a particular name.


Constructor & Destructor Documentation

SoSearchAction::SoSearchAction (  ) 

Constructor.


Member Function Documentation

virtual void SoSearchAction::clearApplyResult (  )  [virtual]

When applied, an action may reference nodes or create objects (e.g. SoPath) that reference nodes. This is especially true for SoSearchAction and SoRayPickAction. These references will prevent the nodes from being destroyed and so may appear to be a "memory leak".All references are cleared when the action is destroyed or re-applied. However it may be useful to clear them explicitly to remove references to nodes.

See also reset()

Reimplemented from SoAction.

static SoType SoSearchAction::getClassTypeId (  )  [static]

Returns the type identifier for this class.

Reimplemented from SoAction.

Reimplemented in SoSearchPathAction, and SoSearchStepAction.

int SoSearchAction::getFind (  )  [inline]

Returns what to look for.

Interest SoSearchAction::getInterest (  )  const [inline]

Returns which paths to return.

const SbName& SoSearchAction::getName (  )  const [inline]

Returns the name of the node to search for.

SoNode* SoSearchAction::getNode (  )  const [inline]

Returns the node to search for.

SoPath* SoSearchAction::getPath (  )  const [inline]

Returns resulting path, or NULL if no path was found.

This should be used if the interest is FIRST or LAST.

SoPathList& SoSearchAction::getPaths (  )  [inline]

Returns resulting path list.

This should be used if the interest is ALL.

SoType SoSearchAction::getType ( SbBool derivedIsOk  )  const [inline]

Returns the node type to search for.

virtual SoType SoSearchAction::getTypeId (  )  const [virtual]

Returns the type identifier for this specific instance.

Implements SoTypedObject.

Reimplemented in SoSearchPathAction, and SoSearchStepAction.

SbBool SoSearchAction::isSearchingAll (  )  const [inline]

Returns FALSE if searching uses regular traversal, TRUE if it traverses every single node.

Default is FALSE.

virtual void SoSearchAction::reset (  )  [virtual]

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

Reimplemented in SoSearchPathAction.

void SoSearchAction::setFind ( int  what  )  [inline]

Sets 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 SoSearchAction::setInterest ( Interest  i  )  [inline]

Sets which paths to return.

Default is FIRST.

void SoSearchAction::setName ( const SbName n  ) 

Sets the name of the node to search for.

void SoSearchAction::setNode ( SoNode n  ) 

Sets the node to search for.

void SoSearchAction::setSearchingAll ( SbBool  flag  )  [inline]

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

void SoSearchAction::setType ( SoType  t,
SbBool  derivedIsOk = TRUE 
)

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


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

Open Inventor Toolkit reference manual, generated on 15 Mar 2023
Copyright © Thermo Fisher Scientific All rights reserved.
http://www.openinventor.com/