Add/refine comments to reflect key event policies
Make clearer how the platform is handling key events following some
unfortunate uses by third party applications. Also highlight the
changes in Jelly Bean default keyboard.
Bug: 6566711
Change-Id: Ibcdaf54c6d629fd0733529bfe2fffc82f555f084
diff --git a/core/java/android/inputmethodservice/InputMethodService.java b/core/java/android/inputmethodservice/InputMethodService.java
index 33dea6c..46153e7 100644
--- a/core/java/android/inputmethodservice/InputMethodService.java
+++ b/core/java/android/inputmethodservice/InputMethodService.java
@@ -1892,6 +1892,13 @@
* {@link KeyEvent#FLAG_KEEP_TOUCH_MODE KeyEvent.FLAG_KEEP_TOUCH_MODE}, so
* that they don't impact the current touch mode of the UI.
*
+ * <p>Note that it's discouraged to send such key events in normal operation;
+ * this is mainly for use with {@link android.text.InputType#TYPE_NULL} type
+ * text fields, or for non-rich input methods. A reasonably capable software
+ * input method should use the
+ * {@link android.view.inputmethod.InputConnection#commitText} family of methods
+ * to send text to an application, rather than sending key events.</p>
+ *
* @param keyEventCode The raw key code to send, as defined by
* {@link KeyEvent}.
*/
@@ -1949,7 +1956,11 @@
* {@link InputConnection#commitText InputConnection.commitText()} with
* the character; some, however, may be handled different. In particular,
* the enter character ('\n') will either be delivered as an action code
- * or a raw key event, as appropriate.
+ * or a raw key event, as appropriate. Consider this as a convenience
+ * method for IMEs that do not have a full implementation of actions; a
+ * fully complying IME will decide of the right action for each event and
+ * will likely never call this method except maybe to handle events coming
+ * from an actual hardware keyboard.
*
* @param charCode The UTF-16 character code to send.
*/
diff --git a/core/java/android/text/method/BaseKeyListener.java b/core/java/android/text/method/BaseKeyListener.java
index 7e29dc7..4fede32 100644
--- a/core/java/android/text/method/BaseKeyListener.java
+++ b/core/java/android/text/method/BaseKeyListener.java
@@ -28,6 +28,10 @@
* 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 {
diff --git a/core/java/android/text/method/DateKeyListener.java b/core/java/android/text/method/DateKeyListener.java
index 7c11434..e6f63d1 100644
--- a/core/java/android/text/method/DateKeyListener.java
+++ b/core/java/android/text/method/DateKeyListener.java
@@ -21,6 +21,10 @@
/**
* 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
{
diff --git a/core/java/android/text/method/DateTimeKeyListener.java b/core/java/android/text/method/DateTimeKeyListener.java
index f8ebc40..523e986 100644
--- a/core/java/android/text/method/DateTimeKeyListener.java
+++ b/core/java/android/text/method/DateTimeKeyListener.java
@@ -21,6 +21,10 @@
/**
* 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
{
diff --git a/core/java/android/text/method/DialerKeyListener.java b/core/java/android/text/method/DialerKeyListener.java
index 07127b7..ce51fae 100644
--- a/core/java/android/text/method/DialerKeyListener.java
+++ b/core/java/android/text/method/DialerKeyListener.java
@@ -23,6 +23,10 @@
/**
* 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
{
diff --git a/core/java/android/text/method/DigitsKeyListener.java b/core/java/android/text/method/DigitsKeyListener.java
index f0f072c..3d9daed 100644
--- a/core/java/android/text/method/DigitsKeyListener.java
+++ b/core/java/android/text/method/DigitsKeyListener.java
@@ -24,6 +24,10 @@
/**
* 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
{
diff --git a/core/java/android/text/method/KeyListener.java b/core/java/android/text/method/KeyListener.java
index 318149a..bb79ecd 100644
--- a/core/java/android/text/method/KeyListener.java
+++ b/core/java/android/text/method/KeyListener.java
@@ -27,6 +27,12 @@
* {@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 {
/**
diff --git a/core/java/android/text/method/MultiTapKeyListener.java b/core/java/android/text/method/MultiTapKeyListener.java
index 2a739fa..95ac0a1 100644
--- a/core/java/android/text/method/MultiTapKeyListener.java
+++ b/core/java/android/text/method/MultiTapKeyListener.java
@@ -28,6 +28,10 @@
* 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 {
diff --git a/core/java/android/text/method/NumberKeyListener.java b/core/java/android/text/method/NumberKeyListener.java
index 1e72309..5d4c732 100644
--- a/core/java/android/text/method/NumberKeyListener.java
+++ b/core/java/android/text/method/NumberKeyListener.java
@@ -27,6 +27,10 @@
/**
* 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
diff --git a/core/java/android/text/method/QwertyKeyListener.java b/core/java/android/text/method/QwertyKeyListener.java
index 4c82b81..c5261f3 100644
--- a/core/java/android/text/method/QwertyKeyListener.java
+++ b/core/java/android/text/method/QwertyKeyListener.java
@@ -27,6 +27,10 @@
* 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 =
diff --git a/core/java/android/text/method/TextKeyListener.java b/core/java/android/text/method/TextKeyListener.java
index 8312fe1..994f3d7 100644
--- a/core/java/android/text/method/TextKeyListener.java
+++ b/core/java/android/text/method/TextKeyListener.java
@@ -33,6 +33,10 @@
/**
* 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 =
diff --git a/core/java/android/text/method/TimeKeyListener.java b/core/java/android/text/method/TimeKeyListener.java
index 3fbfd8c..c5bfd5c 100644
--- a/core/java/android/text/method/TimeKeyListener.java
+++ b/core/java/android/text/method/TimeKeyListener.java
@@ -21,6 +21,10 @@
/**
* 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
{
diff --git a/core/java/android/view/KeyEvent.java b/core/java/android/view/KeyEvent.java
index ace7aa8..1080229 100755
--- a/core/java/android/view/KeyEvent.java
+++ b/core/java/android/view/KeyEvent.java
@@ -52,6 +52,19 @@
* to characters. Be aware that there may be multiple key input devices active
* at the same time and each will have its own key character map.
* </p><p>
+ * As soft input methods can use multiple and inventive ways of inputting text,
+ * there is no guarantee that any key press on a soft keyboard will generate a key
+ * event: this is left to the IME's discretion, and in fact sending such events is
+ * discouraged. You should never rely on receiving KeyEvents for any key on a soft
+ * input method. In particular, the default software keyboard will never send any
+ * key event to any application targetting Jelly Bean or later, and will only send
+ * events for some presses of the delete and return keys to applications targetting
+ * Ice Cream Sandwich or earlier. Be aware that other software input methods may
+ * never send key events regardless of the version. Consider using editor actions
+ * like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} if you need
+ * specific interaction with the software keyboard, as it gives more visibility to
+ * the user as to how your application will react to key presses.
+ * </p><p>
* When interacting with an IME, the framework may deliver key events
* with the special action {@link #ACTION_MULTIPLE} that either specifies
* that single repeated key code or a sequence of characters to insert.
diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java
index 8cb5c85..35b6aa6 100644
--- a/core/java/android/view/View.java
+++ b/core/java/android/view/View.java
@@ -204,12 +204,12 @@
* <tr>
* <td rowspan="4">Event processing</td>
* <td><code>{@link #onKeyDown(int, KeyEvent)}</code></td>
- * <td>Called when a new key event occurs.
+ * <td>Called when a new hardware key event occurs.
* </td>
* </tr>
* <tr>
* <td><code>{@link #onKeyUp(int, KeyEvent)}</code></td>
- * <td>Called when a key up event occurs.
+ * <td>Called when a hardware key up event occurs.
* </td>
* </tr>
* <tr>
@@ -4082,7 +4082,9 @@
}
/**
- * Register a callback to be invoked when a key is pressed in this view.
+ * Register a callback to be invoked when a hardware key is pressed in this view.
+ * Key presses in software input methods will generally not trigger the methods of
+ * this listener.
* @param l the key listener to attach to this view
*/
public void setOnKeyListener(OnKeyListener l) {
@@ -7389,6 +7391,10 @@
* when {@link KeyEvent#KEYCODE_DPAD_CENTER} or {@link KeyEvent#KEYCODE_ENTER}
* is released, if the view is enabled and clickable.
*
+ * <p>Key presses in software keyboards will generally NOT trigger this listener,
+ * although some may elect to do so in some situations. Do not rely on this to
+ * catch software key presses.
+ *
* @param keyCode A key code that represents the button pressed, from
* {@link android.view.KeyEvent}.
* @param event The KeyEvent object that defines the button action.
@@ -7420,6 +7426,9 @@
* Default implementation of {@link KeyEvent.Callback#onKeyLongPress(int, KeyEvent)
* KeyEvent.Callback.onKeyLongPress()}: always returns false (doesn't handle
* the event).
+ * <p>Key presses in software keyboards will generally NOT trigger this listener,
+ * although some may elect to do so in some situations. Do not rely on this to
+ * catch software key presses.
*/
public boolean onKeyLongPress(int keyCode, KeyEvent event) {
return false;
@@ -7430,6 +7439,9 @@
* KeyEvent.Callback.onKeyUp()}: perform clicking of the view
* when {@link KeyEvent#KEYCODE_DPAD_CENTER} or
* {@link KeyEvent#KEYCODE_ENTER} is released.
+ * <p>Key presses in software keyboards will generally NOT trigger this listener,
+ * although some may elect to do so in some situations. Do not rely on this to
+ * catch software key presses.
*
* @param keyCode A key code that represents the button pressed, from
* {@link android.view.KeyEvent}.
@@ -7464,6 +7476,9 @@
* Default implementation of {@link KeyEvent.Callback#onKeyMultiple(int, int, KeyEvent)
* KeyEvent.Callback.onKeyMultiple()}: always returns false (doesn't handle
* the event).
+ * <p>Key presses in software keyboards will generally NOT trigger this listener,
+ * although some may elect to do so in some situations. Do not rely on this to
+ * catch software key presses.
*
* @param keyCode A key code that represents the button pressed, from
* {@link android.view.KeyEvent}.
@@ -16760,14 +16775,20 @@
}
/**
- * Interface definition for a callback to be invoked when a key event is
- * dispatched to this view. The callback will be invoked before the key
- * event is given to the view.
+ * Interface definition for a callback to be invoked when a hardware key event is
+ * dispatched to this view. The callback will be invoked before the key event is
+ * given to the view. This is only useful for hardware keyboards; a software input
+ * method has no obligation to trigger this listener.
*/
public interface OnKeyListener {
/**
- * Called when a key is dispatched to a view. This allows listeners to
+ * Called when a hardware key is dispatched to a view. This allows listeners to
* get a chance to respond before the target view.
+ * <p>Key presses in software keyboards will generally NOT trigger this method,
+ * although some may elect to do so in some situations. Do not assume a
+ * software input method has to be key-based; even if it is, it may use key presses
+ * in a different way than you expect, so there is no way to reliably catch soft
+ * input key presses.
*
* @param v The view the key has been dispatched to.
* @param keyCode The code for the physical key that was pressed
diff --git a/core/java/android/view/inputmethod/InputConnection.java b/core/java/android/view/inputmethod/InputConnection.java
index 3563d4d..76c6d19 100644
--- a/core/java/android/view/inputmethod/InputConnection.java
+++ b/core/java/android/view/inputmethod/InputConnection.java
@@ -283,7 +283,7 @@
/**
* Tell the editor that you are done with a batch edit previously
- * initiated with {@link #endBatchEdit}.
+ * initiated with {@link #beginBatchEdit}.
*/
public boolean endBatchEdit();
@@ -307,7 +307,11 @@
* {@link KeyEvent#FLAG_SOFT_KEYBOARD KeyEvent.FLAG_SOFT_KEYBOARD} on all
* key event objects you give to this API; the flag will not be set
* for you.
- *
+ *
+ * <p>Note that it's discouraged to send such key events in normal operation;
+ * this is mainly for use with {@link android.text.InputType#TYPE_NULL} type
+ * text fields. Use the {@link #commitText} family of methods to send text
+ * to the application instead.
* @param event The key event.
*
* @return Returns true on success, false if the input connection is no longer