Class SensorEventAgent
- java.lang.Object
-
- com.sun.j3d.utils.behaviors.sensor.SensorEventAgent
-
public class SensorEventAgent extends java.lang.Object
This class works in conjunction with theSensorButtonListener
andSensorReadListener
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 theprocessStimulus
method of aBehavior
, but may also be called directly from thepollAndProcessInput
method of an event-driven implementation ofInputDevice
. 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, theInputDevice
implementation may choose to calldispatchEvents
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 thepressed
andreleased
callbacks.The
dragged
method is not necessarily called in response to a motion event generated by a sensor.dispatchEvents
will calldragged
whenever any button assigned to the listener is down and has not changed state since the last time it was called. IfdispatchEvents
is called in theprocessStimulus
of aBehavior
, thendragged
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
, theread
method ofSensorReadListener
is not necessarily invoked in response to a real event. It is called bydispatchEvents
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 lastread
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 thepressed
,released
, anddragged
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:
SensorEvent
,SensorButtonListener
,SensorReadListener
-
-
Constructor Summary
Constructors Constructor Description SensorEventAgent(java.lang.Object source)
Create aSensorEventAgent
to generate and dispatch sensor events to registered listeners.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
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
dispatchEvents()
Reads all sensor button state and dispatches events to registered button and read listeners.SensorButtonListener[]
getSensorButtonListeners(Sensor sensor, int button)
Gets theSensorButtonListener
implementations bound to the given sensor and button.SensorReadListener[]
getSensorReadListeners(Sensor sensor)
Gets theSensorReadListeners
bound to the specified sensor.Sensor[]
getSensors()
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
removeSensorButtonListener(SensorButtonListener listener)
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.java.lang.String
toString()
-
-
-
Constructor Detail
-
SensorEventAgent
public SensorEventAgent(java.lang.Object source)
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 Detail
-
addSensorButtonListener
public void addSensorButtonListener(Sensor sensor, int button, SensorButtonListener buttonListener)
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
public void addSensorButtonListener(Sensor sensor, SensorButtonListener buttonListener)
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
public void addSensorButtonListeners(Sensor sensor, SensorButtonListener[] buttonListeners)
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
public SensorButtonListener[] getSensorButtonListeners(Sensor sensor, int button)
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
public void removeSensorButtonListener(Sensor sensor, SensorButtonListener listener)
Remove the givenSensorButtonListener
binding from the specified sensor.- Parameters:
sensor
- the sensor from which to remove the listenerlistener
- the listener to be removed
-
removeSensorButtonListener
public void removeSensorButtonListener(SensorButtonListener listener)
Remove the givenSensorButtonListener
from all sensors.- Parameters:
listener
- the listener to remove
-
addSensorReadListener
public void addSensorReadListener(Sensor sensor, SensorReadListener readListener)
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
public SensorReadListener[] getSensorReadListeners(Sensor sensor)
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
public void removeSensorReadListener(Sensor sensor, SensorReadListener listener)
Remove the givenSensorReadListener
binding from the specified sensor.- Parameters:
sensor
- the sensor from which to remove the listenerlistener
- the listener to be removed
-
removeSensorReadListener
public void removeSensorReadListener(SensorReadListener listener)
Remove the givenSensorReadListener
from all sensors.- Parameters:
listener
- the listener to remove
-
removeSensorBinding
public void removeSensorBinding(Sensor sensor)
Remove all sensor listeners bound to the given sensor.
-
getSensors
public 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
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-