NAME

       SoHandleEventAction — allows nodes in a graph to receive input events

INHERITS FROM

       SoAction > SoHandleEventAction

SYNOPSIS

       #include <Inventor/actions/SoHandleEventAction.h>

          Methods from class SoHandleEventAction:

                                SoHandleEventAction(const SbViewportRegion &viewportRegion)
     void                       setViewportRegion(const SbViewportRegion &newRegion)
     const SbViewportRegion &   getViewportRegion() const
     void                       setEvent(const SoEvent *ev)
     const SoEvent *            getEvent() const
     void                       setHandled()
     SbBool                     isHandled() const
     void                       setGrabber(SoNode *node)
     void                       releaseGrabber()
     SoNode *                   getGrabber() const
     void                       setPickRoot(SoNode *node)
     SoNode *                   getPickRoot() const
     void                       setPickRadius(float radiusInPixels)
     const SoPickedPoint *      getPickedPoint()
     const SoPickedPointList &  getPickedPointList()

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

METHODS

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

     void                       setViewportRegion(const SbViewportRegion &newRegion)
     const SbViewportRegion &   getViewportRegion() const
          Sets/returns current viewport region to use for action.

     void                       setEvent(const SoEvent *ev)
     const SoEvent *            getEvent() const
          Sets/returns the event being handled.

     void                       setHandled()
     SbBool                     isHandled() const
          Sets/returns whether any node has yet handled the event.

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

     void                       releaseGrabber()
          Releases the grab.

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

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

     void                       setPickRadius(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 getPickedPoint()  is called.  The
          pick radius set here is used when testing the ray against lines and points.

     const SoPickedPoint *      getPickedPoint()
          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 &  getPickedPointList()
          Returns a list of objects intersected by a picking operation, sorted  from  nearest  to
          farthest.

SEE ALSO

       SoEvent, SoPickedPoint, SoRayPickAction

                                                                       SoHandleEventAction(3IV)()