com.jogamp.newt.event

## Class MouseEvent

- java.lang.Object
- - java.util.EventObject
  - - com.jogamp.newt.event.NEWTEvent
    - - com.jogamp.newt.event.InputEvent
      - - com.jogamp.newt.event.MouseEvent

- All Implemented Interfaces:
    Serializable

      public class MouseEvent
      extends InputEvent

  Pointer event of type `MouseEvent.PointerType`.

  The historical misleading class name may change in the future to `PointerEvent`.

  http://www.w3.org/Submission/pointer-events/#pointerevent-interface

  ##### Unit of Coordinates

  All pointer coordinates of this interface are represented in pixel units, see `NativeSurface` and `NativeWindow`.

  ##### Multiple-Pointer Events

  In case an instance represents a multiple-pointer event, i.e. `getPointerCount()` is > 1, the first data element of the multiple-pointer fields represents the pointer triggering this event.
  For example `e.getX(0)` at `EVENT_MOUSE_PRESSED` returns the data of the pressed pointer, etc.

  Multiple-pointer event's `button number` is mapped to the first `pointer ID` triggering the event and the `button mask bits` in the `modifiers` field represent the pressed pointer IDs.

  Users can query the pressed button and pointer count via `InputEvent.getButtonDownCount()` or use the simple query `InputEvent.isAnyButtonDown()`.

  If representing a single-pointer `MouseEvent.PointerType.Mouse` event, `pointer-ID` is `0` and a `button value` of `0` denotes no button activity, i.e. `MouseEvent.PointerType.Mouse` move.

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `MouseEvent.PointerClass` Class of pointer types
    `static class` | `MouseEvent.PointerType` Type of pointer devices

    - ### Nested classes/interfaces inherited from class com.jogamp.newt.event.InputEvent

      `InputEvent.InputClass, InputEvent.InputType`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static short` | `BUTTON_COUNT` Maximum number of buttons, value `16`
    `static short` | `BUTTON1` ID for button 1, value `1`
    `static short` | `BUTTON2` ID for button 2, value `2`
    `static short` | `BUTTON3` ID for button 3, value `3`
    `static short` | `BUTTON4` ID for button 4, value `4`
    `static short` | `BUTTON5` ID for button 5, value `5`
    `static short` | `BUTTON6` ID for button 6, value `6`
    `static short` | `BUTTON7` ID for button 6, value `7`
    `static short` | `BUTTON8` ID for button 6, value `8`
    `static short` | `BUTTON9` ID for button 6, value `9`
    `static short` | `EVENT_MOUSE_CLICKED`
    `static short` | `EVENT_MOUSE_DRAGGED`
    `static short` | `EVENT_MOUSE_ENTERED` Only generated for `MouseEvent.PointerType.Mouse`
    `static short` | `EVENT_MOUSE_EXITED` Only generated for `MouseEvent.PointerType.Mouse`
    `static short` | `EVENT_MOUSE_MOVED`
    `static short` | `EVENT_MOUSE_PRESSED`
    `static short` | `EVENT_MOUSE_RELEASED`
    `static short` | `EVENT_MOUSE_WHEEL_MOVED`

    - ### Fields inherited from class com.jogamp.newt.event.InputEvent

      `ALT_GRAPH_MASK, ALT_MASK, AUTOREPEAT_MASK, BUTTON1_MASK, BUTTON2_MASK, BUTTON3_MASK, BUTTON4_MASK, BUTTON5_MASK, BUTTON6_MASK, BUTTON7_MASK, BUTTON8_MASK, BUTTON9_MASK, BUTTONALL_MASK, BUTTONLAST_MASK, CONFINED_MASK, CTRL_MASK, INVISIBLE_MASK, META_MASK, SHIFT_MASK`

    - ### Fields inherited from class com.jogamp.newt.event.NEWTEvent

      `consumedTag`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MouseEvent(short eventType, Object source, long when, int modifiers, int x, int y, short clickCount, short button, float[] rotationXYZ, float rotationScale)` Constructor for traditional one-pointer event.
    `MouseEvent(short eventType, Object source, long when, int modifiers, MouseEvent.PointerType[] pointerType, short[] pointerID, int[] x, int[] y, float[] pressure, float maxPressure, short button, short clickCount, float[] rotationXYZ, float rotationScale)` Constructor for a multiple-pointer event.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `MouseEvent` | `createVariant(short newEventType)`
    `short[]` | `getAllPointerIDs()` See details for multiple-pointer events.
    `MouseEvent.PointerType[]` | `getAllPointerTypes()` See details for multiple-pointer events.
    `float[]` | `getAllPressures()` See details for multiple-pointer events.
    `int[]` | `getAllX()` See details for multiple-pointer events.
    `int[]` | `getAllY()` See details for multiple-pointer events.
    `short` | `getButton()` Returns the button number, e.g.
    `short` | `getClickCount()`
    `static short` | `getClickTimeout()`
    `static String` | `getEventTypeString(short type)`
    `float` | `getMaxPressure()` Returns the maximum pressure known for the input device generating this event.
    `int` | `getPointerCount()` See details for multiple-pointer events.
    `short` | `getPointerId(int index)` Return the pointer id for the given index or -1 if index not available.
    `int` | `getPointerIdx(short id)` See details for multiple-pointer events.
    `MouseEvent.PointerType` | `getPointerType(int index)` See details for multiple-pointer events.
    `float` | `getPressure(boolean normalized)`
    `float` | `getPressure(int index, boolean normalized)` See details for multiple-pointer events.
    `float[]` | `getRotation()` Returns a 3-component float array filled with the values of the rotational axis in the following order: horizontal-, vertical- and z-axis.
    `float` | `getRotationScale()` Returns the scale used to determine the `rotation value`, which semantics depends on the `pointer type's` `MouseEvent.PointerClass`.
    `static float[]` | `getRotationXYZ(float rotationXorY, int mods)` Returns the 3-axis XYZ rotation array by given rotation on Y axis or X axis (if SHIFT_MASK is given in mods).
    `int` | `getX()` See details for multiple-pointer events.
    `int` | `getX(int index)` See details for multiple-pointer events.
    `int` | `getY()` See details for multiple-pointer events.
    `int` | `getY(int index)` See details for multiple-pointer events.
    `String` | `toString()`
    `StringBuilder` | `toString(StringBuilder sb)`

    - ### Methods inherited from class com.jogamp.newt.event.InputEvent

      `getButtonDownCount, getButtonMask, getButtonsDown, getModifiers, getModifiersString, isAltDown, isAltGraphDown, isAnyButtonDown, isAutoRepeat, isButtonDown, isConfined, isControlDown, isInvisible, isMetaDown, isShiftDown`

    - ### Methods inherited from class com.jogamp.newt.event.NEWTEvent

      `getAttachment, getEventType, getWhen, isConsumed, setAttachment, setConsumed, toHexString`

    - ### Methods inherited from class java.util.EventObject

      `getSource`

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

      `equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### BUTTON1

          public static final short BUTTON1

      ID for button 1, value `1`
      See Also:
        Constant Field Values

    - #### BUTTON2

          public static final short BUTTON2

      ID for button 2, value `2`
      See Also:
        Constant Field Values

    - #### BUTTON3

          public static final short BUTTON3

      ID for button 3, value `3`
      See Also:
        Constant Field Values

    - #### BUTTON4

          public static final short BUTTON4

      ID for button 4, value `4`
      See Also:
        Constant Field Values

    - #### BUTTON5

          public static final short BUTTON5

      ID for button 5, value `5`
      See Also:
        Constant Field Values

    - #### BUTTON6

          public static final short BUTTON6

      ID for button 6, value `6`
      See Also:
        Constant Field Values

    - #### BUTTON7

          public static final short BUTTON7

      ID for button 6, value `7`
      See Also:
        Constant Field Values

    - #### BUTTON8

          public static final short BUTTON8

      ID for button 6, value `8`
      See Also:
        Constant Field Values

    - #### BUTTON9

          public static final short BUTTON9

      ID for button 6, value `9`
      See Also:
        Constant Field Values

    - #### BUTTON_COUNT

          public static final short BUTTON_COUNT

      Maximum number of buttons, value `16`
      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_CLICKED

          public static final short EVENT_MOUSE_CLICKED

      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_ENTERED

          public static final short EVENT_MOUSE_ENTERED

      Only generated for `MouseEvent.PointerType.Mouse`
      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_EXITED

          public static final short EVENT_MOUSE_EXITED

      Only generated for `MouseEvent.PointerType.Mouse`
      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_PRESSED

          public static final short EVENT_MOUSE_PRESSED

      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_RELEASED

          public static final short EVENT_MOUSE_RELEASED

      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_MOVED

          public static final short EVENT_MOUSE_MOVED

      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_DRAGGED

          public static final short EVENT_MOUSE_DRAGGED

      See Also:
        Constant Field Values

    - #### EVENT_MOUSE_WHEEL_MOVED

          public static final short EVENT_MOUSE_WHEEL_MOVED

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MouseEvent

          public MouseEvent(short eventType,
                    Object source,
                    long when,
                    int modifiers,
                    int x,
                    int y,
                    short clickCount,
                    short button,
                    float[] rotationXYZ,
                    float rotationScale)

      Constructor for traditional one-pointer event.
      Parameters:
        `eventType` -
        `source` -
        `when` -
        `modifiers` -
        `x` - X-axis
        `y` - Y-axis
        `clickCount` - Mouse-button click-count
        `button` - button number, e.g. [`BUTTON1`..`BUTTON_COUNT`-1]. A button value of `0` denotes no button activity, i.e. `MouseEvent.PointerType.Mouse` move.
        `rotationXYZ` - Rotation of all axis
        `rotationScale` - Rotation scale

    - #### MouseEvent

          public MouseEvent(short eventType,
                    Object source,
                    long when,
                    int modifiers,
                    MouseEvent.PointerType[] pointerType,
                    short[] pointerID,
                    int[] x,
                    int[] y,
                    float[] pressure,
                    float maxPressure,
                    short button,
                    short clickCount,
                    float[] rotationXYZ,
                    float rotationScale)

      Constructor for a multiple-pointer event.

      First element of multiple-pointer arrays represents the pointer which triggered the event!

      See details for multiple-pointer events.

      Parameters:
        `eventType` -
        `source` -
        `when` -
        `modifiers` -
        `pointerType` - PointerType for each pointer (multiple pointer)
        `pointerID` - Pointer ID for each pointer (multiple pointer). IDs start w/ 0 and are consecutive numbers. A pointer-ID of -1 may also denote no pointer/button activity, i.e. `MouseEvent.PointerType.Mouse` move.
        `x` - X-axis for each pointer (multiple pointer)
        `y` - Y-axis for each pointer (multiple pointer)
        `pressure` - Pressure for each pointer (multiple pointer)
        `maxPressure` - Maximum pointer pressure for all pointer
        `button` - Corresponding mouse-button
        `clickCount` - Mouse-button click-count
        `rotationXYZ` - Rotation of all axis
        `rotationScale` - Rotation scale

  - ### Method Detail

    - #### getRotationXYZ

          public static final float[] getRotationXYZ(float rotationXorY,
                               int mods)

      Returns the 3-axis XYZ rotation array by given rotation on Y axis or X axis (if SHIFT_MASK is given in mods).

    - #### getClickTimeout

          public static final short getClickTimeout()

    - #### createVariant

          public final MouseEvent createVariant(short newEventType)

    - #### getPointerCount

          public final int getPointerCount()

      See details for multiple-pointer events.
      Returns:
        the count of pointers involved in this event

    - #### getPointerType

          public final MouseEvent.PointerType getPointerType(int index)

      See details for multiple-pointer events.
      Returns:
        the `MouseEvent.PointerType` for the data at index or null if index not available.

    - #### getAllPointerTypes

          public final MouseEvent.PointerType[] getAllPointerTypes()

      See details for multiple-pointer events.
      Returns:
        array of all `MouseEvent.PointerType`s for all pointers

    - #### getPointerId

          public final short getPointerId(int index)

      Return the pointer id for the given index or -1 if index not available.

      IDs start w/ 0 and are consecutive numbers.

      See details for multiple-pointer events.

    - #### getPointerIdx

          public final int getPointerIdx(short id)

      See details for multiple-pointer events.
      Returns:
        the pointer index for the given pointer id or -1 if id not available.

    - #### getAllPointerIDs

          public final short[] getAllPointerIDs()

      See details for multiple-pointer events.
      Returns:
        array of all pointer IDs for all pointers. IDs start w/ 0 and are consecutive numbers.

    - #### getButton

          public final short getButton()

      Returns the button number, e.g. [`BUTTON1`..`BUTTON_COUNT`-1].

      A button value of `0` denotes no button activity, i.e. `MouseEvent.PointerType.Mouse` move.

      See details for multiple-pointer events.

    - #### getClickCount

          public final short getClickCount()

    - #### getX

          public final int getX()

      See details for multiple-pointer events.
      Returns:
        X-Coord of the triggering pointer-index zero in pixel units.

    - #### getY

          public final int getY()

      See details for multiple-pointer events.
      Returns:
        Y-Coord of the triggering pointer-index zero in pixel units.

    - #### getX

          public final int getX(int index)

      See details for multiple-pointer events.
      Parameters:
        `index` - pointer-index within [0 .. `getPointerCount()`-1]
      Returns:
        X-Coord associated with the pointer-index in pixel units.
      See Also:
        `getPointerId(index)`

    - #### getY

          public final int getY(int index)

      See details for multiple-pointer events.
      Parameters:
        `index` - pointer-index within [0 .. `getPointerCount()`-1]
      Returns:
        Y-Coord associated with the pointer-index in pixel units.
      See Also:
        `getPointerId(index)`

    - #### getAllX

          public final int[] getAllX()

      See details for multiple-pointer events.
      Returns:
        array of all X-Coords for all pointers in pixel units.

    - #### getAllY

          public final int[] getAllY()

      See details for multiple-pointer events.
      Returns:
        array of all Y-Coords for all pointers in pixel units.

    - #### getPressure

          public final float getPressure(boolean normalized)

      Parameters:
        `normalized` - if true, method returns the normalized pressure, i.e. `pressure / maxPressure`
      Returns:
        The pressure associated with the pointer-index 0. The value of zero is return if not available.
      See Also:
        `getMaxPressure()`

    - #### getPressure

          public final float getPressure(int index,
                          boolean normalized)

      See details for multiple-pointer events.
      Parameters:
        `index` - pointer-index within [0 .. `getPointerCount()`-1]
        `normalized` - if true, method returns the normalized pressure, i.e. `pressure / maxPressure`
      Returns:
        The pressure associated with the pointer-index. The value of zero is return if not available.
      See Also:
        `getMaxPressure()`

    - #### getAllPressures

          public final float[] getAllPressures()

      See details for multiple-pointer events.
      Returns:
        array of all raw, un-normalized pressures for all pointers

    - #### getMaxPressure

          public final float getMaxPressure()

      Returns the maximum pressure known for the input device generating this event.

      This value may be self calibrating on devices/OS, where no known maximum pressure is known. Hence subsequent events may return a higher value.

      Self calibrating maximum pressure is performed on:

      - Android

    - #### getRotation

          public final float[] getRotation()

      Returns a 3-component float array filled with the values of the rotational axis in the following order: horizontal-, vertical- and z-axis.

      A vertical rotation of > 0.0f is up and < 0.0f is down.

      A horizontal rotation of > 0.0f is left and < 0.0f is right.

      A z-axis rotation of > 0.0f is back and < 0.0f is front.

      However, on some OS this might be flipped due to the OS default behavior. The latter is true for OS X 10.7 (Lion) for example.

      On PointerClass `onscreen` devices, i.e. `touch screens`, rotation events are usually produced by a 2-finger movement, where horizontal and vertical rotation values are filled.

      On PointerClass `offscreen` devices, i.e. `mouse`, either the horizontal or the vertical rotation value is filled.

      The `InputEvent.SHIFT_MASK` modifier is set in case |horizontal| > |vertical| value.
      This can be utilized to implement only one 2d rotation direction, you may use `InputEvent.isShiftDown()` to query it.

      In case the pointer type is `mouse`, events are usually send in steps of one, ie. -1.0f and 1.0f. Higher values may result due to fast scrolling. Fractional values may result due to slow scrolling with high resolution devices.
      Here the button number refers to the wheel number.

      In case the pointer type is of class `MouseEvent.PointerClass.Onscreen`, e.g. `touch screen`, see `getRotationScale()` for semantics.

    - #### getRotationScale

          public final float getRotationScale()

      Returns the scale used to determine the `rotation value`, which semantics depends on the `pointer type's` `MouseEvent.PointerClass`.

      For `MouseEvent.PointerClass.Offscreen`, the scale is usually `1.0f` and denominates an abstract value without association to a physical value.

      For `MouseEvent.PointerClass.Onscreen`, the scale varies and denominates the divisor of the distance the finger[s] have moved on the screen. Hence `scale * rotation` reproduces the screen distance in pixels the finger[s] have moved.

    - #### toString

          public final String toString()

      Overrides:
        `toString` in class `InputEvent`

    - #### toString

          public final StringBuilder toString(StringBuilder sb)

      Overrides:
        `toString` in class `InputEvent`

    - #### getEventTypeString

          public static String getEventTypeString(short type)

Copyright 2010 JogAmp Community.