am 0dae634b: Merge "docs: add class on keyboards" into jb-mr1-dev (481102ee) · Commits · e / os / android_frameworks_base

docs/html/guide/topics/ui/controls/text.jd

+37 −11

Original line number	Diff line number	Diff line
		@@ -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;

docs/html/images/training/input/ime_autocorrect.png

0 → 100644

+35.1 KiB

Loading image diff...

docs/html/images/training/input/ime_password.png

0 → 100644

+26.7 KiB

Loading image diff...

docs/html/training/best-user-input.jd

0 → 100644

+9 −0

Original line number	Diff line number	Diff line
		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

docs/html/training/keyboard-input/commands.jd

0 → 100644

+113 −0

Original line number	Diff line number	Diff line
		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>