SoSearchAction(3IV)

NAME
     SoSearchAction (SoSearchAct) - searches for nodes in a scene graph

INHERITS FROM
     SoAction > SoSearchAction

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

     typedef SoSearchAction  SoSearchAct

     enum SoSearchActionLookFor {
          SO_SEARCH_ACT_NODE  Search for a particular node (by pointer)
          SO_SEARCH_ACT_TYPE  Search for a particular type of node
          SO_SEARCH_ACT_NAME  Search for a node with a particular name
     }

     enum SoSearchActionInterest {
          SO_SEARCH_ACT_FIRST  Return only the first path found
          SO_SEARCH_ACT_LAST   Return only the last path found
          SO_SEARCH_ACT_ALL    Return all paths found
     }

          Functions from class SoSearchAction:

     SoSearchAction *    SoSearchActCreate()
     void                SoSearchActSetNode(SoSearchAct *this, SoNode *n)
     SoNode *            SoSearchActGetNode(const SoSearchAct *this)
     void                SoSearchActSetType(SoSearchAct *this, SoType t,
                              SbBool derivedIsOk = TRUE)
     SoType              SoSearchActGetType(const SoSearchAct *this, SbBool
                              *derivedIsOk)
     void                SoSearchActSetName(SoSearchAct *this, const char *n)
     const SbName *      SoSearchActGetName(const SoSearchAct *this)
     void                SoSearchActSetFind(SoSearchAct *this, int what)
     int                 SoSearchActGetFind(SoSearchAct *this)
     void                SoSearchActSetInterest(SoSearchAct *this, Interest
                              interest)
     Interest            SoSearchActGetInterest(const SoSearchAct *this)
     void                SoSearchActSetSearchAll(SoSearchAct *this, SbBool
                              flag)
     SbBool              SoSearchActIsSearchAll(const SoSearchAct *this)
     SoPath *            SoSearchActGetPath(const SoSearchAct *this)
     SoPathList *        SoSearchActGetPaths(SoSearchAct *this)
     void                SoSearchActReset(SoSearchAct *this)

          Functions from class SoAction:

     void                SoSearchActApply(SoSearchAct *this, SoNode *node)
     void                SoSearchActApplyPath(SoSearchAct *this, SoPath *path)
     void                SoSearchActApplyPathList(SoSearchAct *this, const
                              SoPathList *pathList, SbBool obeysRules = FALSE)
     SoType              SoSearchActGetClassTypeId()
     SoType              SoSearchActGetTypeId(SoSearchAct *this)
     SbBool              SoSearchActIsOfType(SoSearchAct *this, SoType type)
     void                SoSearchActInvalidateState(SoSearchAct *this)


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
     SoKitIsSearchingChildren() and SoKitSetSearchingChildren(), which allow
     you to query and control this behavior.

FUNCTIONS
     SoSearchAction *    SoSearchActCreate()
          Constructor.

     void                SoSearchActSetNode(SoSearchAct *this, SoNode *n)
     SoNode *            SoSearchActGetNode(const SoSearchAct *this)
          Sets/returns the node to search for.

     void                SoSearchActSetType(SoSearchAct *this, SoType t,
                              SbBool derivedIsOk = TRUE)
     SoType              SoSearchActGetType(const SoSearchAct *this, SbBool
                              *derivedIsOk)
          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                SoSearchActSetName(SoSearchAct *this, const char *n)
     const SbName *      SoSearchActGetName(const SoSearchAct *this)
          Sets/returns the name of the node to search for.

     void                SoSearchActSetFind(SoSearchAct *this, int what)
     int                 SoSearchActGetFind(SoSearchAct *this)
          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                SoSearchActSetInterest(SoSearchAct *this, Interest
                              interest)
     Interest            SoSearchActGetInterest(const SoSearchAct *this)
          Sets/returns which paths to return. Default is FIRST.

     void                SoSearchActSetSearchAll(SoSearchAct *this, SbBool
                              flag)

     SbBool              SoSearchActIsSearchAll(const SoSearchAct *this)
          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 *            SoSearchActGetPath(const SoSearchAct *this)
          Returns resulting path, or NULL if no path was found. This should be
          used if the interest is FIRST or LAST.

     SoPathList *        SoSearchActGetPaths(SoSearchAct *this)
          Returns resulting path list. This should be used if the interest is
          ALL.

     void                SoSearchActReset(SoSearchAct *this)
          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