We support a
Software Patent Free Europe.

ot::QtMouseEventSinkBase Class Reference
[OTQt Classes]

Base class of MEMs sink nodes. More...

#include <QtMouseEventSinkBase.h>

Inheritance diagram for ot::QtMouseEventSinkBase:

[legend]Collaboration diagram for ot::QtMouseEventSinkBase:


Public Types
	EVENT_PENDING_SIGNAL = 0x01
	EVENT_ACQUIRE_LOCK = 0x02
	POS_THRESH_FILTER = 0x04
	ORIENT_THRESH_FILTER = 0x08
	CONSUME_EVENTS = 0x10
	EVENT_CONSUME_SIGNAL = 0x20
enum	StateFlag { EVENT_PENDING_SIGNAL = 0x01, EVENT_ACQUIRE_LOCK = 0x02, POS_THRESH_FILTER = 0x04, ORIENT_THRESH_FILTER = 0x08, CONSUME_EVENTS = 0x10, EVENT_CONSUME_SIGNAL = 0x20 }
Public Member Functions
	QtMouseEventSinkBase (StringTable &xml_attrib_table)
virtual	~QtMouseEventSinkBase ()
virtual void	onEventGenerated (Event &event, Node &generator)=0
virtual int	isEventGenerator ()
bool	isEventPending () const
void	resetPendingEventBit ()
Event const &	getCurrentEvent () const
Event const &	getPreviousEvent () const
bool	enableState (StateFlag flag, bool enable=true)
void	forwardEvent (Event &event)
Protected Types
typedef unsigned short	state_t
Protected Member Functions
bool	isInsidePosThreshSphere (Event const &event) const
bool	isInsideOrientThreshCone (Event const &event) const
void	acquireEvent (Event const &event)
Protected Attributes
state_t	state_
Event	curr_event_
Event	prev_event_
StringTable	xml_attrib_table_
float	POS_THRESH_RADIUS
float	ORIENT_THRESH_QUAT [4]
Private Member Functions
	QtMouseEventSinkBase ()
	QtMouseEventSinkBase (QtMouseEventSinkBase const &ref)
QtMouseEventSinkBase &	operator= (QtMouseEventSinkBase const &ref)
Friends
class	QtMouseEventModule

Detailed Description

Base class of MEMs sink nodes.

OTQt sinks are implemented as event generator nodes. Each sink node receives tracking events from its child nodes and passes the event to its parent nodes in the same cycle.

OTQt sinks basically store copies of incoming events (see onEventGenerated() method) and provide methods to retrieve them (see getCurrentEvent(), getPreviousEvent()). Different sinks provide useful methods which indicate changes in tracking event data. Most of the work is done in the module (MEM) itself: the application screen 3D location management, the mouse cursor placement and the generation of button and wheel events. There main reason for that design decision is simple: only in the module all information is available to decide wheater certain Qt mouse events should be generated or not.

The OTQt sinks store incoming events only if the pending event differs from the last event which was processed in the MEM. Each sink employs a two element event queue internally where current and previous events are stored. If the pending event differs from the current event, the event is copied and stored as new current event while the old current event becomes the previous event. The original event is passed unchanged to parent nodes of the sink. The intention of this early event filtering is the reduction of computational load. Only relevant events are processed afterwards in the module. Each sink indicates the arrival of a new event by setting the pending event flag, which can be retrieved with isEventPending() and reset with resetPendingEventBit() methods. Each sink's event acquisition can be suspended by enabling the EVENT_LOCK state flag. Provides the enableState() method to switch states.

Filters (experimental!)

This class provides additional mechanisms such as position (see method isInsidePosThreshSphere()) and orientation (see method isInsideOrientThreshCone()) threshold filter. Derived sinks apply these methods in the acquisition of incoming tracking events where convenient. Desired position and orientation threshold values can be assigned over the sink's XML attributes. Assigning non-default values, the state flags POS_THRESH_FILTER and/or ORIENT_THRESH_FILTER are enabled automatically (see QtMouseEventSinkBase(StringTable &).

In order to finally ignore a tracking event, the event must be catched by ALL applied filters. Otherwise,

The corresponding XML attributes are:

PosThreshRadiusInMeter radius of threshold sphere, applied in position filter (optional; default value: "0.0" -> position filter disabled)

The threshold sphere is determined by the last acquired input device position (center) and the specified radius. Consecutive 3D tracking events are ignored, if they are located inside the threshold sphere.

OrientThreshAngle radian angle used equally for all XYZ axes to describe an euler rotation, applied in orientation filter (optional; default value: "0.0" -> orientation filter disabled)

The last acquired tracking event is the reference for the orienation comparison. Consecutive tracking events are ignored, if their orientation difference on all axes is less or equal the specified angle.

consume-events Either "true" (enabled) or "false" (disabled, default). If enabled, tracking events are not forwarded to their parent nodes within the OT node graph iff they are consumed within the OTQt MEM, that is, if a specific tracking event was used to generate Qt mouse events.

