diff options
Diffstat (limited to 'core/java')
15 files changed, 105 insertions, 10 deletions
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 @@ public class InputMethodService extends AbstractInputMethodService { * {@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 @@ public class InputMethodService extends AbstractInputMethodService { * {@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 @@ 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 { 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 @@ 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 { 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 @@ 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 { 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 @@ 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 { 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 @@ 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 { 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 @@ 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 { /** 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 @@ 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 { 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 @@ 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 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 @@ 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 = 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 @@ 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 = 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 @@ 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 { 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 |