SoHandleEventAction Class Reference
[Actions]
Allows nodes in a graph to receive input events. More...
#include <Inventor/actions/SoHandleEventAction.h>
Public Member Functions | |
| virtual SoType | getTypeId () const |
| SoHandleEventAction (const SbViewportRegion &viewportRegion) | |
| void | setViewportRegion (const SbViewportRegion &newRegion) |
| const SbViewportRegion & | getViewportRegion () const |
| virtual void | clearApplyResult () |
| 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) |
| float | getPickRadius () const |
| void | enableRadiusForTriangles (SbBool flag) |
| const SoPickedPoint * | getPickedPoint () |
| const SoPickedPointList & | getPickedPointList () |
Static Public Member Functions | |
| static SoType | getClassTypeId () |
Detailed Description
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 & Destructor Documentation
| SoHandleEventAction::SoHandleEventAction | ( | const SbViewportRegion & | viewportRegion | ) |
Constructor takes viewport region to use; this is needed to perform a pick operation when requested.
Member Function Documentation
| virtual void SoHandleEventAction::clearApplyResult | ( | ) | [virtual] |
When applied, an action may reference nodes or create objects (e.g. SoPath) that reference nodes. This is especially true for SoSearchAction and SoRayPickAction. These references will prevent the nodes from being destroyed and so may appear to be a "memory leak".All references are cleared when the action is destroyed or re-applied. However it may be useful to clear them explicitly to remove references to nodes.
Reimplemented from SoAction.
| void SoHandleEventAction::enableRadiusForTriangles | ( | SbBool | 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.
| static SoType SoHandleEventAction::getClassTypeId | ( | ) | [static] |
Returns the type identifier for this class.
Reimplemented from SoAction.
| const SoEvent* SoHandleEventAction::getEvent | ( | ) | const [inline] |
Returns the event being handled.
| SoNode* SoHandleEventAction::getGrabber | ( | ) | const [inline] |
Returns the node that is currently grabbing events, or NULL if there is none.
| const SoPickedPoint* SoHandleEventAction::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).
| const SoPickedPointList& SoHandleEventAction::getPickedPointList | ( | ) |
Returns a list of objects intersected by a picking operation, sorted from nearest to farthest.
| float SoHandleEventAction::getPickRadius | ( | ) | const [inline] |
Returns the radius (in pixels) around the viewport-space point through which the ray passes when doing ray picking.
| SoNode* SoHandleEventAction::getPickRoot | ( | ) | const [inline] |
Returns the root node used for initiating a pick action for those nodes that want to know what is under the cursor.
| virtual SoType SoHandleEventAction::getTypeId | ( | ) | const [virtual] |
Returns the type identifier for this specific instance.
Implements SoTypedObject.
| const SbViewportRegion& SoHandleEventAction::getViewportRegion | ( | ) | const [inline] |
Returns current viewport region to use for action.
| SbBool SoHandleEventAction::isHandled | ( | ) | const [inline] |
Returns whether any node has yet handled the event.
| void SoHandleEventAction::releaseGrabber | ( | ) | [inline] |
Releases the grab.
| void SoHandleEventAction::setEvent | ( | const SoEvent * | ev | ) | [inline] |
Sets the event being handled.
| void SoHandleEventAction::setGrabber | ( | SoNode * | node | ) |
Initiates grabbing of future events.
All events will be sent to the given node until the grab is released.
| void SoHandleEventAction::setHandled | ( | ) | [inline] |
Sets whether any node has yet handled the event.
| void SoHandleEventAction::setPickRadius | ( | float | radiusInPixels | ) | [inline] |
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.
| void SoHandleEventAction::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 SoHandleEventAction::setViewportRegion | ( | const SbViewportRegion & | newRegion | ) |
Sets current viewport region to use for action.
The documentation for this class was generated from the following file:
- Inventor/actions/SoHandleEventAction.h