OSGUIsh  0.3.1
Public Types | Public Member Functions | Private Types | Private Member Functions | Private Attributes
OSGUIsh::EventHandler Class Reference

#include <EventHandler.hpp>

List of all members.

Public Types

typedef std::vector
< osg::Node::NodeMask > 		NodeMasks_t
 A type representing a sequence of node masks.
typedef boost::signal< void(HandlerParams &)> Signal_t
typedef boost::shared_ptr
< Signal_t > 		SignalPtr
 A (smart) pointer to a Signal_t;.

Public Member Functions

 EventHandler (double pickerRadius=0.0, const FocusPolicyFactory &kbdPolicyFactory=FocusPolicyFactoryMason< ManualFocusPolicy >(), const FocusPolicyFactory &wheelPolicyFactory=FocusPolicyFactoryMason< ManualFocusPolicy >())
bool handle (const osgGA::GUIEventAdapter &ea, osgGA::GUIActionAdapter &)
void setPickingMask (osg::Node::NodeMask newMask)
void setPickingMasks (osg::Node::NodeMask newMask1, osg::Node::NodeMask newMask2)
void setPickingMasks (osg::Node::NodeMask newMask1, osg::Node::NodeMask newMask2, osg::Node::NodeMask newMask3)
void setPickingMasks (const NodeMasks_t &newMasks)
void addNode (const NodePtr node)
SignalPtr getSignal (const NodePtr node, Event signal)
void ignoreBackFaces (bool ignore=true)
void setKeyboardFocus (const NodePtr node)
void setMouseWheelFocus (const NodePtr node)
void setKeyboardFocusPolicy (const FocusPolicyFactory &policyFactory)
void setMouseWheelFocusPolicy (const FocusPolicyFactory &policyFactory)

Private Types

enum  MouseButton { LEFT_MOUSE_BUTTON, MIDDLE_MOUSE_BUTTON, RIGHT_MOUSE_BUTTON, MOUSE_BUTTON_COUNT }
 The buttons of a mouse. More...
typedef std::map< Event,
SignalPtr > 		SignalCollection_t
 Type mapping an event type to the signal object.
typedef std::map< NodePtr,
SignalCollection_t > 		SignalsMap_t
 Type mapping nodes to the collection of signals associated to it.

Private Member Functions

NodePtr getObservedNode (const osg::NodePath &nodePath)
void handleFrameEvent (osg::View *view, const osgGA::GUIEventAdapter &ea)
void handlePushEvent (const osgGA::GUIEventAdapter &ea)
void handleReleaseEvent (const osgGA::GUIEventAdapter &ea)
void handleKeyDownEvent (const osgGA::GUIEventAdapter &ea)
void handleKeyUpEvent (const osgGA::GUIEventAdapter &ea)
void handleScrollEvent (const osgGA::GUIEventAdapter &ea)
MouseButton getMouseButton (const osgGA::GUIEventAdapter &ea)
void updatePickingData (osg::View *view, const osgGA::GUIEventAdapter &ea)
void updatePickingDataLine (osg::View *view, const osgGA::GUIEventAdapter &ea)
void updatePickingDataPolytope (osg::View *view, const osgGA::GUIEventAdapter &ea)

Private Attributes

double pickerRadius_
bool ignoreBackFaces_
NodeMasks_t pickingMasks_
std::map
< osgGA::GUIEventAdapter::EventType,
bool > 		handleReturnValues_
SignalsMap_t signals_
Intersection_t hitUnderMouse_
NodePtr nodeUnderMouse_
 The node currently under the mouse pointer.
osg::Vec3 positionUnderMouse_
NodePtr prevNodeUnderMouse_
 The node previously under the mouse pointer.
osg::Vec3 prevPositionUnderMouse_
NodePtr nodeThatGotMouseDown_ [MOUSE_BUTTON_COUNT]
NodePtr nodeThatGotClick_ [MOUSE_BUTTON_COUNT]
double timeOfLastClick_ [MOUSE_BUTTON_COUNT]
NodePtr kbdFocus_
 The node receiving keyboard events.
