SoHandleEventAction(3IV)

NAME
     SoHandleEventAction (SoEvAct) - allows nodes in a graph to receive input
     events

INHERITS FROM
     SoAction > SoHandleEventAction

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

     typedef SoHandleEventAction  SoEvAct

          Functions from class SoHandleEventAction:

     SoHandleEventAction *      SoEvActCreate(const SbViewportRegion
                                     *viewportRegion)
     void                       SoEvActSetVPReg(SoEvAct *this, const
                                     SbViewportRegion *newRegion)
     const SbViewportRegion *   SoEvActGetVPReg(const SoEvAct *this)
     void                       SoEvActSetEv(SoEvAct *this, const SoEvent *ev)
     const SoEvent *            SoEvActGetEv(const SoEvAct *this)
     void                       SoEvActSetHandled(SoEvAct *this)
     SbBool                     SoEvActIsHandled(const SoEvAct *this)
     void                       SoEvActSetGrabber(SoEvAct *this, SoNode *node)
     void                       SoEvActReleaseGrabber(SoEvAct *this)
     SoNode *                   SoEvActGetGrabber(const SoEvAct *this)
     void                       SoEvActSetPickRoot(SoEvAct *this, SoNode
                                     *node)
     SoNode *                   SoEvActGetPickRoot(const SoEvAct *this)
     void                       SoEvActSetPickRadius(SoEvAct *this, float
                                     radiusInPixels)
     const SoPickedPoint *      SoEvActGetPickPt(SoEvAct *this)
     const SoPickedPointList *  SoEvActGetPickPtList(SoEvAct *this)

          Functions from class SoAction:

     void                SoEvActApply(SoEvAct *this, SoNode *node)
     void                SoEvActApplyPath(SoEvAct *this, SoPath *path)
     void                SoEvActApplyPathList(SoEvAct *this, const SoPathList
                              *pathList, SbBool obeysRules = FALSE)
     SoType              SoEvActGetClassTypeId()
     SoType              SoEvActGetTypeId(SoEvAct *this)
     SbBool              SoEvActIsOfType(SoEvAct *this, SoType type)
     void                SoEvActInvalidateState(SoEvAct *this)


DESCRIPTION
     This class is used to allow nodes in a scene graph to handle input
     events. It is usually invoked from a component derived from
     SoXtRenderArea when the component receives a window system event.

     Manipulator, dragger and selection nodes respond to and process events.
     Most other group nodes just pass the event to their children, while most
     other nodes simply ignore the action entirely. Once a node has indicated
     to the action that it has handled the event, traversal stops.

     A node that handles an event can also grab future events. Once it has
     done so, all events will be sent directly to that node, with no traversal
     taking place, until the node releases the grab.

FUNCTIONS
     SoHandleEventAction *      SoEvActCreate(const SbViewportRegion
                                     *viewportRegion)
          Constructor takes viewport region to use; this is needed to perform
          a pick operation when requested.

     void                       SoEvActSetVPReg(SoEvAct *this, const
                                     SbViewportRegion *newRegion)
     const SbViewportRegion *   SoEvActGetVPReg(const SoEvAct *this)
          Sets/returns current viewport region to use for action.

     void                       SoEvActSetEv(SoEvAct *this, const SoEvent *ev)
     const SoEvent *            SoEvActGetEv(const SoEvAct *this)
          Sets/returns the event being handled.

     void                       SoEvActSetHandled(SoEvAct *this)
     SbBool                     SoEvActIsHandled(const SoEvAct *this)
          Sets/returns whether any node has yet handled the event.

     void                       SoEvActSetGrabber(SoEvAct *this, SoNode *node)
          Initiates grabbing of future events. All events will be sent to the
          given node until the grab is released.

     void                       SoEvActReleaseGrabber(SoEvAct *this)
          Releases the grab.

     SoNode *                   SoEvActGetGrabber(const SoEvAct *this)
          Returns the node that is currently grabbing events, or NULL if there
          is none.

     void                       SoEvActSetPickRoot(SoEvAct *this, SoNode
                                     *node)
     SoNode *                   SoEvActGetPickRoot(const SoEvAct *this)
          Sets/returns the root node used for initiating a pick action for
          those nodes that want to know what is under the cursor.

     void                       SoEvActSetPickRadius(SoEvAct *this, float
                                     radiusInPixels)
          Set the radius (in pixels) around the viewport-space point through
          which the ray passes when doing ray picking. Ray picking is
          performed when  SoEvActGetPickPt() is called. The pick radius set
          here is used when testing the ray against lines and points.

     const SoPickedPoint *      SoEvActGetPickPt(SoEvAct *this)
          Returns the frontmost object hit (as an SoPickedPoint) by performing
          a pick based on the mouse location specified in the event for which
          the action is being applied. The first time this is called for a
          particular event, a SoRayPickAction is applied to find this object;
          subsequent calls for the same event return the same information. The
          storage for the picked point remains valid as long as the action is
          not re-applied or deleted.

     const SoPickedPointList *  SoEvActGetPickPtList(SoEvAct *this)
          Returns a list of objects intersected by a picking operation, sorted
          from nearest to farthest.


SEE ALSO
     SoEvent, SoPickedPoint, SoRayPickAction