com.sun.j3d.utils.behaviors.sensor

## Class SensorEvent

- java.lang.Object
- - com.sun.j3d.utils.behaviors.sensor.SensorEvent

-     public class SensorEvent
      extends java.lang.Object

  This class defines the event object that is created by a `SensorEventAgent` and passed to registered `SensorReadListener` and `SensorButtonListener` implementations.

  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.

  Since:
    Java 3D 1.3
  See Also:
    `SensorEventAgent`, `SensorButtonListener`, `SensorReadListener`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DRAGGED` A button dragged event.
    `static int` | `NOBUTTON` The value that is returned by `getButton` when no buttons have changed state.
    `static int` | `PRESSED` A button pressed event.
    `static int` | `READ` A sensor read event.
    `static int` | `RELEASED` A button released event.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SensorEvent()` Creates a new ephemeral `SensorEvent`.
    `SensorEvent(java.lang.Object source, int id, Sensor sensor, Transform3D sensorRead, int[] buttonState, int button, long time, long lastTime)` Creates a new `SensorEvent`.
    `SensorEvent(SensorEvent e)` Creates a copy of the given `SensorEvent`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getButton()` Gets the index of the button that changed state when passed to a `pressed` or `released` callback.
    `void` | `getButtonState(int[] buttonState)` Copies the state of the sensor's buttons at the time of the event into the given array.
    `int` | `getID()` Gets the event type.
    `long` | `getLastTime()` Gets the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was last called to generate events, usually from the `processStimulus` method of a `Behavior`; may be used to measure frame time in behaviors that wake up every frame.
    `Sensor` | `getSensor()` Gets a reference to the provoking sensor.
    `void` | `getSensorRead(Transform3D t)` Copies the sensor's read value at the time of the event into the given `Transform3D`.
    `java.lang.Object` | `getSource()` Gets a reference to the originating object which instantiated the `SensorEventAgent`, usually a `Behavior`; may be null.
    `long` | `getTime()` Gets the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was called to generate this event, usually from the `processStimulus` method of a `Behavior`.
    `boolean` | `isEphemeral()` Returns true if this event is ephemeral and is valid only until the listener returns.
    `void` | `set(java.lang.Object source, int id, Sensor sensor, Transform3D sensorRead, int[] buttonState, int button, long time, long lastTime)` Sets the fields of an ephemeral event.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PRESSED

          public static final int PRESSED

      A button pressed event.
      See Also:
        Constant Field Values

    - #### RELEASED

          public static final int RELEASED

      A button released event.
      See Also:
        Constant Field Values

    - #### DRAGGED

          public static final int DRAGGED

      A button dragged event.
      See Also:
        Constant Field Values

    - #### READ

          public static final int READ

      A sensor read event.
      See Also:
        Constant Field Values

    - #### NOBUTTON

          public static final int NOBUTTON

      The value that is returned by `getButton` when no buttons have changed state.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SensorEvent

          public SensorEvent(java.lang.Object source,
                     int id,
                     Sensor sensor,
                     Transform3D sensorRead,
                     int[] buttonState,
                     int button,
                     long time,
                     long lastTime)

      Creates a new `SensorEvent`.
      Parameters:
        `source` - a reference to the originating object which instantiated the `SensorEventAgent`, usually a `Behavior`; may be null
        `id` - event type
        `sensor` - a reference to the provoking sensor
        `sensorRead` - the sensor's read value at the time of the event
        `buttonState` - the state of the sensor's buttons at the time of the event, where a 1 in the array indicates that the button at that index is down, and a 0 indicates that button is up; may be null
        `button` - index of the button that changed state, from 0 to `(buttonCount - 1)`, or the value `NOBUTTON`
        `time` - the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was called to generate this event, usually from the `processStimulus` method of a Behavior
        `lastTime` - the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was last called to generate events, usually from the `processStimulus` method of a `Behavior`; may be used to measure frame time in behaviors that wake up every frame

    - #### SensorEvent

          public SensorEvent()

      Creates a new ephemeral `SensorEvent`. In order to avoid creating large numbers of sensor event objects, the events passed to the button and read listeners by the `dispatchEvents` method of `SensorEventAgent` are valid only until the listener returns. If the event needs to be retained then they must be copied with the `SensorEvent(SensorEvent)` constructor.

    - #### SensorEvent

          public SensorEvent(SensorEvent e)

      Creates a copy of the given `SensorEvent`. Listeners must use this constructor to copy events that need to be retained. NOTE: The `Sensor` and `Object` references returned by `getSensor` and `getSource` remain references to the original objects.
      Parameters:
        `e` - the event to be copied

  - ### Method Detail

    - #### set

          public void set(java.lang.Object source,
                 int id,
                 Sensor sensor,
                 Transform3D sensorRead,
                 int[] buttonState,
                 int button,
                 long time,
                 long lastTime)

      Sets the fields of an ephemeral event. No objects are copied. An `IllegalStateException` will be thrown if this event is not ephemeral.
      Parameters:
        `source` - a reference to the originating object which instantiated the `SensorEventAgent`, usually a `Behavior`; may be null
        `id` - event type
        `sensor` - a reference to the provoking sensor
        `sensorRead` - the sensor's read value at the time of the event
        `buttonState` - the state of the sensor's buttons at the time of the event; a 1 in the array indicates that the button at that index is down, while a 0 indicates that button is up
        `button` - index of the button that changed state, from 0 to `(buttonCount - 1)`, or the value `NOBUTTON`
        `time` - the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was called to generate this event, usually from the `processStimulus` method of a Behavior
        `lastTime` - the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was last called to generate events, usually from the `processStimulus` method of a `Behavior`; may be used to measure frame time in behaviors that wake up every frame

    - #### getSource

          public java.lang.Object getSource()

      Gets a reference to the originating object which instantiated the `SensorEventAgent`, usually a `Behavior`; may be null.
      Returns:
        the originating object

    - #### getID

          public int getID()

      Gets the event type.
      Returns:
        the event id

    - #### getSensor

          public Sensor getSensor()

      Gets a reference to the provoking sensor.
      Returns:
        the provoking sensor

    - #### getTime

          public long getTime()

      Gets the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was called to generate this event, usually from the `processStimulus` method of a `Behavior`.
      Returns:
        time in nanoseconds

    - #### getLastTime

          public long getLastTime()

      Gets the time in nanoseconds at which the `dispatchEvents` method of `SensorEventAgent` was last called to generate events, usually from the `processStimulus` method of a `Behavior`; may be used to measure frame time in behaviors that wake up every frame.
      Returns:
        last time in nanoseconds

    - #### getSensorRead

          public void getSensorRead(Transform3D t)

      Copies the sensor's read value at the time of the event into the given `Transform3D`.
      Parameters:
        `t` - the transform to receive the sensor read

    - #### getButton

          public int getButton()

      Gets the index of the button that changed state when passed to a `pressed` or `released` callback. The index may range from 0 to `(sensor.getSensorButtonCount() - 1)`. The value returned is `NOBUTTON` for events passed to a `read` or `dragged` callback.
      Returns:
        the button index

    - #### getButtonState

          public void getButtonState(int[] buttonState)

      Copies the state of the sensor's buttons at the time of the event into the given array. A 1 in the array indicates that the button at that index is down, while a 0 indicates that button is up.
      Parameters:
        `buttonState` - the state of the sensor buttons

    - #### isEphemeral

          public boolean isEphemeral()

      Returns true if this event is ephemeral and is valid only until the listener returns. A copy of the event can be created by passing it to the `SensorEvent(SensorEvent)` constructor.

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