diff options
Diffstat (limited to 'core/java/android/view')
| -rwxr-xr-x | core/java/android/view/KeyEvent.java | 13 | ||||
| -rw-r--r-- | core/java/android/view/View.java | 35 | ||||
| -rw-r--r-- | core/java/android/view/inputmethod/InputConnection.java | 8 |
3 files changed, 47 insertions, 9 deletions
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 @@ import android.view.KeyCharacterMap.KeyData; * 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 @@ import java.util.concurrent.CopyOnWriteArrayList; * <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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal } /** - * 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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * 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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * 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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * 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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal * 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 @@ public class View implements Drawable.Callback, Drawable.Callback2, KeyEvent.Cal } /** - * 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 @@ public interface InputConnection { /** * 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 @@ public interface InputConnection { * {@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 |