NAME

       SoEventCallback — node which invokes callbacks for events

INHERITS FROM

       SoBase > SoFieldContainer > SoNode > SoEventCallback

SYNOPSIS

       #include <Inventor/nodes/SoEventCallback.h>

     typedef void        SoEventCallbackCB(void *userData, SoEventCallback *node)

          Methods from class SoEventCallback:

     static SoType          getClassTypeId()
                            SoEventCallback()
     void                   setPath(SoPath *path)
     const SoPath *         getPath()
     void                   addEventCallback(SoType   eventType,   SoEventCallbackCB   *f,   void
                                 *userData = NULL)
     void                   removeEventCallback(SoType  eventType,  SoEventCallbackCB  *f,   void
                                 *userData = NULL)
     SoHandleEventAction *  getAction() const
     const SoEvent *        getEvent() const
     const SoPickedPoint *  getPickedPoint() const
     void                   setHandled()
     SbBool                 isHandled() const
     void                   grabEvents()
     void                   releaseEvents()

          Methods from class SoNode:

     void                setOverride(SbBool state)
     SbBool              isOverride() const
     SoNode *            copy(SbBool copyConnections = FALSE) const
     virtual SbBool      affectsState() const
     static SoNode *     getByName(const SbName &name)
     static int          getByName(const SbName &name, SoNodeList &list)

          Methods from class SoFieldContainer:

     void                setToDefaults()
     SbBool              hasDefaultValues() const
     SbBool              fieldsAreEqual(const SoFieldContainer *fc) const
     void                copyFieldValues(const  SoFieldContainer  *fc,  SbBool  copyConnections =
                              FALSE)
     SbBool              set(const char *fieldDataString)
     void                get(SbString &fieldDataString)
     virtual int         getFields(SoFieldList &resultList) const
     virtual SoField *   getField(const SbName &fieldName) const
     SbBool              getFieldName(const SoField *field, SbName &fieldName) const
     SbBool              isNotifyEnabled() const
     SbBool              enableNotify(SbBool flag)

          Methods from class SoBase:

     void                ref()
     void                unref() const
     void                unrefNoDelete() const
     void                touch()
     virtual SoType      getTypeId() const
     SbBool              isOfType(SoType type) const
     virtual void        setName(const SbName &name)
     virtual SbName      getName() const

DESCRIPTION

       SoEventCallback   will   invoke   application   supplied   callback    functions    during
       SoHandleEventAction  traversal.  Methods  allow  the application to specify which Inventor
       events should trigger callbacks, and which path must be picked, if any, for  the  callback
       invocation  to  occur. The application callback is able to get information about the event
       and the pick detail, and may grab events, release events, and set whether  the  event  was
       handled.

       If  you  register  more  than  one  callback  function in an SoEventCallback node, all the
       callback functions will be invoked when an event occurs, even  if  one  of  the  callbacks
       handles  the  event. However, if the event is handled by any of the callback functions, no
       other node in the scene graph will see the event.

METHODS

     static SoType          getClassTypeId()
          Return the type id for the SoEventCallback class.

                            SoEventCallback()
          Constructor creates an event callback node with no event interest and a NULL path.

     void                   setPath(SoPath *path)
     const SoPath *         getPath()
          Set and get the path which must be picked in order for the callbacks to be invoked.  If
          the  path  is  NULL,  the  callbacks  will  be  invoked for every interesting event, as
          specified by addEventCallback(),  regardless of what is picked.  The  setPath()  method
          makes its own copy of the passed path.

     void                   addEventCallback(SoType   eventType,   SoEventCallbackCB   *f,   void
                                 *userData = NULL)
     void                   removeEventCallback(SoType  eventType,  SoEventCallbackCB  *f,   void
                                 *userData = NULL)
          Specifies the callback functions to be invoked for different event types. When invoked,
          the callback function will be passed  the  userData,  along  with  a  pointer  to  this
          SoEventCallback  node. For example, passing SoMouseButtonEvent::getClassTypeId()  means
          callbacks will be invoked only when a mouse button  is  pressed  or  released.  Passing
          SoEvent::getClassTypeId()  for  the eventType will cause the callback to be invoked for
          every event which passes through this event callback node.

     SoHandleEventAction *  getAction() const
          Returns the SoHandleEventAction currently traversing this node, or NULL if traversal is
          not taking place. This should be called only from callback functions.

     const SoEvent *        getEvent() const
          Returns  the  event  currently being handled, or NULL if traversal is not taking place.
          This should be called only from callback functions.

     const SoPickedPoint *  getPickedPoint() const
          Returns pick information during SoHandleEventAction traversal, or NULL if traversal  is
          not taking place. This should be called only from callback functions.

     void                   setHandled()
          Tells  the node the event was handled. The callback function is responsible for setting
          whether the event was handled or not. If there  is  more  than  one  callback  function
          registered  with  an  SoEventCallback  node, all of them will be invoked, regardless of
          whether one has handled the event or not. This should  be  called  only  from  callback
          functions.

     SbBool                 isHandled() const
          Returns  whether  the  event has been handled. This should be called only from callback
          functions.

     void                   grabEvents()
     void                   releaseEvents()
          Tells the event callback node to grab events or release the grab. While  grabbing,  the
          node  will consume all events; however, each callback function will only be invoked for
          events of interest.

FILE FORMAT/DEFAULTS

       EventCallback {
       }

SEE ALSO

       SoInteraction, SoSelection, SoHandleEventAction, SoDragger

                                                                           SoEventCallback(3IV)()