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

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.