Class SensorEventAgent
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.
- Since:
- Java 3D 1.3
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionSensorEventAgent
(Object source) Create aSensorEventAgent
to generate and dispatch sensor events to registered listeners. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addSensorButtonListener
(Sensor sensor, int button, SensorButtonListener buttonListener) Creates a binding of the specified sensor button to the givenSensorButtonListener
implementation.void
addSensorButtonListener
(Sensor sensor, SensorButtonListener buttonListener) Creates a binding from all the buttons on the specified sensor to the givenSensorButtonListener
implementation.void
addSensorButtonListeners
(Sensor sensor, SensorButtonListener[] buttonListeners) Creates a binding of the specified sensor to the given array ofSensorButtonListener
implementations.void
addSensorReadListener
(Sensor sensor, SensorReadListener readListener) Creates a binding of the specified sensor to the givenSensorReadListener
.void
Reads all sensor button state and dispatches events to registered button and read listeners.getSensorButtonListeners
(Sensor sensor, int button) Gets theSensorButtonListener
implementations bound to the given sensor and button.getSensorReadListeners
(Sensor sensor) Gets theSensorReadListeners
bound to the specified sensor.Sensor[]
Returns an array of references to all sensors that have been bound to listeners.void
removeSensorBinding
(Sensor sensor) Remove all sensor listeners bound to the given sensor.void
Remove the givenSensorButtonListener
from all sensors.void
removeSensorButtonListener
(Sensor sensor, SensorButtonListener listener) Remove the givenSensorButtonListener
binding from the specified sensor.void
removeSensorReadListener
(SensorReadListener listener) Remove the givenSensorReadListener
from all sensors.void
removeSensorReadListener
(Sensor sensor, SensorReadListener listener) Remove the givenSensorReadListener
binding from the specified sensor.toString()
-
Constructor Details
-
SensorEventAgent
Create aSensorEventAgent
to generate and dispatch sensor events to registered listeners.- Parameters:
source
- reference to the originating object for inclusion in generatedSensorEvents
; intended to refer to the instantiating Behavior but may be any reference, or null
-
-
Method Details
-
addSensorButtonListener
Creates a binding of the specified sensor button to the givenSensorButtonListener
implementation.- Parameters:
sensor
- the sensor with the button to be boundbutton
- the index of the button to be bound on the specified sensor; may range from 0 to(sensor.getSensorButtonCount() - 1)
buttonListener
- theSensorButtonListener
implementation that will be invoked for the sensor's button
-
addSensorButtonListener
Creates a binding from all the buttons on the specified sensor to the givenSensorButtonListener
implementation. If multiple sensor buttons are held down at the same time, the press and release callbacks are called for each button in the order that they occur. This allows actions to be bound to combinations of button presses, but is also convenient for listeners that don't care which button was pressed.- Parameters:
sensor
- the sensor to be boundbuttonListener
- theSensorButtonListener
implementation that will be called for all button events
-
addSensorButtonListeners
Creates a binding of the specified sensor to the given array ofSensorButtonListener
implementations. The array index of the listener indicates the index of the sensor button to which it will be bound.This method enforces a mutually exclusive callback policy among the listeners specified in the array. If multiple sensor buttons are held down at the same time, callbacks are invoked only for the button that was depressed first.
- Parameters:
sensor
- the sensor to be boundbuttonListeners
- array of implementations ofSensorButtonListener
; array entries may be null or duplicates but the array length must equal the sensor's button count
-
getSensorButtonListeners
Gets theSensorButtonListener
implementations bound to the given sensor and button.- Parameters:
sensor
- the sensor of interestbutton
- the button of interest- Returns:
- array of
SensorButtonListener
implementations bound to the given sensor and button, or null
-
removeSensorButtonListener
Remove the givenSensorButtonListener
binding from the specified sensor.- Parameters:
sensor
- the sensor from which to remove the listenerlistener
- the listener to be removed
-
removeSensorButtonListener
Remove the givenSensorButtonListener
from all sensors.- Parameters:
listener
- the listener to remove
-
addSensorReadListener
Creates a binding of the specified sensor to the givenSensorReadListener
. The read listener is invoked every timedispatchEvents
is called and a button listener is not invoked.- Parameters:
sensor
- the sensor to be boundreadListener
- theSensorReadListener
implementation
-
getSensorReadListeners
Gets theSensorReadListeners
bound to the specified sensor.- Parameters:
sensor
- the sensor of interest- Returns:
- array of
SensorReadListeners
bound to the given sensor, or null
-
removeSensorReadListener
Remove the givenSensorReadListener
binding from the specified sensor.- Parameters:
sensor
- the sensor from which to remove the listenerlistener
- the listener to be removed
-
removeSensorReadListener
Remove the givenSensorReadListener
from all sensors.- Parameters:
listener
- the listener to remove
-
removeSensorBinding
Remove all sensor listeners bound to the given sensor. -
getSensors
Returns an array of references to all sensors that have been bound to listeners.- Returns:
- an array of sensors, or null if no sensors have been bound
-
dispatchEvents
public void dispatchEvents()Reads all sensor button state and dispatches events to registered button and read listeners. This method is intended to be called from theprocessStimulus
implementation of aBehavior
or thepollAndProcessInput
method of an event-driven implementation ofInputDevice
. -
toString
-