com.openinventor.inventor.actions

Class SoHandleEventAction

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.actions.SoAction

com.openinventor.inventor.actions.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.

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.

A node can get the event currently being handled by calling getEvent(). A node can also find out what, if any, geometry is under the cursor by calling the getPickedPoint() method. The handle event action will automatically apply an SoRayPickAction to the scene graph and remember the result in case other nodes make the same query during the traversal. If a node needs to apply the pick action itself, it can get the appropriate root node by calling getPickRoot().

NOTE: The SoRayPickAction applied by the handle event action 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).

Sets: SoViewportRegionElement

See also:

SoEvent, SoEventCallback, SoPickedPoint, SoRayPickAction

Nested Class Summary

Nested classes/interfaces inherited from class com.openinventor.inventor.actions.SoAction

SoAction.AppliedCodes, SoAction.DistribModes, SoAction.PathCodes, SoAction.PathIndices

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields inherited from class com.openinventor.inventor.actions.SoAction

ALL, BELOW_PATH, CLUSTER_ONLY, IN_PATH, LOCAL_ONLY, NO_PATH, NODE, OFF_PATH, PATH, PATH_LIST

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
static void	enableElement(java.lang.Class<? extends Inventor> t, int stkIndex)
void	enableRadiusForTriangles(boolean flag) Enable pick radius for triangle-based shapes.
SoEvent	getEvent() Returns the event being handled.
SoNode	getGrabber() Returns the node that is currently grabbing events, or NULL if there is none.
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.
java.util.Vector<SoPickedPoint>	getPickedPointList() Returns a list of objects intersected by a picking operation, sorted from nearest to farthest.
float	getPickRadius() Returns the radius (in pixels) around the viewport-space point through which the ray passes when doing ray picking.
SoNode	getPickRoot() Returns the root node used for initiating a pick action for those nodes that want to know what is under the cursor.
SbViewportRegion	getViewportRegion() Returns current viewport region to use for action.
boolean	isHandled() Returns whether any node has yet handled the event.
void	releaseGrabber() Releases the grab.
void	setEvent(SoEvent ev) Sets the event being handled.
void	setGrabber(SoNode node) Initiates grabbing of future events.
void	setHandled() Sets whether any node has yet handled the event.
void	setPickedPoint() Calls setPickedPoint((com.openinventor.inventor.SoPickedPoint)null).
void	setPickedPoint(SoPickedPoint point) Set the SoPickedPoint object that will be returned by getPickedPoint.
void	setPickRadius(float radiusInPixels) Sets the radius (in pixels) around the viewport-space point through which the ray passes when doing ray picking.
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.
void	setViewportRegion(SbViewportRegion newRegion) Sets current viewport region to use for action.

Methods inherited from class com.openinventor.inventor.actions.SoAction

apply, apply, clearApplyResult, forwardTraversal, getContinueActionInBranchFlag, getCurPath, getNodeAppliedTo, getOriginalPathListAppliedTo, getPathAppliedTo, getPathCode, getPathListAppliedTo, getPipeId, getSceneManager, getState, getWhatAppliedTo, hasTerminated, invalidateState, isBeingApplied, isLastPathListAppliedTo, isUsingAlternateRep, nullAction, postDelayedTraversal, preDelayedTraversal, resetContinueActionInBranchFlag, setPipeId, setSceneManager, setUpState, stopActionInBranch, traverse, useAlternateRep

Methods inherited from class com.openinventor.inventor.Inventor

dispose, getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

enableElement

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

getGrabber

public SoNode getGrabber()

Returns the node that is currently grabbing events, or NULL if there is none.

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.

setViewportRegion

public void setViewportRegion(SbViewportRegion newRegion)

Sets current viewport region to use for action.

getViewportRegion

public SbViewportRegion getViewportRegion()

Returns current viewport region to use for action.

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.

isHandled

public boolean isHandled()

Returns whether any node has yet handled the event.

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.

releaseGrabber

public void releaseGrabber()

Releases the grab.

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.

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.

setHandled

public void setHandled()

Sets whether any node has yet handled the event.

setEvent

public void setEvent(SoEvent ev)

Sets the event being handled.

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

getPickedPointList

public java.util.Vector<SoPickedPoint> getPickedPointList()

Returns a list of objects intersected by a picking operation, sorted from nearest to farthest.

getPickRadius

public float getPickRadius()

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

getEvent

public SoEvent getEvent()

Returns the event being handled.

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.