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
`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
`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.