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