Example: Within a hybrid 2D/3D setup, where the same tracking devices are used, the feature can be applied to filter all tracking events which have already been used (consumed) within one UI (eg the 2D UI) and prevent them to be forwarded to the second UI (eg the 3D UI) and causing unwanted interactions.

Configuration example (schema):

<NetworkSink target="3D-UI">
  <QtMouseButtonSink consume-events="true">
    <NetworkSource source="Tracking" />
  </QtMouseButtonSink>
</NetworkSink>

Tracking events are generated by some source (here "Tracking") and enter the node graph in the NetworkSink node. The QtMouseButtonSink is is connected to some 2D UI and configured to consume events. Forwarded tracking events leave the graph through a NetworkSink which sends them to another host where the 3D UI application is assumed.

Only those tracking event pass the entire hierarchy, which are not consumed by the OTQt MEM, thus they where used to generate some mouse (button) event on the 2D application. Otherwise the tracking event was not destined for the 2D UI and is forwarded to the 3D UI.

Definition at line 154 of file QtMouseEventSinkBase.h.

Member Typedef Documentation

typedef unsigned short ot::QtMouseEventSinkBase::state_t [protected]

object state encoding type

Definition at line 181 of file QtMouseEventSinkBase.h.

Member Enumeration Documentation

enum ot::QtMouseEventSinkBase::StateFlag

State flags.

Enumerator:

EVENT_PENDING_SIGNAL	if enabled, indicates the acquisition of a new current (pending) tracking event
EVENT_ACQUIRE_LOCK	while enabled, the sink will not acquire tracking events (disabled by default)
POS_THRESH_FILTER	enable/disable the position threshold filter applied in the acquisition of tracking event (disabled by default)
ORIENT_THRESH_FILTER	enable/disable the orientation threshold filter applied in the acquisition of tracking event (disabled by default)
CONSUME_EVENTS	enable/disable event consumption; if enabled, the sink does not forward events to its parent nodes while the `EVENT_CONSUME_SIGNAL` is enabled (disabled by default)
EVENT_CONSUME_SIGNAL	enabled, the sink will not forward tracking events to its parents (disabled by default); this flag is used in conjuction with the `CONSUME_EVENTS` flag (and is thus overruled by that flag)

Definition at line 158 of file QtMouseEventSinkBase.h.

Constructor & Destructor Documentation

ot::QtMouseEventSinkBase::QtMouseEventSinkBase ( StringTable & xml_attrib_table )

Disables all state flags by default.

Sets current and previous event to State::null. Stores specified XML attribute map. Computes position and orientation threshold values from XML attributes, enabling the corresponding POS_THRESH_FILTER and ORIENT_THRESH_FILTER flags if appropriate.

Parameters:

xml_attrib_table

XML attribute key/value map

Definition at line 54 of file QtMouseEventSinkBase.cxx.

References CONSUME_EVENTS, enableState(), ot::MathUtils::eulerToQuaternion(), ot::StringTable::get(), ORIENT_THRESH_FILTER, ORIENT_THRESH_QUAT, OTQT_DEBUG(), POS_THRESH_FILTER, POS_THRESH_RADIUS, state_, and ot::MathUtils::XYZ.

virtual ot::QtMouseEventSinkBase::~QtMouseEventSinkBase ( ) [inline, virtual]

Definition at line 193 of file QtMouseEventSinkBase.h.

ot::QtMouseEventSinkBase::QtMouseEventSinkBase ( ) [private]

ot::QtMouseEventSinkBase::QtMouseEventSinkBase ( QtMouseEventSinkBase const & ref ) [private]

Member Function Documentation

void ot::QtMouseEventSinkBase::acquireEvent ( Event const & event ) [protected]

Acquires the given tracking event as new current event.

Resets the old current event as new previous event. Discards the the old previous element. Enables the EVENT_PENDING_SIGNAL state flag.

Parameters:

event

pending tracking event

Definition at line 126 of file QtMouseEventSinkBase.cxx.

References curr_event_, EVENT_PENDING_SIGNAL, prev_event_, and state_.

Referenced by ot::QtMouseWheelSink::onEventGenerated(), ot::QtMousePosSink::onEventGenerated(), ot::QtMouseButtonSink::onEventGenerated(), ot::QtAppScreenPosSink::onEventGenerated(), and ot::QtMouseEventModule::pullEvent().

bool ot::QtMouseEventSinkBase::enableState	(	StateFlag	flag,
		bool	enable = `true`
	)

Enables or disables the given state flag depending on the binary argument.

Enables flag if true (default), otherwise disables flag. Returns the state flag value after the update was performed.

Parameters:

	flag	state flag
	enable	set true if state flag should be enabled (default), otherwise disables

Returns:: enable/disable (true/false) value of the state flag after update

