docs: add class on keyboards

Change-Id: I3fb179457af50eec9d111f84eb9fabf49bc7ab1b

10 files changed, 718 insertions, 14 deletions

diff --git a/docs/html/guide/topics/ui/controls/text.jd b/docs/html/guide/topics/ui/controls/text.jd
index 2d9d215..654883d 100644
--- a/docs/html/guide/topics/ui/controls/text.jd
+++ b/docs/html/guide/topics/ui/controls/text.jd
@@ -79,15 +79,23 @@ should use the {@code textEmailAddress} input type:</p>
 </pre>
 
 
-<p>There are several different input types available for different situations. You can find
-them all listed with the documentation for <a
-href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code
-android:inputType}</a>.</p>
-
-<p class="note"><strong>Tip:</strong> To allow users to input long strings of text with line
-breaks, use the {@code "textMultiLine"} input type. By default, an {@link android.widget.EditText}
-object is restricted to one line of text and scrolls horizontally when the text exceeds the
-available width.</p>
+<p>There are several different input types available for different situations.
+Here are some of the more common values for
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a>:</p>
+
+<dl>
+  <dt>{@code "text"}</dt>
+    <dd>Normal text keyboard.</dd>
+  <dt>{@code "textEmailAddress"}</dt>
+    <dd>Normal text keyboard with the @ character.</dd>
+  <dt>{@code "textUri"}</dt>
+    <dd>Normal text keyboard with the / character.</dd>
+  <dt>{@code "number"}</dt>
+    <dd>Basic number keypad.</dd>
+  <dt>{@code "phone"}</dt>
+    <dd>Phone-style keypad.</dd>
+</dl>
 
 
 <h3 id="Behaviors">Controlling other behaviors</h3>
@@ -98,7 +106,25 @@ capitalize all new words or use features like auto-complete and spelling suggest
 
 <p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code
 android:inputType}</a> attribute allows bitwise combinations so you can specify both a keyboard
-layout and one or more behaviors at once. For example, here's how you can collect a postal
+layout and one or more behaviors at once.</p>
+
+<p>Here are some of the common input type values that define keyboard behaviors:</p>
+
+<dl>
+  <dt>{@code "textCapSentences"}</dt>
+    <dd>Normal text keyboard that capitalizes the first letter for each new sentence.</dd>
+  <dt>{@code "textCapWords"}</dt>
+    <dd>Normal text keyboard that capitalizes every word. Good for titles or person names.</dd>
+  <dt>{@code "textAutoCorrect"}</dt>
+    <dd>Normal text keyboard that corrects commonly misspelled words.</dd>
+  <dt>{@code "textPassword"}</dt>
+    <dd>Normal text keyboard, but the characters entered turn into dots.</dd>
+  <dt>{@code "textMultiLine"}</dt>
+    <dd>Normal text keyboard that allow users to input long strings of text that include line
+breaks (carriage returns).</dd>
+</dl>
+
+<p>For example, here's how you can collect a postal
 address, capitalize each word, and disable text suggestions:</p>
 
 <pre>