FocusPolicyPtr kbdFocusPolicy_
 The focus policy for keyboard-related events.
NodePtr wheelFocus_
 The node receiving mouse wheel events.
FocusPolicyPtr wheelFocusPolicy_
 The focus policy for mouse wheel-related events.

Detailed Description

An event handler providing GUI-like events for nodes. The EventHandler has an internal list of nodes being "observed". Every observed node has a collection of signals associated to it. These signals represent the events that can be generated for the node.

Definition at line 81 of file EventHandler.hpp.

Member Typedef Documentation

typedef std::vector<osg::Node::NodeMask> OSGUIsh::EventHandler::NodeMasks_t

A type representing a sequence of node masks.

Definition at line 115 of file EventHandler.hpp.

typedef boost::signal<void (HandlerParams&)> OSGUIsh::EventHandler::Signal_t

A type representing a signal used in OSGUIsh. This signal returns nothing and takes a HandlerParams, which packs all relevant data for an event handler function.

Definition at line 191 of file EventHandler.hpp.

typedef std::map<Event, SignalPtr> OSGUIsh::EventHandler::SignalCollection_t [private]

Type mapping an event type to the signal object.

Definition at line 346 of file EventHandler.hpp.

typedef boost::shared_ptr<Signal_t> OSGUIsh::EventHandler::SignalPtr

A (smart) pointer to a Signal_t;.

Definition at line 194 of file EventHandler.hpp.

typedef std::map<NodePtr, SignalCollection_t > OSGUIsh::EventHandler::SignalsMap_t [private]

Type mapping nodes to the collection of signals associated to it.

Definition at line 349 of file EventHandler.hpp.

Member Enumeration Documentation

enum OSGUIsh::EventHandler::MouseButton [private]

The buttons of a mouse.

Enumerator:
LEFT_MOUSE_BUTTON 

The left button.

MIDDLE_MOUSE_BUTTON 

The middle button.

RIGHT_MOUSE_BUTTON 

The right button.

MOUSE_BUTTON_COUNT 

The number of buttons in a mouse.

Definition at line 391 of file EventHandler.hpp.

Constructor & Destructor Documentation

OSGUIsh::EventHandler::EventHandler ( double  pickerRadius = 0.0,
const FocusPolicyFactory &  kbdPolicyFactory = FocusPolicyFactoryMason< ManualFocusPolicy >(),
const FocusPolicyFactory &  wheelPolicyFactory = FocusPolicyFactoryMason< ManualFocusPolicy >() 
)

Constructs an EventHandler.

Parameters:
pickerRadiusThe radius of the picking region, as a percentage of the screen width. When this is zero (the default), picking is done with an osgUtil::LineSegmentIntersector; this is efficient, but cannot pick points and lines. When this is greater than zero, an osgUtil::PolytopeIntersector is used instead, with a "radius" given by the value of this parameter; this is less efficient, but can pick points and lines.
kbdPolicyFactoryThe factory that will be used to create the FocusPolicy used to automatically set the focus for keyboard events.
wheelPolicyFactoryThe factory that will be used to create the FocusPolicy used to automatically set the focus for mouse wheel events.

Member Function Documentation

void OSGUIsh::EventHandler::addNode ( const NodePtr  node)

Adds a given node to the list of nodes being "observed" by this EventHandler. In other words, after this call, signals for this node will be triggered.

Parameters:
nodeThe node that will be added to this EventHandler.
MouseButton OSGUIsh::EventHandler::getMouseButton ( const osgGA::GUIEventAdapter &  ea) [private]

Returns the mouse button used in the osgGA::GUIEventAdapter passed as parameter.

NodePtr OSGUIsh::EventHandler::getObservedNode ( const osg::NodePath &  nodePath) [private]

Returns the first node in an osg::NodePath that is present in the list of nodes being "observed" by this EventHandler. This is necessary in the cases in which the user is picking a node that is child of an added node. That's the case, for instance, of when the user adds a node read from a 3D model file returned by osgDB::readNodeFile().

