NEWTEvent: Add isConsumed() and setConsumed(boolean) methods to simply usage, using the existing consumedTag attachment for compatibility and efficiency.

2 files changed, 39 insertions, 7 deletions

diff --git a/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java b/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
index a3c2a5dc8..d22e50cb8 100644
--- a/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
+++ b/src/newt/classes/com/jogamp/newt/awt/NewtCanvasAWT.java
@@ -60,7 +60,6 @@ import com.jogamp.newt.Display;
 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 class NewtCanvasAWT extends java.awt.Canvas implements WindowClosingProto
          }
          public void keyTyped(KeyEvent e) {
              if(suppress) {
-                 e.setAttachment(NEWTEvent.consumedTag);
+                 e.setConsumed(true);
                  suppress = false; // reset
              }             
          }
@@ -244,7 +243,7 @@ public class NewtCanvasAWT extends java.awt.Canvas implements WindowClosingProto
                  }
              }
              if(suppress) {
-                 evt.setAttachment(NEWTEvent.consumedTag);                 
+                 evt.setConsumed(true);                 
              }
              if(DEBUG) {
                  System.err.println("NewtCanvasAWT.focusKey: XXX: "+ks);
diff --git a/src/newt/classes/com/jogamp/newt/event/NEWTEvent.java b/src/newt/classes/com/jogamp/newt/event/NEWTEvent.java
index 17210cef8..67bc73652 100644
--- a/src/newt/classes/com/jogamp/newt/event/NEWTEvent.java
+++ b/src/newt/classes/com/jogamp/newt/event/NEWTEvent.java
@@ -49,8 +49,7 @@ package com.jogamp.newt.event;
 @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 class NEWTEvent extends java.util.EventObject {
      * @param attachment User application specific object
      */
     public final void setAttachment(Object attachment) {
-        this.attachment=attachment;
+        this.attachment = attachment;
     }
 
     /** 
@@ -95,7 +94,41 @@ public class NEWTEvent extends java.util.EventObject {
     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();
     }