@@ -177,7 +203,7 @@ editText.setOnEditorActionListener(new OnEditorActionListener() {
     public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
         boolean handled = false;
         if (actionId == EditorInfo.IME_ACTION_SEND) {
-            // Send the user message
+            sendMessage();
             handled = true;
         }
         return handled;
diff --git a/docs/html/images/training/input/ime_autocorrect.png b/docs/html/images/training/input/ime_autocorrect.png
new file mode 100644
index 0000000..fd8371b
--- /dev/null
+++ b/docs/html/images/training/input/ime_autocorrect.png
diff --git a/docs/html/images/training/input/ime_password.png b/docs/html/images/training/input/ime_password.png
new file mode 100644
index 0000000..6270c30
--- /dev/null
+++ b/docs/html/images/training/input/ime_password.png
diff --git a/docs/html/training/best-user-input.jd b/docs/html/training/best-user-input.jd
new file mode 100644
index 0000000..7f5ed15
--- /dev/null
+++ b/docs/html/training/best-user-input.jd
@@ -0,0 +1,9 @@
+page.title=Best Practices for User Input
+page.trainingcourse=true
+
+@jd:body
+
+
+
+<p>These classes cover various subjects of user input, such as
+touch screen gestures and text input through on-screen input methods and hardware keyboards.</p>
\ No newline at end of file
diff --git a/docs/html/training/keyboard-input/commands.jd b/docs/html/training/keyboard-input/commands.jd
new file mode 100644
index 0000000..9d2de41
--- /dev/null
+++ b/docs/html/training/keyboard-input/commands.jd
@@ -0,0 +1,113 @@
+page.title=Handling Keyboard Actions
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#SingleKey">Handle Single Key Events</a></li>
+  <li><a href="#ModifierKey">Handle Modifier Keys</a></li>
+</ol>
+
+</div>
+</div>
+
+
+<p>When the user gives focus to an editable text view such as an {@link android.widget.EditText}
+element and the user has a hardware keyboard attached, all
+input is handled by the system. If, however, you'd like to intercept
+or directly handle the keyboard input yourself, you can do so by implementing callback methods
+from the {@link android.view.KeyEvent.Callback} interface, such as {@link
+android.view.KeyEvent.Callback#onKeyDown onKeyDown()} and {@link
+android.view.KeyEvent.Callback#onKeyMultiple onKeyMultiple()}.</p>
+
+<p>Both the {@link
+android.app.Activity} and {@link android.view.View} class implement the
+{@link android.view.KeyEvent.Callback} interface, so you
+should generally override the callback methods in your extension of these classes as
+appropriate.</p>
+
+<p class="note"><strong>Note:</strong> When handling keyboard events with the {@link
+android.view.KeyEvent} class and related APIs, you should expect that such keyboard
+events come only from a hardware keyboard. You should never rely on receiving key events
+for any key on a soft input method (an on-screen keyboard).</p>
+
+
+<h2 id="SingleKey">Handle Single Key Events</h2>
+
+<p>To handle an individual key press, implement {@link
+android.app.Activity#onKeyDown onKeyDown()} or {@link
+android.app.Activity#onKeyUp onKeyUp()} as appropriate. Usually, you should
+use {@link android.app.Activity#onKeyUp onKeyUp()} if you want to be sure that you receive
+only one event. If the user presses and holds the button, then {@link
+android.app.Activity#onKeyDown onKeyDown()} is called multiple times.</p>
+
+<p>For example, this implementation responds to some keyboard keys to control a game:</p>
+
+<pre>
+&#64;Override
+public boolean onKeyUp(int keyCode, KeyEvent event) {
+    switch (keyCode) {
+        case KeyEvent.KEYCODE_D:
+            moveShip(MOVE_LEFT);
+            return true;
+        case KeyEvent.KEYCODE_F:
+            moveShip(MOVE_RIGHT);
+            return true;
+        case KeyEvent.KEYCODE_J:
+            fireMachineGun();
+            return true;
+        case KeyEvent.KEYCODE_K:
+            fireMissile();
+            return true;
+        default:
+            return super.onKeyUp(keyCode, event);
+    }
+}
+</pre>
+
+
+<h2 id="ModifierKey">Handle Modifier Keys</h2>
+
+<p>To respond to modifier key events such as when a key is combined with Shift or Control, you can
+query the {@link android.view.KeyEvent} that's passed to the callback method. Several methods
+provide information about modifier keys such as {@link android.view.KeyEvent#getModifiers()}
+and {@link android.view.KeyEvent#getMetaState()}. However, the simplest solution is to check whether
+the exact modifier key you care about is being pressed with methods such as
+{@link android.view.KeyEvent#isShiftPressed()} and {@link android.view.KeyEvent#isCtrlPressed()}.
+</p>
+
+<p>For example, here's the {@link android.app.Activity#onKeyDown onKeyDown()} implementation
+again, with some extra handling for when the Shift key is held down with one of the keys:</p>
+
+<pre>
+&#64;Override
+public boolean onKeyUp(int keyCode, KeyEvent event) {
+    switch (keyCode) {
+        ...
+        case KeyEvent.KEYCODE_J:
+            if (event.isShiftPressed()) {
+                fireLaser();
+            } else {
+                fireMachineGun();
+            }
+            return true;
+        case KeyEvent.KEYCODE_K:
+            if (event.isShiftPressed()) {
+                fireSeekingMissle();
+            } else {
+                fireMissile();
+            }
+            return true;
+        default:
+            return super.onKeyUp(keyCode, event);
+    }
+}
+</pre>
+
+
+
diff --git a/docs/html/training/keyboard-input/index.jd b/docs/html/training/keyboard-input/index.jd
new file mode 100644
index 0000000..ba4e598
--- /dev/null
+++ b/docs/html/training/keyboard-input/index.jd
@@ -0,0 +1,54 @@
+page.title=Handling Keyboard Input
+
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+<ul>
+  <li>Android 1.6 (API Level 3) or higher</li>
+</ul>
+
+</div>
+</div>
+
+<p>The Android system shows an on-screen keyboard&mdash;known as a
+<em>soft input method</em>&mdash;when a text field in your UI receives focus.
+To provide the best user experience, you can specify characteristics
+about the type of input you expect (such as
+whether it's a phone number or email address) and how the input method should behave (such as
+whether it performs auto-correct for spelling mistakes).</p>
+
+<p>In addition to the on-screen input methods, Android also supports hardware keyboards, so it's
+important that your app optimize its user experience for interaction that might occur
+through an attached keyboard.</p>
+
+<p>These topics and more are discussed in the following lessons.</p>
+
+
+<h2>Lessons</h2> 
+ 
+<dl> 
+  <dt><b><a href="style.html">Specifying the Input Method Type</a></b></dt>
+    <dd>Learn how to show certain soft input methods, such as those designed for phone numbers, web
+    addresses, or other formats. Also learn how to specify characteristics such
+    as spelling suggestion behavior and action buttons such as <b>Done</b> or <b>Next</b>.
+    </dd>
+  <dt><b><a href="visibility.html">Handling Input Method Visibility</a></b></dt>
+    <dd>Learn how to specify when to show the soft input method and how
+    your layout should adjust to the reduced screen space.
+    </dd>
+  <dt><b><a href="navigation.html">Supporting Keyboard Navigation</a></b></dt>
+    <dd>Learn how to verify that users can navigate your app using a keyboard
+    and how to make any necessary changes to the navigation order.
+    </dd>
+  <dt><b><a href="commands.html">Handling Keyboard Actions</a></b></dt>
+    <dd>Learn how to respond directly to keyboard input for user actions.
+    </dd>
+ 
+</dl> 
\ No newline at end of file
diff --git a/docs/html/training/keyboard-input/navigation.jd b/docs/html/training/keyboard-input/navigation.jd
new file mode 100644
index 0000000..6e26ab2
--- /dev/null
+++ b/docs/html/training/keyboard-input/navigation.jd
@@ -0,0 +1,166 @@
+page.title=Supporting Keyboard Navigation
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
  <li><a href="#Test">Test Your App</a></li>
  <li><a href="#Tab">Handle Tab Navigation</a></li>
  <li><a href="#Direction">Handle Directional Navigation</a></li>
</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li>
+</ul>
+
+</div>
+</div>
+
+<p>In addition to soft input methods (such as on-screen keyboards), Android supports
+physical keyboards attached to the device. A keyboard offers not only a convenient
+mode for text input, but also offers a way for users to navigate and
+interact with your app. Although most hand-held devices such as phones use touch as the
+primary mode of interaction,
+tablets and similar devices are growing in popularity and many users like to attach
+keyboard accessories.</p>
+
+<p>As more Android devices offer this kind of experience, it's important that
+you optimize your app to support interaction through a keyboard. This lesson describes
+how you can better support navigation with a keyboard.</p>
+
+<p class="note"><strong>Note:</strong>
+Supporting of directional navigation in your application is also important in ensuring that
+your application is <a href="{@docRoot}guide/topics/ui/accessibility/apps.html">accessible</a>
+to users who do not navigate using visual cues. Fully supporting directional navigation in your
+application can also help you automate <a href="{@docRoot}tools/testing/testing_ui.html">user
+interface testing</a> with tools like <a
+href="{@docRoot}tools/help/uiautomator/index.html">uiautomator</a>.</p>
+
+
+
+<h2 id="Test">Test Your App</h2>
+
+<p>It's possible that users can already navigate your app using a keyboard, because the
+Android system enables most of the necessary behaviors by default.</p>
+
+<p>All interactive widgets provided by the Android framework (such as {@link android.widget.Button}
+and {@link android.widget.EditText}) are focusable. This means users can navigate with
+control devices such as a D-pad or keyboard and each widget glows or otherwise changes its
+appearance when it gains input focus.</p>
+
+<p>To test your app:</p>
+<ol>
+  <li>Install your app on a device that offers a hardware keyboard.
+    <p>If you don't have a hardware device with a keyboard, connect a Bluetooth keyboard
+    or a USB keyboard (though not all devices support USB accessories).</p>
+    <p>You can also use the Android emulator:</p>
+    <ol>
+      <li>In the AVD Manager, either click <strong>New Device</strong> or
+      select an existing profile and click <strong>Clone</strong>.</li>
+      <li>In the window that appears, ensure that <strong>Keyboard</strong> and
+      <strong>DPad</strong> are enabled.</li>
+    </ol>
+  </li>
+  <li>To test your app, use only the Tab key to navigate through your UI, ensuring that
+    each UI control gets focus as expected.
+    <p>Look for any instances in which the focus moves in a way you don't expect.</p>
+  </li>
+  <li>Start from the beginning of your app and instead use the direction controls
+  (arrow keys on the keyboard) to navigate your app.
+    <p>From each focusable element in your UI, press Up, Down, Left, and Right.</p>
+    <p>Look for any instances in which the focus moves in a way you don't expect.</p>
+  </li>
+</ol>
+
+<p>If you encounter any instances where navigating with the Tab key or direction controls
+does not do what you expect, specify where the focus should go in your layout, as discussed
+in the following sections.</p>
+
+
+
+<h2 id="Tab">Handle Tab Navigation</h2>
+
+<p>When a user navigates your app using the keyboard Tab key,
+the system passes input focus between elements based
+on the order in which they appear in the layout. If you use a relative layout, for example,
+and the order of elements on the screen is different than the order in the file, then you might need
+to manually specify the focus order.</p>
+
+<p>For example, in the following layout, two buttons are aligned to the right side and a text field
+is aligned to the left of the second button. In order to pass focus from the first button to the
+text field, then to the second button, the layout needs to explicitly define the focus order
+for each of the focusable elements with the <a
+href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusForward">{@code
+android:nextFocusForward}</a> attribute:</p>
+
+<pre>
+&lt;RelativeLayout ...>
+    &lt;Button
+        android:id="@+id/button1"
+        android:layout_alignParentTop="true"
+        android:layout_alignParentRight="true"
+        android:nextFocusForward="@+id/editText1"
+        ... />
+    &lt;Button
+        android:id="@+id/button2"
+        android:layout_below="@id/button1"
+        android:nextFocusForward="@+id/button1"
+        ... />
+    &lt;EditText
+        android:id="@id/editText1"
+        android:layout_alignBottom="@+id/button2"
+        android:layout_toLeftOf="@id/button2"
+        android:nextFocusForward="@+id/button2"
+        ...  />
+    ...
+&lt;/RelativeLayout>
+</pre>
+
+<p>Now instead of sending focus from {@code button1} to {@code button2} then {@code editText1}, the
+focus appropriately moves according to the appearance on the screen: from
+{@code button1} to {@code editText1} then {@code button2}.</p>
+
+
+<h2 id="Direction">Handle Directional Navigation</h2>
+
+<p>Users can also navigate your app using the arrow keys on a
+keyboard (the behavior is the same as when navigating with a D-pad or trackball).
+The system provides a best-guess as to which view should be given focus
+in a given direction based on the layout of the views on screen. Sometimes, however, the system
+might guess wrong.</p>
+
+<p>If the system does not pass focus to the appropriate view when navigating in a given direction,
+specify which view should receive focus with the following attributes:</p>
+<ul>
+  <li><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp">{@code
+android:nextFocusUp}</a></li>
+  <li><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown">{@code
+android:nextFocusDown}</a></li>
+  <li><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft">{@code
+android:nextFocusLeft}</a></li>
+  <li><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight">{@code
+android:nextFocusRight}</a></li>
+</ul>
+
+<p>Each attribute designates the next view to receive focus when the user navigates
+in that direction, as specified by the view ID. For example:</p>
+
+<pre>
+&lt;Button
+    android:id="@+id/button1"
+    android:nextFocusRight="@+id/button2"
+    android:nextFocusDown="@+id/editText1"
+    ... />
+&lt;Button
+    android:id="@id/button2"
+    android:nextFocusLeft="@id/button1"
+    android:nextFocusDown="@id/editText1"
+    ... />
+&lt;EditText
+    android:id="@id/editText1"
+    android:nextFocusUp="@id/button1"
+    ...  />
+</pre>
+
diff --git a/docs/html/training/keyboard-input/style.jd b/docs/html/training/keyboard-input/style.jd
new file mode 100644
index 0000000..b0e506c
--- /dev/null
+++ b/docs/html/training/keyboard-input/style.jd
@@ -0,0 +1,171 @@
+page.title=Specifying the Input Method Type
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+  <li><a href="#Type">Specify the Keyboard Type</a></li>
+  <li><a href="#Spelling">Enable Spelling Suggestions and Other Behaviors</a></li>
+  <li><a href="#Action">Specify the Input Method Action</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+  <li><a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a></li>
+</ul>
+
+</div>
+</div>
+
+
+<p>Every text field expects a certain type of text input, such as an
+email address, phone number, or just plain text. So it's important
+that you specify the input type for each text field in your app
+so the system displays the appropriate soft input method (such as an on-screen keyboard).</p>
+
+<p>Beyond the type of buttons available with an input method, you should specify
+behaviors such as whether the input method provides spelling suggestions,
+capitalizes new sentences, and replaces the carriage return button with an
+action button such as a <b>Done</b> or <b>Next</b>.
+This lesson shows how to specify these characteristics.</p>
+
+
+
+<h2 id="Type">Specify the Keyboard Type</h2>
+
+<p>You should always declare the input method for your text fields by adding
+the <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute to the {@link android.widget.EditText
+&lt;EditText&gt;} element.</p>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/ui/edittext-phone.png" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> The {@code phone} input type.</p>
+</div>
+
+<p>For example, if you'd like an input method for entering a phone number,
+use the {@code "phone"} value:</p>
+<pre>
+&lt;EditText
+    android:id="@+id/phone"
+    android:layout_width="fill_parent"
+    android:layout_height="wrap_content"
+    android:hint="@string/phone_hint"
+    android:inputType="phone" />
+</pre>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/training/input/ime_password.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> The {@code textPassword} input type.</p>
+</div>
+
+<p>Or if the text field is for a password, use the {@code "textPassword"} value
+so the text field conceals the user's input:</p>
+<pre>
+&lt;EditText
+    android:id="@+id/password"
+    android:hint="@string/password_hint"
+    android:inputType="textPassword"
+    ... />    
+</pre>
+
+<p>There are several possible values documented with the
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute and
+some of the values can be combined to specify the input method
+appearance and additional behaviors.</p>
+
+
+
+<h2 id="Spelling">Enable Spelling Suggestions and Other Behaviors</h2>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/training/input/ime_autocorrect.png" alt="" />
+<p class="img-caption"><strong>Figure 3.</strong> Adding {@code textAutoCorrect}
+provides auto-correction for misspellings.</p>
+</div>
+
+<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute allows you to specify various behaviors for the
+input method. Most importantly, if your text field is intended for basic text input (such
+as for a text message), you should enable auto spelling correction with the
+{@code "textAutoCorrect"} value.</p>
+
+<p>You can combine different behaviors and input method styles with the
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute. For example,
+here's how to create a text field that capitalizes the first word of a sentence
+and also auto-corrects misspellings:</p>
+
+<pre>
+&lt;EditText
+    android:id="@+id/message"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:inputType=
+        "textCapSentences|textAutoCorrect"
+    ... />
+</pre>
+
+
+
+
+<h2 id="Action">Specify the Input Method Action</h2>
+
+<p>Most soft input methods provide a user action button in the
+bottom corner that's appropriate for the current text field.
+By default, the system uses this button for either a <b>Next</b> or
+<b>Done</b> action unless your text field allows multi-line text (such as with {@code
+android:inputType="textMultiLine"}), in which case the action button is a carriage return.
+However, you can specify additional actions that might be more appropriate for your
+text field, such as <b>Send</b> or <b>Go</b>.</p>
+
+<p>To specify the keyboard action button, use the <a
+href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code
+android:imeOptions}</a> attribute with an action value such as {@code "actionSend"} or
+{@code "actionSearch"}. For example:</p>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/ui/edittext-actionsend.png" alt="" />
+<p class="img-caption"><strong>Figure 4.</strong> The Send button appears when you declare
+{@code android:imeOptions="actionSend"}.</p>
+</div>
+
+<pre>
+&lt;EditText
+    android:id="@+id/search"
+    android:layout_width="fill_parent"
+    android:layout_height="wrap_content"
+    android:hint="@string/search_hint"
+    android:inputType="text"
+    android:imeOptions="actionSend" />
+</pre>
+
+<p>You can then listen for presses on the action button by defining a
+{@link android.widget.TextView.OnEditorActionListener} for the {@link android.widget.EditText}
+element. In your listener, respond to the appropriate IME action ID defined in the
+{@link android.view.inputmethod.EditorInfo} class, such as
+{@link android.view.inputmethod.EditorInfo#IME_ACTION_SEND}. For example:</p>
+
+<pre>
+EditText editText = (EditText) findViewById(R.id.search);
+editText.setOnEditorActionListener(new OnEditorActionListener() {
+    &#64;Override
+    public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
+        boolean handled = false;
+        if (actionId == EditorInfo.IME_ACTION_SEND) {
+            sendMessage();
+            handled = true;
+        }
+        return handled;
+    }
+});
+</pre>
+
+
+
diff --git a/docs/html/training/keyboard-input/visibility.jd b/docs/html/training/keyboard-input/visibility.jd
new file mode 100644
index 0000000..5dc6fc2
--- /dev/null
+++ b/docs/html/training/keyboard-input/visibility.jd
@@ -0,0 +1,133 @@
+page.title=Handling Input Method Visibility
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
  <li><a href="#ShowOnStart">Show the Input Method When the Activity Starts</a></li>
  <li><a href="#ShowOnDemand">Show the Input Method On Demand</a></li>
  <li><a href="#Respond">Specify How Your UI Should Respond</a></li>
</ol>
+
+</div>
+</div>
+
+
+<p>When input focus moves into or out of an editable text field, Android shows
+or hides the input method (such as the on-screen keyboard) as appropriate.
+The system also makes decisions about
+how your UI and the text field appear above the input method. For example, when the vertical
+space on the screen is constrained, the text field might fill all space above the input method.
+For most apps, these default behaviors are all that's needed.</p>
+
+<p>In some cases, though, you might want to more directly control
+the visibility of the input method and specify how you'd like your layout to appear
+when the input method is visible. This lesson explains how to control and respond to
+the input method visibility.</p>
+
+
+<h2 id="ShowOnStart">Show the Input Method When the Activity Starts</h2>
+
+<p>Although Android gives focus to the first text field in your layout
+when the activity starts, it does not show the input method. This behavior is appropriate because
+entering text might not be the primary task in the activity. However, if entering
+text is indeed the primary task (such as in a login screen), then you probably want
+the input method to appear by default.</p>
+
+<p>To show the input method when your activity starts, add the <a
+href="{@docRoot}guide/topics/manifest/activity-element.html#wsoft">{@code
+android:windowSoftInputMode}</a> attribute to the {@code &lt;activity>} element with the
+{@code "stateVisible"} value. For example:</p>
+
+<pre>
+&lt;application ... >
+    &lt;activity
+        android:windowSoftInputMode="stateVisible" ... >
+        ...
+    &lt;/activity>
+    ...
+&lt;/application>
+</pre>
+
+<p class="note"><strong>Note:</strong> If the user's device has an attached hardware keyboard,
+the soft input method <em>does not</em> appear.</p>
+
+
+<h2 id="ShowOnDemand">Show the Input Method On Demand</h2>
+
+<p>If there is a method in your activity's lifecycle where you want to ensure that
+the input method is visible, you can use the {@link android.view.inputmethod.InputMethodManager}
+to show it.</p>
+
+<p>For example, the following method takes a {@link android.view.View} in which the user should type
+something, calls {@link android.view.View#requestFocus requestFocus()} to give it focus, then
+{@link android.view.inputmethod.InputMethodManager#showSoftInput showSoftInput()} to open
+the input method:</p>
+
+<pre>
+public void showSoftKeyboard(View view) {
+    if (view.requestFocus()) {
+        InputMethodManager imm = (InputMethodManager)
+                getSystemService(Context.INPUT_METHOD_SERVICE);
+        imm.showSoftInput(view, InputMethodManager.SHOW_IMPLICIT);
+    }
+}
+</pre>
+
+<p class="note"><strong>Note:</strong>
+Once the input method is visible, you should not programmatically hide it. The system
+hides the input method when the user finishes the task in the text field or the user can hide
+it with a system control (such as with the <em>Back</em> button).</p>
+
+
+
+
+<h2 id="Respond">Specify How Your UI Should Respond</h2>
+
+<p>When the input method appears on the screen, it reduces the amount of space available
+for your app's UI. The system makes a decision as to how it should adjust the visible portion
+of your UI, but it might not get it right. To ensure the best behavior for your app,
+you should specify how you'd like the system to display your UI in the remaining space.</p>
+
+<p>To declare your preferred treatment in an activity, use the <a
+href="{@docRoot}guide/topics/manifest/activity-element.html#wsoft">{@code
+android:windowSoftInputMode}</a> attribute in your manifest's {@code &lt;activity>} element
+with one of the "adjust" values.</p>
+
+<p>For example, to ensure that the system resizes your layout to the available space&mdash;which
+ensures that all of your layout content is accessible (even though it probably requires
+scrolling)&mdash;use {@code "adjustResize"}:</p>
+
+<pre>
+&lt;application ... >
+    &lt;activity
+        android:windowSoftInputMode="adjustResize" ... >
+        ...
+    &lt;/activity>
+    ...
+&lt;/application>
+</pre>
+
+<p>You can combine the adjustment specification with the <a
+href="#ShowOnStart">initial input method visibility</a> specification from above:</p>
+
+<pre>
+    &lt;activity
+        android:windowSoftInputMode="stateVisible|adjustResize" ... >
+        ...
+    &lt;/activity>
+</pre>
+
+
+<p>Specifying {@code "adjustResize"} is important if your UI includes controls that the
+user might need to access immediately after or while performing text input. For example,
+if you use a relative layout to place a button bar at the bottom of the screen, using
+{@code "adjustResize"} resizes the layout so the button bar appears above the input method.</p>
+
+
+
+
+
+
+
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 17f8b91..9518046 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -194,6 +194,8 @@
     </ul>
   </li><!-- end getting started -->
   
+  
+  
 
   <li class="nav-section">
     <div class="nav-section-header">
@@ -799,9 +801,10 @@
   </li>
   <!-- End best UX and UI -->
   
+
   <li class="nav-section">
     <div class="nav-section-header">
-      <a href="<?cs var:toroot ?>training/best-performance.html">
+      <a href="<?cs var:toroot ?>training/best-user-input.html">
       <span class="small">Best Practices for</span><br/>
               User Input
       </a>
@@ -841,8 +844,37 @@
           </a>
           </li>
         </ul>
-      </li> 
-      </ul>
+      </li>
+      
+      <li class="nav-section">
+        <div class="nav-section-header">
+          <a href="<?cs var:toroot ?>training/keyboard-input/index.html"
+             description=
+             "How to specify the appearance and behaviors of soft input methods (such
+             as on-screen keyboards) and how to optimize the experience with
+             hardware keyboards."
+            >Handling Keyboard Input</a>
+        </div>
+        <ul>
+          <li><a href="<?cs var:toroot ?>training/keyboard-input/style.html">
+            Specifying the Input Method Type
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/keyboard-input/visibility.html">
+            Handling Input Method Visibility
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/keyboard-input/navigation.html">
+            Supporting Keyboard Navigation
+          </a>
+          </li>
+          <li><a href="<?cs var:toroot ?>training/keyboard-input/commands.html">
+            Handling Keyboard Actions
+          </a>
+          </li>
+        </ul>
+      </li>
+    </ul>
   </li> <!-- end of User Input -->    
 
   <li class="nav-section">