Parameters:
nodePathThe node path leading to the node being queried.
Returns:
The first node in nodePath that was added to the list of nodes being observed.
SignalPtr OSGUIsh::EventHandler::getSignal ( const NodePtr  node,
Event  signal 
)

Returns a signal associated with a given node. This is typically used to call connect() on the returned signal.

Parameters:
nodeThe desired node.
signalThe desired signal.
Note:
The "mouse move" event is "relative": if the mouse is not moving, but a node is moving "below" it, mouse move events will be generated.
bool OSGUIsh::EventHandler::handle ( const osgGA::GUIEventAdapter &  ea,
osgGA::GUIActionAdapter &   
)

Handles upcoming events (overloads virtual method).

Returns:
See handleReturnValues_, please.
void OSGUIsh::EventHandler::handleFrameEvent ( osg::View *  view,
const osgGA::GUIEventAdapter &  ea 
) [private]

Handles a FRAME event triggered by OSG. Signals triggered here are "MouseEnter", "MouseLeave" and "MouseMove".

Parameters:
viewThe view displaying the scene.
eaThe event generated by OSG.
void OSGUIsh::EventHandler::handleKeyDownEvent ( const osgGA::GUIEventAdapter &  ea) [private]

Handles a KEYDOWN event triggered by OSG. The only signal triggered here is "KeyDown".

Parameters:
eaThe event generated by OSG.
void OSGUIsh::EventHandler::handleKeyUpEvent ( const osgGA::GUIEventAdapter &  ea) [private]

Handles a KEYUP event triggered by OSG. The only signal triggered here is "KeyUp".

Parameters:
eaThe event generated by OSG.
void OSGUIsh::EventHandler::handlePushEvent ( const osgGA::GUIEventAdapter &  ea) [private]

Handles a PUSH event triggered by OSG. The only signal triggered here is "MouseDown", but this function also does bookkeeping related to other mouse signals.

Parameters:
eaThe event generated by OSG.
void OSGUIsh::EventHandler::handleReleaseEvent ( const osgGA::GUIEventAdapter &  ea) [private]

Handles a RELEASE event triggered by OSG. Signals triggered here are "MouseUp", "Click" and "DoubleClick".

Parameters:
eaThe event generated by OSG.
void OSGUIsh::EventHandler::handleScrollEvent ( const osgGA::GUIEventAdapter &  ea) [private]

Handles a SCROLL event triggered by OSG. The signals triggered here are "ScrollUp" and "ScrollDown".

Parameters:
eaThe event generated by OSG.
void OSGUIsh::EventHandler::ignoreBackFaces ( bool  ignore = true) [inline]

Ignores or stops to ignore faces that are back-facing the viewer when picking. It may be useful to ignore back faces when backface culling is enabled.

Parameters:
ignoreIf true, back faces will be ignored when picking. If false, back faces will be considered when piking.
Bug:
Ignoring back faces works only if the picking radius is equals to zero.

Definition at line 225 of file EventHandler.hpp.

References ignoreBackFaces_.

void OSGUIsh::EventHandler::setKeyboardFocus ( const NodePtr  node)

Manually sets the node that will receive keyboard events. Notice that focus policies allow to set this automatically.

void OSGUIsh::EventHandler::setKeyboardFocusPolicy ( const FocusPolicyFactory &  policyFactory)

Sets the focus policy for keyboard events to a given one.

Parameters:
policyFactoryThe factory that will be used to create the actual policy.
void OSGUIsh::EventHandler::setMouseWheelFocus ( const NodePtr  node)

Sets the node that will receive mouse wheel events. Notice that focus policies allow to set this automatically.

void OSGUIsh::EventHandler::setMouseWheelFocusPolicy ( const FocusPolicyFactory &  policyFactory)

Sets the focus policy for mouse wheel events to a given one.

Parameters:
policyFactoryThe factory that will be used to create the actual policy.
void OSGUIsh::EventHandler::setPickingMask ( osg::Node::NodeMask  newMask)