Definition at line 94 of file QtMouseEventSinkBase.cxx.

References state_.

Referenced by ot::QtMouseEventModule::pullEvent(), and QtMouseEventSinkBase().

void ot::QtMouseEventSinkBase::forwardEvent ( Event & event )

Forwards the given tracking event to its parents if either CONSUME_EVENTS or EVENT_CONSUME_SIGNAL are disabled.

If both are true the event is said to be locally consumed and thus NOT forwarded.

Parameters:

event

tracking event to forward

Definition at line 136 of file QtMouseEventSinkBase.cxx.

References CONSUME_EVENTS, EVENT_CONSUME_SIGNAL, state_, and ot::Node::updateObservers().

Referenced by ot::QtMouseWheelSink::onEventGenerated(), ot::QtMousePosSink::onEventGenerated(), ot::QtMouseButtonSink::onEventGenerated(), and ot::QtAppScreenPosSink::onEventGenerated().

Event const& ot::QtMouseEventSinkBase::getCurrentEvent ( ) const [inline]

Returns the latest acquired tracking event (tracking node current event).

Returns:: current tracking event of node

Definition at line 260 of file QtMouseEventSinkBase.h.

Referenced by ot::QtMouseEventModule::pullEvent(), ot::OTQtMEMCalibProc::trackASCorner(), ot::OTQtMEMCalibProc::trackASPos(), ot::OTQtMEMCalibProc::trackMBDButtonOne(), and ot::OTQtMEMCalibProc::trackMPD().

Event const& ot::QtMouseEventSinkBase::getPreviousEvent ( ) const [inline]

Returns the predecessor of the latest acquired tracking event (tracking node previous event).

Returns:: previous tracking event of node

Definition at line 266 of file QtMouseEventSinkBase.h.

virtual int ot::QtMouseEventSinkBase::isEventGenerator ( ) [inline, virtual]

Returns true if node implements the OpenTracker event edge type interface: the node pushes incoming events to its parent nodes.

Returns:: true if node forwards incoming events to its parent nodes

Reimplemented from ot::Node.

Definition at line 243 of file QtMouseEventSinkBase.h.

bool ot::QtMouseEventSinkBase::isEventPending ( ) const [inline]

Returns true if a new tracking event was acquired (available as current event) indicated by the EVENT_PENDING_SIGNAL state flag.

Returns:: true if new current event available

Definition at line 251 of file QtMouseEventSinkBase.h.

Referenced by ot::QtMouseEventModule::pullEvent(), and ot::OTQtMEMCalibProc::trackMBDButtonOne().

bool ot::QtMouseEventSinkBase::isInsideOrientThreshCone ( Event const & event ) const [protected]

Performs a trivial orientation comparison test.

Computes the difference quaternion angle between the given tracking event and the current event. Verifies the resulting quaternion against some pre-defined threshold value (see ORIENT_THRESH_RADIUS) by comparing the quaternion vector elements. Returns true if each difference quaternion vector element absolute value is less or equal the corresponding absolute value of the threshold quaternion vector.

Parameters:

event

tracking event

Returns:: true if orientation distance less or equal than threshold value

Definition at line 110 of file QtMouseEventSinkBase.cxx.

References curr_event_, ot::Event::getOrientation(), ot::MathUtils::invertQuaternion(), ot::MathUtils::multiplyQuaternion(), and ORIENT_THRESH_QUAT.

Referenced by ot::QtAppScreenPosSink::onEventGenerated().

bool ot::QtMouseEventSinkBase::isInsidePosThreshSphere ( Event const & event ) const [protected]

Returns true if 3D position difference of given tracking event and current event does not exceed pre-defined threshold distance (see POS_THRESH_RADIUS).

Parameters:

event

tracking event

Returns:: true if positional distance less or equal than threshold value

Definition at line 103 of file QtMouseEventSinkBase.cxx.

References curr_event_, ot::OTQtMath::distance(), ot::Event::getPosition(), and POS_THRESH_RADIUS.

Referenced by ot::QtMousePosSink::onEventGenerated(), and ot::QtAppScreenPosSink::onEventGenerated().

virtual void ot::QtMouseEventSinkBase::onEventGenerated	(	Event &	event,
		Node &	generator
	)			`[pure virtual]`

OpenTracker tracking event push pattern callback method.

Basically stores a copy of the incoming event as new current event in the internal event queue and forwards the original event to parent nodes.

Applies a series of elimination checks on the incoming event. Ignores the event if any of these checks fail. Otherwise acquires the event, thus the incoming event becomes the new current event and the old current event becomes the new previous event. Enables the EVENT_PENDING_SIGNAL flag to indicate an acquisition.

Applied checks in detail: Ignores the incoming tracking event if ..

the EVENT_LOCK flag is enabled (currently only implemented in MBS!).

it equals the current event (only modified events pass). Different relevant tracking data portions (position, orientation, button state) are compared, depending on the actual sink.