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

# Class SensorEvent

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

public class SensorEvent extends 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
Description
`static final int`
`DRAGGED`
A button dragged event.
`static final int`
`NOBUTTON`
The value that is returned by `getButton` when no buttons have changed state.
`static final int`
`PRESSED`
A button pressed event.
`static final int`
`READ`
A sensor read event.
`static final int`
`RELEASED`
A button released event.

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
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`.
`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(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 Details

### 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 Details

### SensorEvent

public SensorEvent(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 Details

### set

public void set(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 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.