Sets node mask that will be used when picking. The default node mask is 0xFFFFFFFF, meaning that every node with at least one bit set on their node masks will be taken into account for picking. (All this just means that you don't change any setting related to node masks, OSGUIsh will not ignore any node when picking.)

So, when should one explicitly set the picking mask? The easy answer is "whenever one wants to ignore some nodes when picking". (When picking, OSGUIsh (OSG, in fact) will perform a bitwise AND between the picking root set here and each node's node mask; if the result is zero, the node will be ignored.)

The interesting part is that OSGUIsh supports multiple picking masks. First, it will try to pick nodes using the first node mask; if no node is picked, it will try picking using the second picking mask and so on.

Creative people may find various uses for this, but the feature was implemented so that picking could work with HUDs. When using multiple osg::Cameras (as is the case when using HUDs), picking in OSG can be problematic. The details of this problem are not important here (anyway, basically, we don't have control on the relative "z-order" of objects viewed by different Cameras). But it is important to know that, if we want to pick objects in different camera nodes, we may have some unpredictable results.

So, to enable proper picking in HUDs, OSGUIsh can use this scheme of multiple picking roots.

See also:
setPickingMasks() which are the methods capable of setting multiple picking roots.
Parameters:
newMaskThe new node mask to be used when picking.
void OSGUIsh::EventHandler::setPickingMasks ( osg::Node::NodeMask  newMask1,
osg::Node::NodeMask  newMask2 
)

Sets the node masks used when picking.

Parameters:
newMask1The first node mask to be tried when picking.
newMask2The second node mask to be tried when picking.
See also:
setPickingMask for a description of why using multiple picking roots can be useful (tip: HUD).
void OSGUIsh::EventHandler::setPickingMasks ( osg::Node::NodeMask  newMask1,
osg::Node::NodeMask  newMask2,
osg::Node::NodeMask  newMask3 
)

Sets the node masks used when picking.

Parameters:
newMask1The first node mask to be tried when picking.
newMask2The second node mask to be tried when picking.
newMask3The third node mask to be tried when picking.
See also:
setPickingMask for a description of why using multiple picking roots can be useful (tip: HUD).
void OSGUIsh::EventHandler::setPickingMasks ( const NodeMasks_t &  newMasks)

Sets the node masks used when picking.

Parameters:
newMasksA vector with the node masks to be tried when picking (they'll be tried in sequence).
See also:
setPickingMask for a description of why using multiple picking roots can be useful (tip: HUD).
void OSGUIsh::EventHandler::updatePickingData ( osg::View *  view,
const osgGA::GUIEventAdapter &  ea 
) [private]

Updates the member variables used to store picking info: nodeUnderMouse_, positionUnderMouse_, prevNodeUnderMouse_ and prevPositionUnderMouse_.

Parameters:
viewThe view displaying the scene.
eaThe event generated by OSG.
Note:
The implementation just calls either updatePickingDataLine or updatePickingDataPolytope. This is in fact somewhat ridiculous, since these functions are in fact quite similar. The replication is necessary because, for some reason, OSG "interceptors" don't have a common interface/subclass -- so, I had to do implement polymorphism by hand.
void OSGUIsh::EventHandler::updatePickingDataLine ( osg::View *  view,
const osgGA::GUIEventAdapter &  ea 
) [private]

The version of updatePickingData() using an osgUtil::LineSegmentIntersector.

Parameters:
viewThe view displaying the scene.
eaThe event generated by OSG.
See also:
updatePickingData() for information on what this function does.
void OSGUIsh::EventHandler::updatePickingDataPolytope ( osg::View *  view,
const osgGA::GUIEventAdapter &  ea 
) [private]

The version of updatePickingData() using an osgUtil::PolytopeIntersector.

Parameters:
viewThe view displaying the scene.
eaThe event generated by OSG.
See also:
updatePickingData() for information on what this function does.
Note:
This function does not even try to ignore back faces when ignoreBackFaces_ == true (the PolytopeIntersector does not provide the intersection normals).

Member Data Documentation

std::map<osgGA::GUIEventAdapter::EventType, bool> OSGUIsh::EventHandler::handleReturnValues_ [private]

The values to be returned by the handle() method, depending on the event type it is handling. Currently, this is not initialized, meaning that handle(), by default, returns false for all event types.

Todo:
Implement a method like setHandleReturnValue(), so that the user can configure this.

Definition at line 343 of file EventHandler.hpp.

Intersection_t OSGUIsh::EventHandler::hitUnderMouse_ [private]

The Intersection_t structure for the node currently under the mouse pointer. (Respecting the ignoreBackFaces_ flag.)

Definition at line 362 of file EventHandler.hpp.

bool OSGUIsh::EventHandler::ignoreBackFaces_ [private]

If this is true, faces back-facing the viewer will be ignored while picking.

Definition at line 326 of file EventHandler.hpp.

Referenced by ignoreBackFaces().

NodePtr OSGUIsh::EventHandler::kbdFocus_ [private]

The node receiving keyboard events.

Definition at line 470 of file EventHandler.hpp.

FocusPolicyPtr OSGUIsh::EventHandler::kbdFocusPolicy_ [private]

The focus policy for keyboard-related events.

Definition at line 473 of file EventHandler.hpp.

NodePtr OSGUIsh::EventHandler::nodeThatGotClick_[MOUSE_BUTTON_COUNT] [private]

An array indicating (for every mouse button) which was the node that received the last click event. This is used to identify double clicks.

Definition at line 456 of file EventHandler.hpp.

NodePtr OSGUIsh::EventHandler::nodeThatGotMouseDown_[MOUSE_BUTTON_COUNT] [private]

An array indicating (for every mouse button) which was the node that received the last mouse down event. This is used to identify clicks.

Definition at line 449 of file EventHandler.hpp.

NodePtr OSGUIsh::EventHandler::nodeUnderMouse_ [private]

The node currently under the mouse pointer.

Definition at line 369 of file EventHandler.hpp.

double OSGUIsh::EventHandler::pickerRadius_ [private]

The "radius" of the picker. If zero, will use an osgUtil::LineSegmentIntersector; if greater than zero, will use an osgUtil::PolytopeIntersector. (Values less than zero are not allowed.)

Definition at line 320 of file EventHandler.hpp.

NodeMasks_t OSGUIsh::EventHandler::pickingMasks_ [private]

The sequence of node masks used when picking.

See also:
setPickingRoot for a discussion on how this is used and why this is necessary.

Definition at line 333 of file EventHandler.hpp.

osg::Vec3 OSGUIsh::EventHandler::positionUnderMouse_ [private]

The position (in the object coordinate system) of nodeUnderMouse_ (the node currently under the mouse pointer).

Definition at line 375 of file EventHandler.hpp.

NodePtr OSGUIsh::EventHandler::prevNodeUnderMouse_ [private]

The node previously under the mouse pointer.

Definition at line 378 of file EventHandler.hpp.

osg::Vec3 OSGUIsh::EventHandler::prevPositionUnderMouse_ [private]

The position (in the object coordinate system) of prevNodeUnderMouse_ (the node previously under the mouse pointer).

Definition at line 384 of file EventHandler.hpp.

SignalsMap_t OSGUIsh::EventHandler::signals_ [private]

Structure containing all the signals used by this EventHandler. It can be used with a syntax like this: signals_[node][EVENT_MOUSE_MOVE]->connect(&MyHandler);

Definition at line 356 of file EventHandler.hpp.

double OSGUIsh::EventHandler::timeOfLastClick_[MOUSE_BUTTON_COUNT] [private]

An array indicating (for every mouse button) the time at which the last click event has happened. This is used to identify double clicks.

Definition at line 463 of file EventHandler.hpp.

NodePtr OSGUIsh::EventHandler::wheelFocus_ [private]

The node receiving mouse wheel events.

Definition at line 480 of file EventHandler.hpp.

FocusPolicyPtr OSGUIsh::EventHandler::wheelFocusPolicy_ [private]

The focus policy for mouse wheel-related events.

Definition at line 483 of file EventHandler.hpp.

The documentation for this class was generated from the following file:
Generated on Thu Nov 10 2011 19:50:13 for OSGUIsh by   doxygen 1.7.5.1