Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit c8a6f8a0 authored by Scott Main's avatar Scott Main
Browse files

docs: add class on keyboards 

Change-Id: I3fb179457af50eec9d111f84eb9fabf49bc7ab1b
parent 5b03460f

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>

&#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>