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

* commit '01bf82f27297536399f7dcde214d1a082e3613ef':
  Add/refine comments to reflect key event policies

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.
      */

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
 {

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.

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>
@@ -4155,7 +4155,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) {
@@ -7542,6 +7544,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.
@@ -7573,6 +7579,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;
@@ -7583,6 +7592,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}.
@@ -7617,6 +7629,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}.
@@ -16914,14 +16929,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

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

docs/html/guide/topics/ui/index.jd

@@ -148,7 +148,7 @@ this is how you'll listen for events. The View class contains a collection of ne
 On<em>&lt;something></em>Listener, each with a callback method called <code>On<em>&lt;something></em>()</code>.
 For example, {@link android.view.View.OnClickListener} (for handling "clicks" on a View),
 {@link android.view.View.OnTouchListener} (for handling touch screen events in a View), and
-{@link android.view.View.OnKeyListener} (for handling device key presses within a View). So if you want your View
+{@link android.view.View.OnKeyListener} if you want to handle hardware key presses within a View. So if you want your View
 to be notified when it is "clicked" (such as when a button is selected), implement OnClickListener and define
 its <code>onClick()</code> callback method (where you perform the action upon click), and register it
 to the View with <code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code>.
@@ -158,7 +158,7 @@ what you should do when you've implemented your own View class and want to liste
 that occur within it. Example events you can handle include when the
 screen is touched (<code>{@link android.view.View#onTouchEvent(MotionEvent) onTouchEvent()}</code>), when
 the trackball is moved (<code>{@link android.view.View#onTrackballEvent(MotionEvent) onTrackballEvent()}</code>), 
-or when a key on the device is pressed (<code>{@link android.view.View#onKeyDown(int, KeyEvent)
+or when a <em>hardware</em> key on the device is pressed (<code>{@link android.view.View#onKeyDown(int, KeyEvent)
 onKeyDown()}</code>). This allows you to define the default behavior for each event inside your custom View and determine
 whether the event should be passed on to some other child View. Again, these are callbacks to the View class,
 so your only chance to define them is when you 

docs/html/guide/topics/ui/ui-events.jd

@@ -64,7 +64,7 @@ been registered is triggered by user interaction with the item in the UI.</p>
     This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.</dd>
   <dt><code>onKey()</code></dt>
     <dd>From {@link android.view.View.OnKeyListener}. 
-    This is called when the user is focused on the item and presses or releases a key on the device.</dd>
+    This is called when the user is focused on the item and presses or releases a hardware key on the device.</dd>
   <dt><code>onTouch()</code></dt>
     <dd>From {@link android.view.View.OnTouchListener}. 
     This is called when the user performs an action qualified as a touch event, including a press, a release,
@@ -143,13 +143,23 @@ depends on the event. For the few that do, here's why:</p>
     within the event, such as a finger gesture, or the eventual up action event.</li>
 </ul>
 
-<p>Remember that key events are always delivered to the View currently in focus. They are dispatched starting from the top
+<p>Remember that hardware key events are always delivered to the View currently in focus. They are dispatched starting from the top
 of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View)
 currently has focus, then you can see the event travel through the <code>{@link android.view.View#dispatchKeyEvent(KeyEvent)
 dispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive 
 all of the events inside your Activity with <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code>
 and <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p>
 
+<p>Also, when thinking about text input for your application, remember that many devices only have software input
+methods. Such methods are not required to be key-based; some may use voice input, handwriting, and so on. Even if
+an input method presents a keyboard-like interface, it will generally <strong>not</strong> trigger the
+<code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> family of events. You should never
+build a UI that requires specific key presses to be controlled unless you want to limit your application to devices
+with a hardware keyboard. In particular, do not rely on these methods to validate input when the user presses the
+return key; instead, use actions like {@link android.view.inputmethod.EditorInfo#IME_ACTION_DONE} to signal the
+input method how your application expects to react, so it may change its UI in a meaningful way. Avoid assumptions
+about how a software input method should work and just trust it to supply already formatted text to your application.</p>
+
 <p class="note"><strong>Note:</strong> Android will call event handlers first and then the appropriate default
 handlers from the class definition second. As such, returning <em>true</em> from these event listeners will stop
 the propagation of the event to other event listeners and will also block the callback to the