Package com.sun.j3d.utils.behaviors.sensor

Class 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 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