+Figure 1. The {@code phone} input type.
+There are several different input types available for different situations. You can find -them all listed with the documentation for {@code -android:inputType}.
+There are several different input types available for different situations. +Here are some of the more common values for +{@code android:inputType}:
-Tip: 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.
+The {@code android:inputType} 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.
+ +Here are some of the common input type values that define keyboard behaviors:
+ +For example, here's how you can collect a postal address, capitalize each word, and disable text suggestions:
@@ -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 0000000000000..fd8371bdcd0f4
Binary files /dev/null and b/docs/html/images/training/input/ime_autocorrect.png 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 0000000000000..6270c306764fe
Binary files /dev/null and b/docs/html/images/training/input/ime_password.png differ
diff --git a/docs/html/training/best-user-input.jd b/docs/html/training/best-user-input.jd
new file mode 100644
index 0000000000000..7f5ed152a8622
--- /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
+
+
+
+These classes cover various subjects of user input, such as
+touch screen gestures and text input through on-screen input methods and hardware keyboards.
\ 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 0000000000000..9d2de41b86935
--- /dev/null
+++ b/docs/html/training/keyboard-input/commands.jd
@@ -0,0 +1,113 @@
+page.title=Handling Keyboard Actions
+
+trainingnavtop=true
+
+@jd:body
+
+
+
+
+This lesson teaches you to
+
+
+
+
+
+
+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()}.
+
+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.
+
+Note: 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).
+
+
+Handle Single Key Events
+
+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.
+
+For example, this implementation responds to some keyboard keys to control a game:
+
+
+@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);
+ }
+}
+
+
+
+Handle Modifier Keys
+
+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()}.
+
+
+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:
+
+
+@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);
+ }
+}
+
+
+
+
diff --git a/docs/html/training/keyboard-input/index.jd b/docs/html/training/keyboard-input/index.jd
new file mode 100644
index 0000000000000..ba4e5983401f5
--- /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
+
+
+
+
+
+Dependencies and prerequisites
+
+ - Android 1.6 (API Level 3) or higher
+
+
+
+
+
+The Android system shows an on-screen keyboard—known as a
+soft input method—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).
+
+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.
+
+These topics and more are discussed in the following lessons.
+
+
+Lessons
+
+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.
+ +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.
+ +Note: +Supporting of directional navigation in your application is also important in ensuring that +your application is accessible +to users who do not navigate using visual cues. Fully supporting directional navigation in your +application can also help you automate user +interface testing with tools like uiautomator.
+ + + +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.
+ +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.
+ +To test your app:
+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).
+You can also use the Android emulator:
+Look for any instances in which the focus moves in a way you don't expect.
+From each focusable element in your UI, press Up, Down, Left, and Right.
+Look for any instances in which the focus moves in a way you don't expect.
+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.
+ + + +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.
+ +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 {@code +android:nextFocusForward} attribute:
+ ++<RelativeLayout ...> + <Button + android:id="@+id/button1" + android:layout_alignParentTop="true" + android:layout_alignParentRight="true" + android:nextFocusForward="@+id/editText1" + ... /> + <Button + android:id="@+id/button2" + android:layout_below="@id/button1" + android:nextFocusForward="@+id/button1" + ... /> + <EditText + android:id="@id/editText1" + android:layout_alignBottom="@+id/button2" + android:layout_toLeftOf="@id/button2" + android:nextFocusForward="@+id/button2" + ... /> + ... +</RelativeLayout> ++ +
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}.
+ + +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.
+ +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:
+Each attribute designates the next view to receive focus when the user navigates +in that direction, as specified by the view ID. For example:
+ ++<Button + android:id="@+id/button1" + android:nextFocusRight="@+id/button2" + android:nextFocusDown="@+id/editText1" + ... /> +<Button + android:id="@id/button2" + android:nextFocusLeft="@id/button1" + android:nextFocusDown="@id/editText1" + ... /> +<EditText + android:id="@id/editText1" + android:nextFocusUp="@id/button1" + ... /> ++ diff --git a/docs/html/training/keyboard-input/style.jd b/docs/html/training/keyboard-input/style.jd new file mode 100644 index 0000000000000..b0e506cf756c9 --- /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 + +
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).
+ +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 Done or Next. +This lesson shows how to specify these characteristics.
+ + + +You should always declare the input method for your text fields by adding +the {@code android:inputType} attribute to the {@link android.widget.EditText +<EditText>} element.
+ +
+Figure 1. The {@code phone} input type.
+For example, if you'd like an input method for entering a phone number, +use the {@code "phone"} value:
++<EditText + android:id="@+id/phone" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:hint="@string/phone_hint" + android:inputType="phone" /> ++ +
+Figure 2. The {@code textPassword} input type.
+Or if the text field is for a password, use the {@code "textPassword"} value +so the text field conceals the user's input:
++<EditText + android:id="@+id/password" + android:hint="@string/password_hint" + android:inputType="textPassword" + ... /> ++ +
There are several possible values documented with the +{@code android:inputType} attribute and +some of the values can be combined to specify the input method +appearance and additional behaviors.
+ + + +
+Figure 3. Adding {@code textAutoCorrect} +provides auto-correction for misspellings.
+The {@code android:inputType} 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.
+ +You can combine different behaviors and input method styles with the +{@code android:inputType} attribute. For example, +here's how to create a text field that capitalizes the first word of a sentence +and also auto-corrects misspellings:
+ ++<EditText + android:id="@+id/message" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:inputType= + "textCapSentences|textAutoCorrect" + ... /> ++ + + + +
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 Next or +Done 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 Send or Go.
+ +To specify the keyboard action button, use the {@code +android:imeOptions} attribute with an action value such as {@code "actionSend"} or +{@code "actionSearch"}. For example:
+ +
+Figure 4. The Send button appears when you declare +{@code android:imeOptions="actionSend"}.
++<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" /> ++ +
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:
+ +
+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;
+ }
+});
+
+
+
+
diff --git a/docs/html/training/keyboard-input/visibility.jd b/docs/html/training/keyboard-input/visibility.jd
new file mode 100644
index 0000000000000..5dc6fc260b01a
--- /dev/null
+++ b/docs/html/training/keyboard-input/visibility.jd
@@ -0,0 +1,133 @@
+page.title=Handling Input Method Visibility
+
+trainingnavtop=true
+
+@jd:body
+
+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.
+ +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.
+ + +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.
+ +To show the input method when your activity starts, add the {@code +android:windowSoftInputMode} attribute to the {@code <activity>} element with the +{@code "stateVisible"} value. For example:
+ ++<application ... > + <activity + android:windowSoftInputMode="stateVisible" ... > + ... + </activity> + ... +</application> ++ +
Note: If the user's device has an attached hardware keyboard, +the soft input method does not appear.
+ + +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.
+ +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:
+ +
+public void showSoftKeyboard(View view) {
+ if (view.requestFocus()) {
+ InputMethodManager imm = (InputMethodManager)
+ getSystemService(Context.INPUT_METHOD_SERVICE);
+ imm.showSoftInput(view, InputMethodManager.SHOW_IMPLICIT);
+ }
+}
+
+
+Note: +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 Back button).
+ + + + +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.
+ +To declare your preferred treatment in an activity, use the {@code +android:windowSoftInputMode} attribute in your manifest's {@code <activity>} element +with one of the "adjust" values.
+ +For example, to ensure that the system resizes your layout to the available space—which +ensures that all of your layout content is accessible (even though it probably requires +scrolling)—use {@code "adjustResize"}:
+ ++<application ... > + <activity + android:windowSoftInputMode="adjustResize" ... > + ... + </activity> + ... +</application> ++ +
You can combine the adjustment specification with the initial input method visibility specification from above:
+ ++ <activity + android:windowSoftInputMode="stateVisible|adjustResize" ... > + ... + </activity> ++ + +
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.
+ + + + + + + diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 17f8b91251403..951804683d4ca 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -194,6 +194,8 @@ + +