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

                                                                            SoSearchAction(3IV)()