From 2ebf1bf35928e35ded6e38df64dee7aa578ae3c7 Mon Sep 17 00:00:00 2001 From: Sven Gothel Date: Fri, 18 Oct 2013 02:27:33 +0200 Subject: MouseEvent: Clarify button-number and pointer-ID relation incl. case 'no button/pointer', i.e. button == 0, pointer-ID == -1 doPointerEvent: - allow id==-1 -> button==0 for no button, i.e. mouse move doMouseEvent: - keep button 0 value, i.e. map to pointer-ID -1 --- .../classes/com/jogamp/newt/event/MouseEvent.java | 83 ++++++++++++++++++---- 1 file changed, 69 insertions(+), 14 deletions(-) (limited to 'src/newt/classes/com') diff --git a/src/newt/classes/com/jogamp/newt/event/MouseEvent.java b/src/newt/classes/com/jogamp/newt/event/MouseEvent.java index 85c65b39c..57dd7e68c 100644 --- a/src/newt/classes/com/jogamp/newt/event/MouseEvent.java +++ b/src/newt/classes/com/jogamp/newt/event/MouseEvent.java @@ -49,9 +49,21 @@ package com.jogamp.newt.event; * For example {@link #getX(int) e.getX(0)} at {@link #EVENT_MOUSE_PRESSED} returns the data of the pressed pointer, etc. *

*

- * If representing a multiple-pointer event, the {@link #getButton() button number} is equal to the first {@link #getPointerId(int) pointer ID} + * A {@link #getButton() button value} of 0 denotes no button activity, i.e. {@link PointerType#Mouse} move. + *

+ *

+ * A {@link #getPointerId(int) pointer-ID} of -1 denotes no pointer/button activity, i.e. {@link PointerType#Mouse} move. + *

+ *

+ * {@link #getButton() Button values} are mapped from and to {@link #getPointerId(int) pointer-IDs} as follows: + * + * getPointerId(0) == getButton() - 1 + * . + *

+ *

+ * If representing a multiple-pointer event, the {@link #getButton() button number} is mapped to the first {@link #getPointerId(int) pointer ID} * triggering the event and the {@link InputEvent#BUTTON1_MASK button mask bits} in the {@link #getModifiers() modifiers} - * field represents the pressed pointer IDs.
+ * field represent the pressed pointer IDs.
* Hence users can query the pressed button count as well as the pressed pointer count via {@link InputEvent#getButtonDownCount()} * or use the simple query {@link InputEvent#isAnyButtonDown()}. *

@@ -162,7 +174,21 @@ public class MouseEvent extends InputEvent return 300; } - /** Constructor for traditional one-pointer event. */ + /** + * Constructor for traditional one-pointer event. + * + * @param eventType + * @param source + * @param when + * @param modifiers + * @param x X-axis + * @param y Y-axis + * @param clickCount Mouse-button click-count + * @param button button number, e.g. [{@link #BUTTON1}..{@link #BUTTON_COUNT}-1]. + * A button value of 0 denotes no button activity, i.e. {@link PointerType#Mouse} move. + * @param rotationXYZ Rotation of all axis + * @param rotationScale Rotation scale + */ public MouseEvent(short eventType, Object source, long when, int modifiers, int x, int y, short clickCount, short button, float[] rotationXYZ, float rotationScale) @@ -203,6 +229,7 @@ public class MouseEvent extends InputEvent * @param modifiers * @param pointerType PointerType for each pointer (multiple pointer) * @param 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. {@link PointerType#Mouse} move. * @param x X-axis for each pointer (multiple pointer) * @param y Y-axis for each pointer (multiple pointer) * @param pressure Pressure for each pointer (multiple pointer) @@ -246,6 +273,7 @@ public class MouseEvent extends InputEvent } /** + * See details for multiple-pointer events. * @return the count of pointers involved in this event */ public final int getPointerCount() { @@ -253,8 +281,8 @@ public class MouseEvent extends InputEvent } /** - * @return the {@link PointerType} for the data at index. - * return null if index not available. + * See details for multiple-pointer events. + * @return the {@link PointerType} for the data at index or null if index not available. */ public final PointerType getPointerType(int index) { if(0 > index || index >= pointerType.length) { @@ -264,6 +292,7 @@ public class MouseEvent extends InputEvent } /** + * See details for multiple-pointer events. * @return array of all {@link PointerType}s for all pointers */ public final PointerType[] getAllPointerTypes() { @@ -271,8 +300,16 @@ public class MouseEvent extends InputEvent } /** - * @return the pointer id for the given index. - * return -1 if index not available. IDs start w/ 0 and are consecutive numbers. + * Return the pointer id for the given index or -1 if index not available. + *

+ * IDs start w/ 0 and are consecutive numbers. + *

+ *

+ * A pointer-ID of -1 may also denote no pointer/button activity, i.e. {@link PointerType#Mouse} move. + *

+ *

+ * See details for multiple-pointer events. + *

*/ public final short getPointerId(int index) { if(0 > index || index >= pointerID.length) { @@ -282,19 +319,22 @@ public class MouseEvent extends InputEvent } /** - * @return the pointer index for the given pointer id. - * return -1 if id not available. + * See details for multiple-pointer events. + * @return the pointer index for the given pointer id or -1 if id not available. */ public final int getPointerIdx(short id) { - for(int i=pointerID.length-1; i>=0; i--) { - if( pointerID[i] == id ) { - return i; + if( id >= 0 ) { + for(int i=pointerID.length-1; i>=0; i--) { + if( pointerID[i] == id ) { + return i; + } } } return -1; } /** + * See details for multiple-pointer events. * @return array of all pointer IDs for all pointers. IDs start w/ 0 and are consecutive numbers. */ public final short[] getAllPointerIDs() { @@ -304,6 +344,9 @@ public class MouseEvent extends InputEvent /** * Returns the button number, e.g. [{@link #BUTTON1}..{@link #BUTTON_COUNT}-1]. *

+ * A button value of 0 denotes no button activity, i.e. {@link PointerType#Mouse} move. + *

+ *

* See details for multiple-pointer events. *

*/ @@ -511,7 +554,12 @@ public class MouseEvent extends InputEvent /** PointerType for each pointer (multiple pointer) */ private final PointerType pointerType[]; - /** Pointer-ID for each pointer (multiple pointer). IDs start w/ 0 and are consecutive numbers. */ + /** + * 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. {@link PointerType#Mouse} move. + *

+ */ private final short pointerID[]; /** X-axis for each pointer (multiple pointer) */ private final int x[]; @@ -520,7 +568,14 @@ public class MouseEvent extends InputEvent /** Pressure for each pointer (multiple pointer) */ private final float pressure[]; // private final short tiltX[], tiltY[]; // TODO: A generic way for pointer axis information, see Android MotionEvent! - private final short clickCount, button; + private final short clickCount; + /** + * Returns the button number, e.g. [{@link #BUTTON1}..{@link #BUTTON_COUNT}-1]. + *

+ * A button value of 0 denotes no button activity, i.e. {@link PointerType#Mouse} move. + *

+ */ + private final short button; /** Rotation around the X, Y and X axis */ private final float[] rotationXYZ; /** Rotation scale */ -- cgit v1.2.3