## 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
`clone, equals, finalize, 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`

Copyright 1996-2008 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.