MouseEvent: Clarify 'Multiple-Pointer' w/ button[mask] semantics, ; InputEvent: getButtonDownCount() and isAnyButtonDown();

- Clarify 'Multiple-Pointer' w/ button[mask] semantics

  - Pointer IDs start w/ 0 and are consecutive numbers.

  - 'button' == triggering pointer-ID

  - buttonMask in modifiers show pressed button _and_ pointer-IDs

- deprecated BUTTON_NUMBER -> use BUTTON_COUNT (name semantics)

2 files changed, 103 insertions, 32 deletions

diff --git a/src/newt/classes/com/jogamp/newt/event/InputEvent.java b/src/newt/classes/com/jogamp/newt/event/InputEvent.java
index 7712b77e7..1bd67efa5 100644
--- a/src/newt/classes/com/jogamp/newt/event/InputEvent.java
+++ b/src/newt/classes/com/jogamp/newt/event/InputEvent.java
@@ -34,6 +34,7 @@
 
 package com.jogamp.newt.event;
 
+import com.jogamp.common.util.IntBitfield;
 import com.jogamp.newt.Window;
 
 @SuppressWarnings("serial")
@@ -63,7 +64,8 @@ public abstract class InputEvent extends NEWTEvent
  public static final int  BUTTON8_MASK     = 1 << 12;
  public static final int  BUTTON9_MASK     = 1 << 13;
  
- public static final int  BUTTONLAST_MASK  = 1 << 20;  // 16
+ public static final int  BUTTONLAST_MASK  = 1 << 20;  // 16 buttons
+ public static final int  BUTTONALL_MASK   = 0xffff << 5 ;  // 16 buttons
  
  /** Event is caused by auto-repeat. */
  public static final int  AUTOREPEAT_MASK  = 1 << 29;
@@ -78,12 +80,12 @@ public abstract class InputEvent extends NEWTEvent
   * Returns the corresponding button mask for the given button.
   * <p>
   * In case the given button lies outside 
