am 96f0e008: am 481102ee: am 0dae634b: Merge "docs: add class on keyboards" into jb-mr1-dev
* commit '96f0e00825cf1bf0f14c358b87394b426020a77b':
docs: add class on keyboards
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 @@
</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>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>
-<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>
+<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 @@
<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 @@
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
Binary files differ
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
Binary files differ
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>
+@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>
+@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—known as a
+<em>soft input method</em>—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
Binary files differ
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
+<EditText>} 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>
+<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>
+<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>
+<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>
+<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() {
+ @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..5dc6fc260
--- /dev/null
+++ b/docs/html/training/keyboard-input/visibility.jd
Binary files differ
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 17f8b912..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">
