This class works in conjunction with the SensorButtonListener
and SensorReadListener interfaces to support an event-driven
model of sensor interaction. Java 3D defines sensors as delivering
continuous input data which must be polled to retrieve their values, but in
practice it is often convenient to structure application code to respond to
events such as button state transitions.
Listeners registered with this class are invoked when its
dispatchEvents method is called. This is usually called from
the processStimulus method of a Behavior, but may
also be called directly from the pollAndProcessInput method of
an event-driven implementation of InputDevice. In either case
the device is still polled by the Java 3D input device scheduling thread to
get its current values; however, in the former, dispatchEvents
is called from the behavior scheduler thread regardless of whether any new
events are available, while in the latter, the InputDevice
implementation may choose to call dispatchEvents only if new
events are actually generated.
Button events are generated by changes in sensor button state, from pressed
to released and vice versa. Button state changes are examined with each
invocation of the dispatchEvents method. Events are
distributed to interested parties through the button listener interface
using the pressed and released callbacks.
The dragged method is not necessarily called in response to a
motion event generated by a sensor. dispatchEvents will call
dragged whenever any button assigned to the listener is down
and has not changed state since the last time it was called. If
dispatchEvents is called in the processStimulus
of a Behavior, then dragged may be called even if
the sensor value has not changed. This is as a consequence of the core
Java 3D API definition of sensors as continuous devices.
Like dragged, the read method of
SensorReadListener is not necessarily invoked in response to a
real event. It is called by dispatchEvents whenever a button
listener has not been called for that sensor. This usually means that no
buttons are down, but clients are free to leave a button listener null, or
to explicitly bind a null button listener to a button so that button's
events are ignored. The sensor value has not necessarily changed since the
last read callback.
A mutual exclusion policy can be applied between button
listeners when they are grouped in an array mapped to the sensor's
buttons. If multiple sensor buttons are held down at the same time,
then a listener in the array is invoked only for the button that was
depressed first. The read callback is separated from the
pressed, released, and dragged
callbacks in a separate interface in order to support this policy.
The events passed to the listeners are ephemeral; they are only
valid until the listener has returned. This is done to avoid
allocating large numbers of mostly temporary objects, especially for
behaviors that wake up every frame. If a listener needs to retain the
event it must be copied using the SensorEvent(SensorEvent)
constructor.
It is safe to add and remove listeners in response to a callback.
See Also: SensorEvent
See Also: SensorButtonListener
See Also: SensorReadListener
since:
Java 3D 1.3 | 