Fix Bug 688: Removal of NEWT KeyEvent.EVENT_KEY_TYPED and KeyListener.keyTyped(KeyEvent) - Part2: API Documentation and Comments

7 files changed, 16 insertions, 28 deletions

diff --git a/src/newt/classes/com/jogamp/newt/event/KeyEvent.java b/src/newt/classes/com/jogamp/newt/event/KeyEvent.java
index 683a5ca54..ec05a34ad 100644
--- a/src/newt/classes/com/jogamp/newt/event/KeyEvent.java
+++ b/src/newt/classes/com/jogamp/newt/event/KeyEvent.java
@@ -43,9 +43,8 @@ import com.jogamp.common.util.IntBitfield;
  * <p>
  * <table border="0">
  *   <tr><th>#</th><th>Event Type</th>      <th>Constraints</th>  <th>Notes</th></tr>
- *   <tr><td>1</td><td>{@link #EVENT_KEY_PRESSED}  </td><td> <i> excluding {@link #isAutoRepeat() auto-repeat} {@link #isModifierKey() modifier} keys</i></td><td></td></tr>
- *   <tr><td>2</td><td>{@link #EVENT_KEY_RELEASED} </td><td> <i> excluding {@link #isAutoRepeat() auto-repeat} {@link #isModifierKey() modifier} keys</i></td><td></td></tr>
- *   <tr><td>3</td><td>{@link #EVENT_KEY_TYPED}    </td><td> <i>only for {@link #isPrintableKey() printable} and non {@link #isAutoRepeat() auto-repeat} keys</i></td><td><b>Deprecated</b>: Use {@link #EVENT_KEY_RELEASED} and apply constraints.</td></tr>
+ *   <tr><td>1</td><td>{@link #EVENT_KEY_PRESSED}  </td><td> <i> excluding {@link #isAutoRepeat() auto-repeat}-{@link #isModifierKey() modifier} keys</i></td><td></td></tr>
+ *   <tr><td>2</td><td>{@link #EVENT_KEY_RELEASED} </td><td> <i> excluding {@link #isAutoRepeat() auto-repeat}-{@link #isModifierKey() modifier} keys</i></td><td></td></tr>
  * </table>
  * </p>
  * In case the native platform does not
@@ -58,27 +57,24 @@ import com.jogamp.common.util.IntBitfield;
  * <p>
  * Auto-Repeat shall behave as follow:
  * <pre>
-    P = pressed, R = released, T = typed
+    P = pressed, R = released
     0 = normal, 1 = auto-repeat
 
-    P(0), [ R(1), P(1), R(1), ..], R(0) T(0)    
+    P(0), [ R(1), P(1), R(1), ..], R(0)    
  * </pre>
  * The idea is if you mask out auto-repeat in your event listener
- * or catch {@link #EVENT_KEY_TYPED typed} events only, 
- * you just get one long pressed P/R/T triple for {@link #isPrintableKey() printable} keys.
- * {@link #isActionKey() Action} keys would produce one long pressed P/R tuple in case you mask out auto-repeat . 
+ * you just get one long pressed P/R tuple for {@link #isPrintableKey() printable} and {@link #isActionKey() Action} keys.
  * </p>
  * <p>
  * {@link #isActionKey() Action} keys will produce {@link #EVENT_KEY_PRESSED pressed} 
  * and {@link #EVENT_KEY_RELEASED released} events including {@link #isAutoRepeat() auto-repeat}.
  * </p>
  * <p>
- * {@link #isPrintableKey() Printable} keys will produce {@link #EVENT_KEY_PRESSED pressed}, 
- * {@link #EVENT_KEY_RELEASED released} and {@link #EVENT_KEY_TYPED typed} events, the latter is excluded for {@link #isAutoRepeat() auto-repeat} events.
+ * {@link #isPrintableKey() Printable} keys will produce {@link #EVENT_KEY_PRESSED pressed} and {@link #EVENT_KEY_RELEASED released} events.
  * </p>
  * <p>
- * {@link #isModifierKey() Modifier} keys will produce {@link #EVENT_KEY_PRESSED pressed} 
- * and {@link #EVENT_KEY_RELEASED released} events excluding {@link #isAutoRepeat() auto-repeat}.
+ * {@link #isModifierKey() Modifier} keys will produce {@link #EVENT_KEY_PRESSED pressed} and {@link #EVENT_KEY_RELEASED released} events 
+ * excluding {@link #isAutoRepeat() auto-repeat}.
  * They will also influence subsequent event's {@link #getModifiers() modifier} bits while pressed.
  * </p>
  * 
@@ -360,9 +356,9 @@ public class KeyEvent extends InputEvent
     private static final byte F_ACTION_MASK     = 1 << 1;
     private static final byte F_PRINTABLE_MASK  = 1 << 2;
 
-    /** A key has been pressed, excluding {@link #isAutoRepeat() auto-repeat} {@link #isModifierKey() modifier} keys. */
+    /** A key has been pressed, excluding {@link #isAutoRepeat() auto-repeat}-{@link #isModifierKey() modifier} keys. */
     public static final short EVENT_KEY_PRESSED = 300;
-    /** A key has been released, excluding {@link #isAutoRepeat() auto-repeat} {@link #isModifierKey() modifier} keys. */
+    /** A key has been released, excluding {@link #isAutoRepeat() auto-repeat}-{@link #isModifierKey() modifier} keys. */
     public static final short EVENT_KEY_RELEASED= 301;
 
     /**
diff --git a/src/newt/classes/jogamp/newt/driver/macosx/WindowDriver.java b/src/newt/classes/jogamp/newt/driver/macosx/WindowDriver.java
index 6370782df..6aebf0410 100644
--- a/src/newt/classes/jogamp/newt/driver/macosx/WindowDriver.java
+++ b/src/newt/classes/jogamp/newt/driver/macosx/WindowDriver.java
@@ -423,8 +423,8 @@ public class WindowDriver extends WindowImpl implements MutableSurface, DriverCl
                                ", was: pressed "+isKeyPressed(keyCode)+", isModifierKeyCode "+isModifierKeyCode);
         } */
             
-        // 1:1 Order: OSX and NEWT delivery order is PRESSED, RELEASED and TYPED            
-        // Auto-Repeat: OSX delivers only PRESSED, inject auto-repeat RELEASE and TYPED keys _before_ PRESSED
+        // OSX delivery order is PRESSED (t0), RELEASED (t1) and TYPED (t2) -> NEWT order: PRESSED (t0) and RELEASED (t1)
+        // Auto-Repeat: OSX delivers only PRESSED, inject auto-repeat RELEASE key _before_ PRESSED
         switch(eventType) {
             case KeyEvent.EVENT_KEY_RELEASED:
                 if( isKeyCodeTracked(keyCode) ) {
diff --git a/src/newt/classes/jogamp/newt/driver/windows/WindowDriver.java b/src/newt/classes/jogamp/newt/driver/windows/WindowDriver.java
index ad7e1e8f3..60fc3ec0f 100644
--- a/src/newt/classes/jogamp/newt/driver/windows/WindowDriver.java
+++ b/src/newt/classes/jogamp/newt/driver/windows/WindowDriver.java
@@ -288,7 +288,7 @@ public class WindowDriver extends WindowImpl {
         // System.err.println("*** sendKeyEvent: event "+KeyEvent.getEventTypeString(eventType)+", keyCode "+toHexString(keyCode)+", keyChar <"+keyChar+">, mods "+toHexString(modifiers)+
         //                   ", isKeyCodeTracked "+isKeyCodeTracked(keyCode)+", was: pressed "+isKeyPressed(keyCode)+", repeat "+isKeyInAutoRepeat(keyCode)+", printableKey "+KeyEvent.isPrintableKey(keyCode)+" [modifierKey "+isModifierKey+"] - "+System.currentTimeMillis());
         
-        // Reorder: WINDOWS delivery order is PRESSED (t0), TYPED (t0) and RELEASED (t1) -> NEWT order: PRESSED (t0), RELEASED (t1) and TYPED (t1)
+        // Reorder: WINDOWS delivery order is PRESSED (t0), TYPED (t0) and RELEASED (t1) -> NEWT order: PRESSED (t0) and RELEASED (t1)
         // Auto-Repeat: WINDOWS delivers only PRESSED (t0) and TYPED (t0).        
         switch(eventType) {
             case KeyEvent.EVENT_KEY_RELEASED:
@@ -307,8 +307,6 @@ public class WindowDriver extends WindowImpl {
                     super.sendKeyEvent(KeyEvent.EVENT_KEY_PRESSED, modifiers, keyCode, keySym, keyChar);
                 }
                 break;
-            // case KeyEvent.EVENT_KEY_TYPED:
-            //     break;
         }
     }
     
diff --git a/src/newt/classes/jogamp/newt/driver/x11/WindowDriver.java b/src/newt/classes/jogamp/newt/driver/x11/WindowDriver.java
index 69a09c1f9..2eb07e00b 100644
--- a/src/newt/classes/jogamp/newt/driver/x11/WindowDriver.java
+++ b/src/newt/classes/jogamp/newt/driver/x11/WindowDriver.java
@@ -287,9 +287,6 @@ public class WindowDriver extends WindowImpl {
                 case KeyEvent.EVENT_KEY_RELEASED:
                     super.sendKeyEvent(KeyEvent.EVENT_KEY_RELEASED, modifiers, keyCode, keySym, keyChar);
                     break;
-                    
-                // case KeyEvent.EVENT_KEY_TYPED:
-                //    break;
             }
         }
     }
diff --git a/src/newt/classes/jogamp/newt/swt/event/SWTNewtEventFactory.java b/src/newt/classes/jogamp/newt/swt/event/SWTNewtEventFactory.java
index 1e99d1ef7..3782a1186 100644
--- a/src/newt/classes/jogamp/newt/swt/event/SWTNewtEventFactory.java
+++ b/src/newt/classes/jogamp/newt/swt/event/SWTNewtEventFactory.java
@@ -56,7 +56,6 @@ public class SWTNewtEventFactory {
 
             case SWT.KeyDown: return com.jogamp.newt.event.KeyEvent.EVENT_KEY_PRESSED;
             case SWT.KeyUp: return com.jogamp.newt.event.KeyEvent.EVENT_KEY_RELEASED;
-            // case SWT.KeyXXX: return com.jogamp.newt.event.KeyEvent.EVENT_KEY_TYPED;
         }
         return (short)0;
     }
diff --git a/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventAutoRepeatAWT.java b/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventAutoRepeatAWT.java
index f3a5c4aa9..fca1a4d93 100644
--- a/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventAutoRepeatAWT.java
+++ b/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventAutoRepeatAWT.java
@@ -68,20 +68,19 @@ import com.jogamp.opengl.test.junit.util.*;
  * <ol>
  *   <li>{@link #EVENT_KEY_PRESSED}</li>
  *   <li>{@link #EVENT_KEY_RELEASED}</li>
- *   <li>{@link #EVENT_KEY_TYPED}</li>
  * </ol>
  * </p>
  * <p>
  * Auto-Repeat shall behave as follow:
  * <pre>
-    D = pressed, U = released, T = typed
+    D = pressed, U = released
     0 = normal, 1 = auto-repeat
 
-    D(0), [ U(1), T(1), D(1), U(1) T(1) ..], U(0) T(0)
+    D(0), [ U(1), D(1), U(1), D(1) ..], U(0)
  * </pre>
  *
  * The idea is if you mask out auto-repeat in your event listener
- * you just get one long pressed key D/U/T triple.
+ * you just get one long pressed key D/U tuple.
  */
 public class TestNewtKeyEventAutoRepeatAWT extends UITestCase {
     static int width, height;
diff --git a/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventOrderAWT.java b/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventOrderAWT.java
index 68ccecf6b..3a95eacae 100644
--- a/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventOrderAWT.java
+++ b/src/test/com/jogamp/opengl/test/junit/newt/event/TestNewtKeyEventOrderAWT.java
@@ -65,7 +65,6 @@ import com.jogamp.opengl.test.junit.util.*;
  * <ol>
  *   <li>{@link #EVENT_KEY_PRESSED}</li>
  *   <li>{@link #EVENT_KEY_RELEASED}</li>
- *   <li>{@link #EVENT_KEY_TYPED}</li>
  * </ol>
  * </p>
  */