NEWTEvent: Add isConsumed() and setConsumed(boolean) methods to simpl…

…y usage, using the existing consumedTag attachment for compatibility and efficiency.

src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java

@@ -60,7 +60,6 @@
 import com.jogamp.newt.Window;
 import com.jogamp.newt.event.KeyEvent;
 import com.jogamp.newt.event.KeyListener;
-import com.jogamp.newt.event.NEWTEvent;
 import com.jogamp.newt.event.WindowAdapter;
 import com.jogamp.newt.event.WindowEvent;
 import com.jogamp.newt.event.WindowListener;
@@ -214,7 +213,7 @@ public void keyReleased(KeyEvent e) {
          }
          public void keyTyped(KeyEvent e) {
              if(suppress) {
-                 e.setAttachment(NEWTEvent.consumedTag);
+                 e.setConsumed(true);
                  suppress = false; // reset
              }             
          }
@@ -244,7 +243,7 @@ void handleKey(KeyEvent evt, boolean onRelease) {
                  }
              }
              if(suppress) {
-                 evt.setAttachment(NEWTEvent.consumedTag);                 
+                 evt.setConsumed(true);                 
              }
              if(DEBUG) {
                  System.err.println("NewtCanvasAWT.focusKey: XXX: "+ks);

src/newt/classes/com/jogamp/newt/event/NEWTEvent.java

@@ -49,8 +49,7 @@
 @SuppressWarnings("serial")
 public class NEWTEvent extends java.util.EventObject {
     /** 
-     * Object when attached via {@link #setAttachment(Object)} marks the event consumed,
-     * ie. stops propagating the event any further to the <i>other</i> event listener. 
+     * See {@link #setConsumed(boolean)} for description.
      */
     public static final Object consumedTag = new Object();
 
@@ -86,7 +85,7 @@ public final long getWhen()  {
      * @param attachment User application specific object
      */
     public final void setAttachment(Object attachment) {
-        this.attachment=attachment;
+        this.attachment = attachment;
     }
 
     /** 
@@ -95,7 +94,41 @@ public final void setAttachment(Object attachment) {
     public final Object getAttachment() {
         return attachment;
     }
-
+
+    /** 
+     * Returns <code>true</code> if this events has been {@link #setConsumed(boolean) consumed},
+     * otherwise <code>false</code>.
+     * @see #setConsumed(boolean)
+     */
+    public final boolean isConsumed() {
+        return consumedTag == attachment;
+    }
+
+    /** 
+     * If <code>consumed</code> is <code>true</code>, this event is marked as consumed,
+     * ie. the event will not be propagated any further to potential <i>other</i> event listener.
+     * Otherwise the event will be propagated to other event listener, the default.
+     * <p>
+     * The event is marked as being consumed while {@link #setAttachment(Object) attaching}
+     * the {@link #consumedTag}.
+     * </p>
+     * <p>
+     * Events with platform specific actions will be supressed if marked as consumed.
+     * Examples are:
+     * <ul>
+     *   <li>{@link KeyEvent#VK_ESCAPE} on Android's BACK button w/ Activity::finish()</li>
+     *   <li>{@link KeyEvent#VK_HOME} on Android's HOME button w/ Intend.ACTION_MAIN[Intend.CATEGORY_HOME]</li>
+     * </ul>
+     * </p>
+     */
+    public final void setConsumed(boolean consumed) {
+        if( consumed ) {
+            setAttachment( consumedTag );
+        } else if( consumedTag == attachment ) {
+            setAttachment( null );
+        }
+    }
+
     public String toString() {
         return toString(null).toString();
     }

src/newt/classes/jogamp/newt/WindowImpl.java

@@ -2194,8 +2194,7 @@ protected void consumeMouseEvent(MouseEvent e) {
         if(DEBUG_MOUSE_EVENT) {
             System.err.println("consumeMouseEvent: event:         "+e);
         }
-        boolean consumed = false;
-        for(int i = 0; !consumed && i < mouseListeners.size(); i++ ) {
+        for(int i = 0; !e.isConsumed() && i < mouseListeners.size(); i++ ) {
             MouseListener l = mouseListeners.get(i);
             switch(e.getEventType()) {
                 case MouseEvent.EVENT_MOUSE_CLICKED:
@@ -2225,7 +2224,6 @@ protected void consumeMouseEvent(MouseEvent e) {
                 default:
                     throw new NativeWindowException("Unexpected mouse event type " + e.getEventType());
             }
-            consumed = NEWTEvent.consumedTag == e.getAttachment();
         }
     }
 
@@ -2354,7 +2352,7 @@ private final boolean propagateKeyEvent(KeyEvent e, KeyListener l) {
             default:
                 throw new NativeWindowException("Unexpected key event type " + e.getEventType());
         }
-        return NEWTEvent.consumedTag == e.getAttachment();
+        return e.isConsumed();
     }
 
     @SuppressWarnings("deprecation")
@@ -2460,8 +2458,7 @@ protected void consumeWindowEvent(WindowEvent e) {
         if(DEBUG_IMPLEMENTATION) {
             System.err.println("consumeWindowEvent: "+e+", visible "+isVisible()+" "+getX()+"/"+getY()+" "+getWidth()+"x"+getHeight());
         }
-        boolean consumed = false;
-        for(int i = 0; !consumed && i < windowListeners.size(); i++ ) {
+        for(int i = 0; !e.isConsumed() && i < windowListeners.size(); i++ ) {
             WindowListener l = windowListeners.get(i);
             switch(e.getEventType()) {
                 case WindowEvent.EVENT_WINDOW_RESIZED:
@@ -2490,7 +2487,6 @@ protected void consumeWindowEvent(WindowEvent e) {
                         new NativeWindowException("Unexpected window event type "
                                                   + e.getEventType());
             }
-            consumed = NEWTEvent.consumedTag == e.getAttachment();
         }
     }