am 887568c4: am 01bf82f2: Merge "Add/refine comments to reflect key event policies" into jb-dev

* commit '887568c4f4e49b78b1549459b265377c7ee4e8c0':
  Add/refine comments to reflect key event policies

core/java/android/text/method/BaseKeyListener.java

@@ -28,6 +28,10 @@ import android.widget.TextView;
  * Provides a basic foundation for entering and editing text.
  * Subclasses should override {@link #onKeyDown} and {@link #onKeyUp} to insert
  * characters as keys are pressed.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public abstract class BaseKeyListener extends MetaKeyKeyListener
         implements KeyListener {

core/java/android/text/method/DateKeyListener.java

@@ -21,6 +21,10 @@ import android.text.InputType;
 
 /**
  * For entering dates in a text field.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class DateKeyListener extends NumberKeyListener
 {

core/java/android/text/method/DateTimeKeyListener.java

@@ -21,6 +21,10 @@ import android.view.KeyEvent;
 
 /**
  * For entering dates and times in the same text field.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class DateTimeKeyListener extends NumberKeyListener
 {

core/java/android/text/method/DialerKeyListener.java

@@ -23,6 +23,10 @@ import android.text.Spannable;
 
 /**
  * For dialing-only text entry
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class DialerKeyListener extends NumberKeyListener
 {

core/java/android/text/method/DigitsKeyListener.java

@@ -24,6 +24,10 @@ import android.view.KeyEvent;
 
 /**
  * For digits-only text entry
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class DigitsKeyListener extends NumberKeyListener
 {

core/java/android/text/method/KeyListener.java

@@ -27,6 +27,12 @@ import android.view.View;
  * {@link android.view.inputmethod.InputMethod}; it should only be used
  * for cases where an application has its own on-screen keypad and also wants
  * to process hard keyboard events to match it.
+ * <p></p>
+ * Key presses on soft input methods are not required to trigger the methods
+ * in this listener, and are in fact discouraged to do so.  The default
+ * android keyboard will not trigger these for any key to any application
+ * targetting Jelly Bean or later, and will only deliver it for some
+ * key presses to applications targetting Ice Cream Sandwich or earlier.
  */
 public interface KeyListener {
     /**

core/java/android/text/method/MultiTapKeyListener.java

@@ -28,6 +28,10 @@ import android.util.SparseArray;
  * This is the standard key listener for alphabetic input on 12-key
  * keyboards.  You should generally not need to instantiate this yourself;
  * TextKeyListener will do it for you.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class MultiTapKeyListener extends BaseKeyListener
         implements SpanWatcher {

core/java/android/text/method/NumberKeyListener.java

@@ -27,6 +27,10 @@ import android.text.Spanned;
 
 /**
  * For numeric text entry
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public abstract class NumberKeyListener extends BaseKeyListener
     implements InputFilter

core/java/android/text/method/QwertyKeyListener.java

@@ -27,6 +27,10 @@ import android.view.View;
  * This is the standard key listener for alphabetic input on qwerty
  * keyboards.  You should generally not need to instantiate this yourself;
  * TextKeyListener will do it for you.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class QwertyKeyListener extends BaseKeyListener {
     private static QwertyKeyListener[] sInstance =

core/java/android/text/method/TextKeyListener.java

@@ -33,6 +33,10 @@ import java.lang.ref.WeakReference;
 /**
  * This is the key listener for typing normal text.  It delegates to
  * other key listeners appropriate to the current keyboard and language.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class TextKeyListener extends BaseKeyListener implements SpanWatcher {
     private static TextKeyListener[] sInstance =

core/java/android/text/method/TimeKeyListener.java

@@ -21,6 +21,10 @@ import android.text.InputType;
 
 /**
  * For entering times in a text field.
+ * <p></p>
+ * As for all implementations of {@link KeyListener}, this class is only concerned
+ * with hardware keyboards.  Software input methods have no obligation to trigger
+ * the methods in this class.
  */
 public class TimeKeyListener extends NumberKeyListener
 {