Widening + generics + new logging api.

git-svn-id: svn+ssh://src.earth.threerings.net/nenya/trunk@571 ed5b42cb-e716-0410-a449-f6a68f950b19

src/java/com/threerings/util/KeyTranslator.java

@@ -24,56 +24,49 @@ package com.threerings.util;
 import java.util.Iterator;
 
 /**
- * The key translator interface provides a means whereby the keyboard
+ * The key translator interface provides a means whereby the keyboard manager can map a key code to
- * manager can map a key code to the logical {@link
+ * the logical {@link com.samskivert.swing.Controller} action command that it represents.
- * com.samskivert.swing.Controller} action command that it represents.
  */
 public interface KeyTranslator
 {
     /**
-     * Returns whether there is an action command for the key
+     * Returns whether there is an action command for the key corresponding to the given keycode.
-     * corresponding to the given keycode.  The translator may have an
+     * The translator may have an action command for either a key press or a key release of the key,
-     * action command for either a key press or a key release of the key,
      * or both.
      */
     public boolean hasCommand (int keyCode);
 
     /**
-     * Returns the action command string associated with a key press of
+     * Returns the action command string associated with a key press of the key corresponding to
-     * the key corresponding to the given key code, or <code>null</code>
+     * the given key code, or <code>null</code> if there is no associated command.
-     * if there is no associated command.
      */
     public String getPressCommand (int keyCode);
 
     /**
-     * Returns the action command string associated with a key release of
+     * Returns the action command string associated with a key release of the key corresponding to
-     * the key corresponding to the given key code, or <code>null</code>
+     * the given key code, or <code>null</code> if there is no associated command.
-     * if there is no associated command.
      */
     public String getReleaseCommand (int keyCode);
 
     /**
-     * Returns the number of times each second that key presses are to be
+     * Returns the number of times each second that key presses are to be automatically repeated
-     * automatically repeated while the key is held down, or
+     * while the key is held down, or <code>0</code> to disable auto-repeat for the key.
-     * <code>0</code> to disable auto-repeat for the key.
      */
     public int getRepeatRate (int keyCode);
 
     /**
-     * Returns the delay in milliseconds before generating auto-repeated
+     * Returns the delay in milliseconds before generating auto-repeated key press events for the
-     * key press events for the specified key.
+     * specified key.
      */
     public long getRepeatDelay (int keyCode);
 
     /**
-     * Returns an iterator that iterates over the available press
+     * Returns an iterator that iterates over the available press commands.
-     * commands.
      */
-    public Iterator enumeratePressCommands ();
+    public Iterator<String> enumeratePressCommands ();
 
     /**
-     * Returns an iterator that iterates over the available release
+     * Returns an iterator that iterates over the available release commands.
-     * commands.
      */
-    public Iterator enumerateReleaseCommands ();
+    public Iterator<String> enumerateReleaseCommands ();
 }

src/java/com/threerings/util/KeyTranslatorImpl.java

@@ -69,8 +69,7 @@ public class KeyTranslatorImpl implements KeyTranslator
      * @param repeatDelay the delay in milliseconds before auto-repeating
      * key press events will be generated for the key.
      */
