Package com.openinventor.inventor.actions

Class SoHandleEventAction

  • public class SoHandleEventAction
extends SoAction
    Allows nodes in a graph to receive input events. This class is used to allow nodes in a scene graph to handle input events. It is usually invoked from a component derived from SoWinRenderArea when the component receives a window system event. SoSceneManager automatically creates a handle event action and provides a convenience method processEvent() to pass events to its managed scene graph. The Open Inventor viewer classes use this method to pass events to the scene graph in selection mode.

    A node can get the event currently being handled by calling getEvent().

    Manipulator, dragger and selection nodes respond to and process events. Most group nodes just pass the event to their children, while most other nodes simply ignore the action entirely. The SoEventCallback node invokes a callback / delegate method when traversed by a handle event action processing a specific type of event. This is the primary mechanism for handling event input in Open Inventor. 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. Draggers use this mechanism to ensure that they see the "finish" (e.g. mouse button up) event for their interaction.

    Picking

    A node can conveniently find out what, if any, geometry is under the cursor by calling the getPickedPoint() method. Applications can do this in the callback function assigned to an SoEventCallback node. The first time this method is called during a handle event traversal, the handle event action will automatically apply its internal SoRayPickAction to the scene graph returned by getPickRoot(). The result is stored in case other nodes make the same query during the same traversal. The stored result can be cleared by calling clearApplyResult().

    Some, but not all, options can be modified on the internal pick action (see for example setPickRadius()). Note that the internal pick action does not compute texture coordinates or normal vector for the picked point. Thus, getPickedPoint().getNormal() returns (0,0,0) and getPickedPoint().getTextureCoords() returns (0,0,0,0).

    If a node needs to apply the pick action itself, for example to set different options, it can get the appropriate root node by calling getPickRoot().

    To use GPU picking on compatible shapes, it is mandatory to set the pick radius to 0, see setPickRadius(float radiusInPixels). Compatible shapes are described in the SoRayPickAction section Picking Algorithms.

    Sets: SoViewportRegionElement

    See Also:
    SoEvent, SoEventCallback, SoPickedPoint, SoRayPickAction

    • Constructor Detail

      • SoHandleEventAction

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

    • Method Detail

      • setPickedPoint

        public void setPickedPoint()
        Calls setPickedPoint((com.openinventor.inventor.SoPickedPoint)null).

      • setHandled

        public void setHandled()
        Sets whether any node has yet handled the event.

      • setPickedPoint

        public void setPickedPoint​(SoPickedPoint point)
        Set the SoPickedPoint object that will be returned by getPickedPoint. Useful in some special cases where a pick operation has already been done and the picked point is known. Avoids doing the pick operation again. In other words, events will be processed as if the specified point had been picked. Reset the picked point by calling with NULL.

      • getEvent

        public SoEvent getEvent()
        Returns the event being handled.

      • setEvent

        public void setEvent​(SoEvent ev)
        Sets the event being handled.

      • getPickRoot

        public SoNode getPickRoot()
        Returns the root node used for initiating a pick action for those nodes that want to know what is under the cursor.

      • getViewportRegion

        public SbViewportRegion getViewportRegion()
        Returns current viewport region to use for action.

      • setViewportRegion

        public void setViewportRegion​(SbViewportRegion newRegion)
        Sets current viewport region to use for action.

      • enableElement

        public static void enableElement​(java.lang.Class<? extends Inventor> t,
                                 int stkIndex)

      • setPickRoot

        public void setPickRoot​(SoNode node)
        Sets the root node used for initiating a pick action for those nodes that want to know what is under the cursor.

      • getPickedPoint

        public 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, an 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.

        Note: The applied SoRayPickAction does not compute texture coordinates and normal vector for the picked point. Thus, getPickedPoint().getNormal() returns (0,0,0) and getPickedPoint().getTextureCoords() returns (0,0,0,0).

      • enableRadiusForTriangles

        public void enableRadiusForTriangles​(boolean flag)
        Enable pick radius for triangle-based shapes. If true, the radius of the ray specified by setPickRadius() is taken in account when checking for a ray intersection with triangle-based shapes (e.g. SoIndexedFaceSet). Otherwise, the pick radius for these shapes is 1 pixel regardless of the specified pick radius. Default is false for performance.

      • setPickRadius

        public void setPickRadius​(float radiusInPixels)
        Sets the radius (in pixels) around the viewport-space point through which the ray passes when doing ray picking. Default is 5 pixels. Ray picking is performed when getPickedPoint() is called.

        Note: By default the pick radius set here is only used when testing the ray against lines and points. To enable pick radius for triangle based geometry use the enableRadiusForTriangles() method.

      • getPickRadius

        public float getPickRadius()
        Returns the radius (in pixels) around the viewport-space point through which the ray passes when doing ray picking.

      • setGrabber

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

      • isHandled

        public boolean isHandled()
        Returns whether any node has yet handled the event.

      • releaseGrabber

        public void releaseGrabber()
        Releases the grab.

      • getGrabber

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

      • getPickedPointList

        public java.util.Vector<SoPickedPoint> getPickedPointList()
        Returns a list of objects intersected by a picking operation, sorted from nearest to farthest.