-  * of the valid range [{@link MouseEvent#BUTTON1} .. {@link MouseEvent#BUTTON_NUMBER}],
+  * of the valid range [{@link MouseEvent#BUTTON1} .. {@link MouseEvent#BUTTON_COUNT}],
   * null is returned.
   * </p>
   */
  public static final int getButtonMask(int button)  {
-     if( 0 < button && button <= MouseEvent.BUTTON_NUMBER ) {
+     if( 0 < button && button <= MouseEvent.BUTTON_COUNT ) {
          return 1 << ( 4 + button ) ;
      }
      return 0;
@@ -143,7 +145,7 @@ public abstract class InputEvent extends NEWTEvent
     if(isAltDown()) { if(!isFirst) { sb.append(", "); } isFirst = false; sb.append("alt"); }
     if(isAltGraphDown()) { if(!isFirst) { sb.append(", "); } isFirst = false; sb.append("altgr"); }
     if(isAutoRepeat()) { if(!isFirst) { sb.append(", "); } isFirst = false; sb.append("repeat"); }
-    for(int i=1; i<=MouseEvent.BUTTON_NUMBER; i++) {
+    for(int i=1; i<=MouseEvent.BUTTON_COUNT; i++) {
         if(isButtonDown(i)) { if(!isFirst) { sb.append(", "); } isFirst = false; sb.append("button").append(i); }
     }
     if(isConfined()) { if(!isFirst) { sb.append(", "); } isFirst = false; sb.append("confined"); }
@@ -154,26 +156,59 @@ public abstract class InputEvent extends NEWTEvent
  }
 
  /**
+  * See also {@link MouseEvent}'s section about <i>Multiple-Pointer Events</i>.
   * @return Array of pressed mouse buttons  [{@link MouseEvent#BUTTON1} .. {@link MouseEvent#BUTTON6}]. 
   *         If none is down, the resulting array is of length 0.
   */
  public final short[] getButtonsDown()  {
-     int len = 0;
-     for(int i=1; i<=MouseEvent.BUTTON_NUMBER; i++) {
-         if( isButtonDown(i) ) { len++; }
-     }
+     final int len = getButtonDownCount();
      
-     short[] res = new short[len];
+     final short[] res = new short[len];
      int j = 0;
-     for(int i=1; i<=MouseEvent.BUTTON_NUMBER; i++) {
+     for(int i=1; i<=MouseEvent.BUTTON_COUNT; i++) {
          if( isButtonDown(i) ) { res[j++] = (short) ( ( MouseEvent.BUTTON1 - 1 ) + i ); }
      }
      return res;
  }
 
+ /**
+  * See also {@link MouseEvent}'s section about <i>Multiple-Pointer Events</i>.
+  * @param button the button to test
+  * @return true if the given button is down 
+  */
  public final boolean isButtonDown(int button)  {
     return ( modifiers & getButtonMask(button) ) != 0;
  }
+
+ /** 
+  * Returns the number of pressed buttons by counting the set bits:
+  * <pre>
+  *     getBitCount(modifiers & BUTTONALL_MASK);
+  * </pre>
+  * <p>
+  * See also {@link MouseEvent}'s section about <i>Multiple-Pointer Events</i>.
+  * </p>
+  * @see IntBitfield#getBitCount(int)
+  * @see #BUTTONALL_MASK
+  */
+ public final int getButtonDownCount() {
+     return IntBitfield.getBitCount(modifiers & BUTTONALL_MASK);
+ }
+ 
+ /** 
+  * Returns true if at least one button is pressed, otherwise false:
+  * <pre>
+  *     0 != ( modifiers & BUTTONALL_MASK )
+  * </pre>
+  * <p>
+  * See also {@link MouseEvent}'s section about <i>Multiple-Pointer Events</i>.
+  * </p>
+  * @see IntBitfield#getBitCount(int)
+  * @see #BUTTONALL_MASK
+  */
+ public final boolean isAnyButtonDown() {
+     return 0 != ( modifiers & BUTTONALL_MASK );
+ }
  
  public String toString() {
      return toString(null).toString();
diff --git a/src/newt/classes/com/jogamp/newt/event/MouseEvent.java b/src/newt/classes/com/jogamp/newt/event/MouseEvent.java
index 2c137ab77..4e13d63fe 100644
--- a/src/newt/classes/com/jogamp/newt/event/MouseEvent.java
+++ b/src/newt/classes/com/jogamp/newt/event/MouseEvent.java
@@ -37,13 +37,24 @@ package com.jogamp.newt.event;
 /**
  * Pointer event of type {@link PointerType}.
  * <p>
+ * The historical misleading class name may change in the future to <code>PointerEvent</code>. 
+ * </p>
+ * <p>
  * http://www.w3.org/Submission/pointer-events/#pointerevent-interface
  * </p>
+ * <a name="multiPtrEvent"><h5>Multiple-Pointer Events</h5></a> 
  * <p>
  * In case an instance represents a multiple-pointer event, i.e. {@link #getPointerCount()} is &gt; 1,
- * the first data element of the multiple-pointer fields represents the pointer which triggered the action.<br/>
+ * the first data element of the multiple-pointer fields represents the pointer triggering this event.<br/>
  * For example {@link #getX(int) e.getX(0)} at {@link #EVENT_MOUSE_PRESSED} returns the data of the pressed pointer, etc.
  * </p>
+ * <p>
+ * If representing a multiple-pointer event, the {@link #getButton() button number} is equal 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.<br>
+ * 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()}. 
+ * </p>
  */
 @SuppressWarnings("serial")
 public class MouseEvent extends InputEvent
@@ -93,8 +104,14 @@ public class MouseEvent extends InputEvent
     public static final short BUTTON9 = 9;
     
     /** Maximum number of buttons, value <code>16</code> */
-    public static final short BUTTON_NUMBER =  16;
+    public static final short BUTTON_COUNT =  16;
 
+    /** 
+     * Maximum number of buttons, value <code>16</code>.
+     * @deprecated Use {@link #BUTTON_COUNT} .. semantics.
+     */
+    public static final short BUTTON_NUMBER =  16;
+    
     /** Returns the 3-axis XYZ rotation array by given rotation on Y axis or X axis (if SHIFT_MASK is given in mods). */ 
     public static final float[] getRotationXYZ(final float rotationXorY, final int mods) {
         final float[] rotationXYZ = new float[] { 0f, 0f, 0f };
@@ -132,14 +149,17 @@ public class MouseEvent extends InputEvent
      * Constructor for a multiple-pointer event.
      * <p>
      * First element of multiple-pointer arrays represents the pointer which triggered the event!
-     * </p>  
+     * </p>
+     * <p>  
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
+     * </p>
      * 
      * @param eventType
      * @param source
      * @param when
      * @param modifiers
      * @param pointerType PointerType for each pointer (multiple pointer)
-     * @param pointerID Pointer ID for each pointer (multiple pointer)
+     * @param pointerID Pointer ID for each pointer (multiple pointer). IDs start w/ 0 and are consecutive numbers.
      * @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)
@@ -185,9 +205,13 @@ public class MouseEvent extends InputEvent
     /**
      * Factory for a multiple-pointer event.
      * <p>
-     * The index for the element of multiple-pointer arrays represents the pointer which triggered the event
-     * is passed via <i>actionIdx</i>.
+     * The index for the multiple-pointer fields representing the triggering pointer is passed via <i>actionIdx</i>.
+     * If <i>actionIdx</i> is not <code>0</code>, all multiple-pointer fields values of index <code>0</code>
+     * and <i>actionIdx</i> are swapped so that the pointer-index 0 will represent the triggering pointer.
      * </p>  
+     * <p>  
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
+     * </p>
      * 
      * @param eventType
      * @param source
@@ -195,7 +219,7 @@ public class MouseEvent extends InputEvent
      * @param modifiers
      * @param actionIdx index of multiple-pointer arrays representing the pointer which triggered the event
      * @param pointerType PointerType for each pointer (multiple pointer)
-     * @param pointerID Pointer ID for each pointer (multiple pointer)
+     * @param pointerID Pointer ID for each pointer (multiple pointer). IDs start w/ 0 and are consecutive numbers.
      * @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)
@@ -269,7 +293,7 @@ public class MouseEvent extends InputEvent
     
     /**
      * @return the pointer id for the given index.
-     *  return -1 if index not available.
+     *  return -1 if index not available. IDs start w/ 0 and are consecutive numbers.
      */
     public final short getPointerId(int index) {
         if(0 > index || index >= pointerID.length) {
@@ -292,16 +316,22 @@ public class MouseEvent extends InputEvent
     }
     
     /**
-     * @return array of all pointer IDs for all pointers
+     * @return array of all pointer IDs for all pointers. IDs start w/ 0 and are consecutive numbers.
      */
     public final short[] getAllPointerIDs() {
         return pointerID;
     }
     
+    /** 
+     * Returns the button number, e.g. [{@link #BUTTON1}..{@link #BUTTON_COUNT}-1].
+     * <p>
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
+     * </p> 
+     */
     public final short getButton() {
         return button;
     }
-    
+
     public final short getClickCount() {
         return clickCount;
     }
@@ -315,6 +345,7 @@ public class MouseEvent extends InputEvent
     }
 
     /** 
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
      * @param index pointer-index within [0 .. {@link #getPointerCount()}-1]
      * @return X-Coord associated with the pointer-index.
      * @see getPointerId(index)
@@ -324,6 +355,7 @@ public class MouseEvent extends InputEvent
     }
 
     /** 
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
      * @param index pointer-index within [0 .. {@link #getPointerCount()}-1]
      * @return Y-Coord associated with the pointer-index.
      * @see getPointerId(index)
@@ -333,6 +365,7 @@ public class MouseEvent extends InputEvent
     }
     
     /**
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
      * @return array of all X-Coords for all pointers
      */
     public final int[] getAllX() {
@@ -340,6 +373,7 @@ public class MouseEvent extends InputEvent
     }
     
     /**
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
      * @return array of all Y-Coords for all pointers
      */
     public final int[] getAllY() {
@@ -357,6 +391,19 @@ public class MouseEvent extends InputEvent
     }
     
     /**
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
+     * @param index pointer-index within [0 .. {@link #getPointerCount()}-1]
+     * @param normalized if true, method returns the normalized pressure, i.e. <code>pressure / maxPressure</code> 
+     * @return The pressure associated with the pointer-index.
+     *         The value of zero is return if not available.
+     * @see #getMaxPressure()
+     */
+    public final float getPressure(int index, boolean normalized){
+        return normalized ? pressure[index] / maxPressure : pressure[index];
+    }
+    
+    /**
+     * See details for <a href="#multiPtrEvent">multiple-pointer events</a>.
      * @return array of all raw, un-normalized pressures for all pointers
      */
     public final float[] getAllPressures() {
@@ -381,17 +428,6 @@ public class MouseEvent extends InputEvent
     }
     
     /**
-     * @param index pointer-index within [0 .. {@link #getPointerCount()}-1]
-     * @param normalized if true, method returns the normalized pressure, i.e. <code>pressure / maxPressure</code> 
-     * @return The pressure associated with the pointer-index.
-     *         The value of zero is return if not available.
-     * @see #getMaxPressure()
-     */
-    public final float getPressure(int index, boolean normalized){
-        return normalized ? pressure[index] / maxPressure : pressure[index];
-    }
-    
-    /**
      * Returns a 3-component float array filled with the values of the rotational axis
      * in the following order: horizontal-, vertical- and z-axis.
      * <p> 
@@ -496,7 +532,7 @@ public class MouseEvent extends InputEvent
     
     /** PointerType for each pointer (multiple pointer) */
     private final PointerType pointerType[];
-    /** Pointer-ID for each pointer (multiple pointer) */
+    /** Pointer-ID for each pointer (multiple pointer). IDs start w/ 0 and are consecutive numbers. */
     private final short pointerID[];
     /** X-axis for each pointer (multiple pointer) */
     private final int x[];