-    public void addPressCommand (
+    public void addPressCommand (int keyCode, String command, int rate, long repeatDelay)
-        int keyCode, String command, int rate, long repeatDelay)
     {
         KeyRecord krec = getKeyRecord(keyCode);
         krec.pressCommand = command;
@@ -80,8 +79,7 @@ public class KeyTranslatorImpl implements KeyTranslator
 
     /**
      * Adds a mapping from a key release to an action command string.
-     * Overwrites any existing mapping that may already have been
+     * Overwrites any existing mapping that may already have been registered.
-     * registered.
      */
     public void addReleaseCommand (int keyCode, String command)
     {
@@ -95,7 +93,7 @@ public class KeyTranslatorImpl implements KeyTranslator
      */
     protected KeyRecord getKeyRecord (int keyCode)
     {
-        KeyRecord krec = (KeyRecord)_keys.get(keyCode);
+        KeyRecord krec = _keys.get(keyCode);
         if (krec == null) {
             krec = new KeyRecord();
             _keys.put(keyCode, krec);
@@ -103,61 +101,59 @@ public class KeyTranslatorImpl implements KeyTranslator
         return krec;
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
     public boolean hasCommand (int keyCode)
     {
         return (_keys.get(keyCode) != null);
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
     public String getPressCommand (int keyCode)
     {
-        KeyRecord krec = (KeyRecord)_keys.get(keyCode);
+        KeyRecord krec = _keys.get(keyCode);
         return (krec == null) ? null : krec.pressCommand;
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
     public String getReleaseCommand (int keyCode)
     {
-        KeyRecord krec = (KeyRecord)_keys.get(keyCode);
+        KeyRecord krec = _keys.get(keyCode);
         return (krec == null) ? null : krec.releaseCommand;
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
     public int getRepeatRate (int keyCode)
     {
-        KeyRecord krec = (KeyRecord)_keys.get(keyCode);
+        KeyRecord krec = _keys.get(keyCode);
         return (krec == null) ? DEFAULT_REPEAT_RATE : krec.repeatRate;
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
     public long getRepeatDelay (int keyCode)
     {
-        KeyRecord krec = (KeyRecord)_keys.get(keyCode);
+        KeyRecord krec = _keys.get(keyCode);
         return (krec == null) ? DEFAULT_REPEAT_DELAY : krec.repeatDelay;
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
-    public Iterator enumeratePressCommands ()
+    public Iterator<String> enumeratePressCommands ()
     {
-        ArrayList commands = new ArrayList();
+        ArrayList<String> commands = new ArrayList<String>();
-        Iterator iter = _keys.values().iterator();
+        for (KeyRecord rec : _keys.values()) {
-        while (iter.hasNext()) {
+            commands.add(rec.pressCommand);
-            KeyRecord krec = (KeyRecord)iter.next();
-            commands.add(krec.pressCommand);
         }
+        
         return commands.iterator();
     }
 
-    // documentation inherited
+    // documentation inherited from interface KeyTranslator
-    public Iterator enumerateReleaseCommands ()
+    public Iterator<String> enumerateReleaseCommands ()
     {
-        ArrayList commands = new ArrayList();
+        ArrayList<String> commands = new ArrayList<String>();
-        Iterator iter = _keys.values().iterator();
+        for (KeyRecord rec : _keys.values()) {
-        while (iter.hasNext()) {
+            commands.add(rec.releaseCommand);
-            KeyRecord krec = (KeyRecord)iter.next();
-            commands.add(krec.releaseCommand);
         }
+        
         return commands.iterator();
     }
 
@@ -169,8 +165,7 @@ public class KeyTranslatorImpl implements KeyTranslator
         /** The command to be posted when the key is released. */
         public String releaseCommand;
 
-        /** The rate in presses per second at which the key is to be
+        /** The rate in presses per second at which the key is to be auto-repeated. */
-         * auto-repeated. */
         public int repeatRate;
 
         /** The delay in milliseconds that must expire with the key still
@@ -179,12 +174,11 @@ public class KeyTranslatorImpl implements KeyTranslator
     }
 
     /** The keys for which commands are registered. */
-    protected HashIntMap _keys = new HashIntMap();
+    protected HashIntMap<KeyRecord> _keys = new HashIntMap<KeyRecord>();
 
     /** The default key press repeat rate. */
     protected static final int DEFAULT_REPEAT_RATE = 5;
 
-    /** The default delay in milliseconds before auto-repeated key presses
+    /** The default delay in milliseconds before auto-repeated key presses will begin. */
-     * will begin. */
     protected static final long DEFAULT_REPEAT_DELAY = 500L;
 }

src/java/com/threerings/util/KeyboardManager.java

@@ -47,23 +47,20 @@ import com.threerings.util.keybd.Keyboard;
 import static com.threerings.NenyaLog.log;
 
 /**
- * The keyboard manager observes keyboard actions on a particular
+ * The keyboard manager observes keyboard actions on a particular component and posts commands
- * component and posts commands associated with the key presses to the
+ * associated with the key presses to the {@link Controller} hierarchy.  It allows specifying the
- * {@link Controller} hierarchy.  It allows specifying the key repeat
+ * key repeat rate, and will begin repeating a key immediately after it is held down rather than
- * rate, and will begin repeating a key immediately after it is held down
+ * depending on the system-specific key repeat delay/rate.
- * rather than depending on the system-specific key repeat delay/rate.
  */
 public class KeyboardManager
     implements KeyEventDispatcher, AncestorListener, WindowFocusListener
 {
     /**
-     * An interface to be implemented by those that care to be notified
+     * An interface to be implemented by those that care to be notified whenever an event (either a
-     * whenever an event (either a key press or a key release) occurs for
+     * key press or a key release) occurs for any key while the keyboard manager is active.  We use
-     * any key while the keyboard manager is active.  We use this custom
+     * this custom interface rather than the more standard {@link java.awt.event.KeyListener}
-     * interface rather than the more standard {@link
+     * interface so that we needn't create key pressed and released event objects each time a
-     * java.awt.event.KeyListener} interface so that we needn't create key
+     * (potentially artificially-generated) event occurs.
-     * pressed and released event objects each time a (potentially
-     * artificially-generated) event occurs.
      */
     public interface KeyObserver
     {
@@ -74,9 +71,9 @@ public class KeyboardManager
     }
 
     /**
-     * Constructs a keyboard manager that is initially disabled.  The
+     * Constructs a keyboard manager that is initially disabled.  The keyboard manager should not
-     * keyboard manager should not be enabled until it has been supplied
+     * be enabled until it has been supplied with a target component and translator via
-     * with a target component and translator via {@link #setTarget}.
+     * {@link #setTarget}.
      */
     public KeyboardManager ()
     {
@@ -86,9 +83,8 @@ public class KeyboardManager
     }
 
     /**
-     * Resets the keyboard manager, clearing any target and key translator
+     * Resets the keyboard manager, clearing any target and key translator in use and disabling the
-     * in use and disabling the keyboard manager if it is currently
+     * keyboard manager if it is currently active.
-     * active.
      */
     public void reset ()
     {
@@ -99,13 +95,11 @@ public class KeyboardManager
     }
 
     /**
-     * Initializes the keyboard manager with the supplied target component
+     * Initializes the keyboard manager with the supplied target component and key translator and
-     * and key translator and disables the keyboard manager if it is
+     * disables the keyboard manager if it is currently active.
-     * currently active.
      *
      * @param target the component whose keyboard events are to be observed.
-     * @param xlate the key translator used to map keyboard events to
+     * @param xlate the key translator used to map keyboard events to controller action commands.
-     * controller action commands.
      */
     public void setTarget (JComponent target, KeyTranslator xlate)
     {
@@ -117,8 +111,8 @@ public class KeyboardManager
     }
 
     /**
-     * Registers a key observer that will be notified of all key events
+     * Registers a key observer that will be notified of all key events while the keyboard manager
-     * while the keyboard manager is active.
+     * is active.
      */
     public void registerKeyObserver (KeyObserver obs)
     {
@@ -126,8 +120,8 @@ public class KeyboardManager
     }
 
     /**
-     * Removes the supplied key observer from the list of observers to be
+     * Removes the supplied key observer from the list of observers to be notified of all key
-     * notified of all key events while the keyboard manager is active.
+     * events while the keyboard manager is active.
      */
     public void removeKeyObserver (KeyObserver obs)
     {
@@ -204,9 +198,8 @@ public class KeyboardManager
     }
 
     /**
-     * Sets the expected delay in milliseconds between each key
+     * Sets the expected delay in milliseconds between each key press/release event the keyboard
-     * press/release event the keyboard manager should expect to receive
+     * manager should expect to receive while a key is repeating.
-     * while a key is repeating.
      */
     public void setRepeatDelay (long delay)
     {
@@ -214,21 +207,20 @@ public class KeyboardManager
     }
 
     /**
-     * Releases all keys and ceases any hot repeating action that may be
+     * Releases all keys and ceases any hot repeating action that may be going on.
-     * going on.
      */
     public void releaseAllKeys ()
     {
         long now = System.currentTimeMillis();
-        Iterator iter = _keys.elements();
+        Iterator<KeyInfo> iter = _keys.elements();
         while (iter.hasNext()) {
-            ((KeyInfo)iter.next()).release(now);
+            iter.next().release(now);
         }
     }
 
     /**
-     * Called when the keyboard manager gains focus and should begin
+     * Called when the keyboard manager gains focus and should begin handling keys again if it was
-     * handling keys again if it was previously enabled.
+     * previously enabled.
      */
     protected void gainedFocus ()
     {
@@ -242,8 +234,7 @@ public class KeyboardManager
     }
 
     /**
-     * Called when the keyboard manager loses focus and should cease
+     * Called when the keyboard manager loses focus and should cease handling keys.
-     * handling keys.
      */
     protected void lostFocus ()
     {
@@ -299,7 +290,7 @@ public class KeyboardManager
         boolean hasCommand = _xlate.hasCommand(keyCode);
         if (hasCommand) {
             // get the info object for this key, creating one if necessary
-            KeyInfo info = (KeyInfo)_keys.get(keyCode);
+            KeyInfo info = _keys.get(keyCode);
             if (info == null) {
                 info = new KeyInfo(keyCode);
                 _keys.put(keyCode, info);
@@ -310,8 +301,7 @@ public class KeyboardManager
         }
 
         // notify any key observers of the key press
-        notifyObservers(KeyEvent.KEY_PRESSED, e.getKeyCode(),
+        notifyObservers(KeyEvent.KEY_PRESSED, e.getKeyCode(), RunAnywhere.getWhen(e));
-                        RunAnywhere.getWhen(e));
 
         return hasCommand;
     }
@@ -327,29 +317,25 @@ public class KeyboardManager
         logKey("keyReleased", e);
 
         // get the info object for this key
-        KeyInfo info = (KeyInfo)_keys.get(e.getKeyCode());
+        KeyInfo info = _keys.get(e.getKeyCode());
         if (info != null) {
             // remember the last time we received a key release
             info.setReleaseTime(RunAnywhere.getWhen(e));
         }
 
         // notify any key observers of the key release
-        notifyObservers(KeyEvent.KEY_RELEASED, e.getKeyCode(),
+        notifyObservers(KeyEvent.KEY_RELEASED, e.getKeyCode(), RunAnywhere.getWhen(e));
-                        RunAnywhere.getWhen(e));
 
         return (info != null);
     }
 
     /**
-     * Notifies all registered key observers of the supplied key event.
+     * Notifies all registered key observers of the supplied key event. This method provides a
-     * This method provides a thread-safe manner in which to notify the
+     * thread-safe manner in which to notify the observers, which is necessary since the
-     * observers, which is necessary since the {@link KeyInfo} objects do
+     * {@link KeyInfo} objects do various antics from the interval manager thread whilst we may do
-     * various antics from the interval manager thread whilst we may do
+     * other notification from the AWT thread when normal key events are handled.
-     * other notification from the AWT thread when normal key events are
-     * handled.
      */
-    protected synchronized void notifyObservers (
+    protected synchronized void notifyObservers (int id, int keyCode, long timestamp)
-        int id, int keyCode, long timestamp)
     {
         _keyOp.init(id, keyCode, timestamp);
         _observers.apply(_keyOp);
@@ -362,7 +348,7 @@ public class KeyboardManager
     {
         if (DEBUG_EVENTS) {
             int keyCode = e.getKeyCode();
-            log.info(msg + " [key=" + KeyEvent.getKeyText(keyCode) + "].");
+            log.info(msg, "key", KeyEvent.getKeyText(keyCode));
         }
     }
 
@@ -444,7 +430,7 @@ public class KeyboardManager
                 _scheduled = true;
 
                 if (DEBUG_EVENTS) {
-                    log.info("Pressing key [key=" + _keyText + "].");
+                    log.info("Pressing key", "key", _keyText);
                 }
             }
 
@@ -480,16 +466,15 @@ public class KeyboardManager
             // infrequently.
             if (_lastPress == _lastRelease) {
                 if (DEBUG_EVENTS) {
-                    log.warning("Insta-releasing key due to equal key " +
+                    log.warning("Insta-releasing key due to equal key press/release times",
-                                "press/release times [key=" + _keyText + "].");
+                        "key", _keyText);
                 }
                 release(time);
             }
         }
 
         /**
-         * Releases the key if pressed and cancels any active key repeat
+         * Releases the key if pressed and cancels any active key repeat interval.
-         * interval.
          */
         public synchronized void release (long timestamp)
         {
@@ -499,7 +484,7 @@ public class KeyboardManager
             }
 
             if (DEBUG_EVENTS) {
-                log.info("Releasing key [key=" + _keyText + "].");
+                log.info("Releasing key", "key", _keyText);
             }
 
             // remove the repeat interval
@@ -517,7 +502,7 @@ public class KeyboardManager
             _lastPress = _lastRelease = 0;
         }
 
-        // documentation inherited
+        @Override
         public synchronized void expired ()
         {
             long now = System.currentTimeMillis();
@@ -525,9 +510,8 @@ public class KeyboardManager
             long deltaRelease = now - _lastRelease;
 
             if (KeyboardManager.DEBUG_INTERVAL) {
-                log.info("Interval [key=" + _keyText +
+                log.info("Interval",
-                         ", deltaPress=" + deltaPress +
+                    "key", _keyText, "deltaPress", deltaPress, "deltaRelease", deltaRelease);
-                         ", deltaRelease=" + deltaRelease + "].");
             }
 
             // handle a normal interval where we either (a) create a
@@ -543,8 +527,7 @@ public class KeyboardManager
 //                         _siid = IntervalManager.register(
 //                             this, delay, Long.valueOf(_lastPress), false);
 //                         if (KeyboardManager.DEBUG_INTERVAL) {
-//                             log.info("Registered sub-interval " +
+//                             log.info("Registered sub-interval", "id", _siid);
-//                                      "[id=" + _siid + "].");
 //                         }
 
 //                     } else {
@@ -595,8 +578,7 @@ public class KeyboardManager
         **/
 
         /**
-         * Posts the press command for this key and notifies all key
+         * Posts the press command for this key and notifies all key observers of the key press.
-         * observers of the key press.
          */
         protected void postPress (long timestamp)
         {
@@ -605,8 +587,7 @@ public class KeyboardManager
         }
 
         /**
-         * Posts the release command for this key and notifies all key
+         * Posts the release command for this key and notifies all key observers of the key release.
-         * observers of the key release.
          */
         protected void postRelease (long timestamp)
         {
@@ -614,7 +595,7 @@ public class KeyboardManager
             Controller.postAction(_target, _releaseCommand);
         }
 
-        /** Returns a string representation of the key info object. */
+        @Override
         public String toString ()
         {
             return "[key=" + _keyText + "]";
@@ -649,7 +630,7 @@ public class KeyboardManager
     }
 
     /** An observer operation to notify observers of a key event. */
-    protected static class KeyObserverOp implements ObserverList.ObserverOp
+    protected static class KeyObserverOp implements ObserverList.ObserverOp<KeyObserver>
     {
         /** Initialized the operation with its parameters. */
         public void init (int id, int keyCode, long timestamp)
@@ -660,9 +641,9 @@ public class KeyboardManager
         }
 
         // documentation inherited from interface ObserverList.ObserverOp
-        public boolean apply (Object observer)
+        public boolean apply (KeyObserver observer)
         {
-            ((KeyObserver)observer).handleKeyEvent(_id, _keyCode, _timestamp);
+            observer.handleKeyEvent(_id, _keyCode, _timestamp);
             return true;
         }
 
@@ -690,7 +671,7 @@ public class KeyboardManager
     protected long _repeatDelay = DEFAULT_REPEAT_DELAY;
 
     /** A hashtable mapping key codes to {@link KeyInfo} objects. */
-    protected HashIntMap _keys = new HashIntMap();
+    protected HashIntMap<KeyInfo> _keys = new HashIntMap<KeyInfo>();
 
     /** Whether the keyboard manager currently has the keyboard focus. */
     protected boolean _focus;
@@ -710,13 +691,11 @@ public class KeyboardManager
     protected KeyTranslator _xlate;
 
     /** The list of key observers. */
-    protected ObserverList _observers =
+    protected ObserverList _observers = new ObserverList(ObserverList.FAST_UNSAFE_NOTIFY);
-        new ObserverList(ObserverList.FAST_UNSAFE_NOTIFY);
 
     /** The operation used to notify observers of actual key events. */
     protected KeyObserverOp _keyOp = new KeyObserverOp();
 
-    /** Whether native key auto-repeating was enabled when the keyboard
+    /** Whether native key auto-repeating was enabled when the keyboard manager was last enabled. */
-     * manager was last enabled. */
     protected boolean _nativeRepeat;
 }