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

2 files changed, 14 insertions, 4 deletions

diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd
index 45c9ac9..be07249 100644
--- a/docs/html/guide/topics/ui/index.jd
+++ b/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 
diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd
index 93bad43..707d4b1 100644
--- a/docs/html/guide/topics/ui/ui-events.jd
+++ b/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