com.sun.j3d.utils.behaviors.sensor
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 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.

Since:

Java 3D 1.3

See Also:

SensorEvent, SensorButtonListener, SensorReadListener

Constructor Summary

SensorEventAgent(java.lang.Object source)
Create a SensorEventAgent to generate and dispatch sensor events to registered listeners.

Method Summary

void	addSensorButtonListener(Sensor sensor, int button, SensorButtonListener buttonListener) Creates a binding of the specified sensor button to the given SensorButtonListener implementation.
void	addSensorButtonListener(Sensor sensor, SensorButtonListener buttonListener) Creates a binding from all the buttons on the specified sensor to the given SensorButtonListener implementation.
void	addSensorButtonListeners(Sensor sensor, SensorButtonListener[] buttonListeners) Creates a binding of the specified sensor to the given array of SensorButtonListener implementations.
void	addSensorReadListener(Sensor sensor, SensorReadListener readListener) Creates a binding of the specified sensor to the given SensorReadListener.
void	dispatchEvents() Reads all sensor button state and dispatches events to registered button and read listeners.
SensorButtonListener[]	getSensorButtonListeners(Sensor sensor, int button) Gets the SensorButtonListener implementations bound to the given sensor and button.
SensorReadListener[]	getSensorReadListeners(Sensor sensor) Gets the SensorReadListeners 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 given SensorButtonListener from all sensors.
void	removeSensorButtonListener(Sensor sensor, SensorButtonListener listener) Remove the given SensorButtonListener binding from the specified sensor.
void	removeSensorReadListener(SensorReadListener listener) Remove the given SensorReadListener from all sensors.
void	removeSensorReadListener(Sensor sensor, SensorReadListener listener) Remove the given SensorReadListener binding from the specified sensor.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SensorEventAgent

public SensorEventAgent(java.lang.Object source)

Create a SensorEventAgent to generate and dispatch sensor events to registered listeners.

Parameters:

source - reference to the originating object for inclusion in generated SensorEvents; 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 given SensorButtonListener implementation.

Parameters:

sensor - the sensor with the button to be bound

button - the index of the button to be bound on the specified sensor; may range from 0 to (sensor.getSensorButtonCount() - 1)

buttonListener - the SensorButtonListener 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 given SensorButtonListener 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 bound

buttonListener - the SensorButtonListener 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 of SensorButtonListener 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 bound

buttonListeners - array of implementations of SensorButtonListener; 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 the SensorButtonListener implementations bound to the given sensor and button.

Parameters:

sensor - the sensor of interest

button - 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 given SensorButtonListener binding from the specified sensor.

Parameters:

sensor - the sensor from which to remove the listener

listener - the listener to be removed

removeSensorButtonListener

public void removeSensorButtonListener(SensorButtonListener listener)

Remove the given SensorButtonListener 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 given SensorReadListener. The read listener is invoked every time dispatchEvents is called and a button listener is not invoked.

Parameters:

sensor - the sensor to be bound

readListener - the SensorReadListener implementation

getSensorReadListeners

public SensorReadListener[] getSensorReadListeners(Sensor sensor)

Gets the SensorReadListeners 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 given SensorReadListener binding from the specified sensor.

Parameters:

sensor - the sensor from which to remove the listener

listener - the listener to be removed

removeSensorReadListener

public void removeSensorReadListener(SensorReadListener listener)

Remove the given SensorReadListener 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 the processStimulus implementation of a Behavior or the pollAndProcessInput method of an event-driven implementation of InputDevice.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object