docs/html/resources/articles/on-screen-inputs.jd

page.title=Onscreen Input Methods
parent.title=Articles
parent.link=../browser.html?tag=article
@jd:body


<div id="qv-wrapper">
<div id="qv">

  <h2>See also</h2>
  <ol>
    <li><a href="{@docRoot}resources/articles/creating-input-method.html">Creating an Input
Method</a></li>
    <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li>
  </ol>

</div>
</div>


<p>Starting from Android 1.5, the Android platform offers an Input Method
Framework (IMF) that lets you create on-screen input methods such as software
keyboards. This article provide an overview of what Android input method editors
(IMEs) are and what an application needs to do to work well with them. The IMF
is designed to support new classes of Android devices, such as those without
hardware keyboards, so it is important that your application works well with the
IMF and offers a great experience for users.</p>

<h3>What is an input method?</h3>

<p>The Android IMF is designed to support a variety of IMEs, including soft
keyboard, hand-writing recognizers, and hard keyboard translators. Our focus,
however, will be on soft keyboards, since this is the kind of input method that
is currently part of the platform.</p>

<p>A user will usually access the current IME by tapping on a text view to 
edit, as shown here in the home screen:</p>

<img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_004.png">
<img style="width: 320px; height: 480px;" src="images/on-screen-inputs.png">

<p>The soft keyboard is positioned at the bottom of the screen over the
application's window. To organize the available space between the application
and IME, we use a few approaches; the one shown here is called <em>pan and
scan</em>, and simply involves scrolling the application window around so that
the currently focused view is visible. This is the default mode, since it is the
safest for existing applications.</p>

<p>Most often the preferred screen layout is a <em>resize</em>, where the
application's window is resized to be entirely visible.  An example is shown
here, when composing an e-mail message:</p>

<img style="width: 320px; height: 480px; margin-right: 10px;" src="images/on-screen-inputs_005.png">
<img style="width: 320px; height: 480px;" src="images/on-screen-inputs_003.png">

<p>The size of the application window is changed so that none of it is hidden by
the IME, allowing full access to both the application and IME. This of course
only works for applications that have a resizeable area that can be reduced to
make enough space, but the vertical space in this mode is actually no less than
what is available in landscape orientation, so very often an application can
already accommodate it.</p>

<p>The final major mode is <em>fullscreen</em> or <em>extract</em>
mode. This is used when the IME is too large to reasonably share space
with the underlying application. With the standard IMEs, you will only
encounter this situation when the screen is in a landscape orientation,
although other IMEs are free to use it whenever they desire. In this
case the application window is left as-is, and the IME simply displays
fullscreen on top of it, as shown here:</p>

<img style="width: 480px; height: 320px; margin-right: 10px; margin-bottom: 10px;" src="images/on-screen-inputs_006.png">
<img style="width: 480px; height: 320px;" src="images/on-screen-inputs_002.png">

<p>Because the IME is covering the application, it has its own editing area,
which shows the text actually contained in the application. There are also some
limited opportunities the application has to customize parts of the IME (the
"done" button at the top and enter key label at the bottom) to improve the user
experience.</p>

<h3>Basic XML attributes for controlling IMEs</h3>

<p>There are a number of things the system does to try to help existing 
applications work with IMEs as well as possible, such as:</p>

<ul>
<li>Use pan and scan mode by default, unless it can reasonably guess that
resize mode will work by the existence of lists, scroll views, etc.</li>
<li>Analyze the various existing TextView attributes to guess at the kind of
content (numbers, plain text, etc) to help the soft keyboard display an
appropriate key layout.</li>
<li>Assign a few default actions to the fullscreen IME, such as "next field"
and "done".</li>
</ul>

<p>There are also some simple things you can do in your application that will
often greatly improve its user experience. Except where explicitly mentioned,
these will work in any Android platform version, even those previous to Android
1.5 (since they will simply ignore these new options).</p>

<h4>Specifying each EditText control's input type</h4>

<p>The most important thing for an application to do is to use the new
<code>android:inputType</code>
attribute on each <code>EditText</code>. The attribute provides much richer
information
about the text content. This attribute actually replaces many existing
attributes (<code>android:</code><code>password</code>,
<code>android:</code><code>singleLine</code>,
<code>android:</code><code>numeric</code>,
<code>android:</code><code>phoneNumber</code>,
<code>android:</code><code>capitalize</code>,
<code>android:</code><code>autoText</code>, and 
<code>android:</code><code>editable</code>). If you specify the older attributes
and the new <code>android:inputType</code> attribute, the system uses
<code>android:inputType</code> and ignores the others. </p>

<p>The <code>android:inputType</code> attribute has three pieces:</p>

<ul>
<li>The <em>class</em> is the overall interpretation of characters.  The
currently supported classes are <code>text</code> (plain text),
<code>number</code> (decimal number), <code>phone</code> (phone number), and
<code>datetime</code> (a date or time).</li>
<li>The <em>variation</em> is a further refinement on the class. In the
attribute you will normally specify the class and variant together, with the
class as a prefix. For example, <code>textEmailAddress</code> is a text field
where the user will enter something that is an e-mail address (foo@bar.com) so
the key layout will have an '@' character in easy access, and
<code>numberSigned</code> is a numeric field with a sign.  If only the class is
specified, then you get the default/generic variant.</li>
<li>Additional <em>flags</em> can be specified that supply further refinement. 
These flags are specific to a class.  For example, some flags for the
<code>text</code> class are <code>textCapSentences</code>,
<code>textAutoCorrect</code>, and <code>textMultiline</code>.</li>
</ul>

<p>As an example, here is the new EditText for the IM application's message text view:</p>

<pre>    &lt;EditText android:id="@+id/edtInput"
        android:layout_width="0dip"
        android:layout_height="wrap_content"
        android:layout_weight="1"
        android:inputType="textShortMessage|textAutoCorrect|textCapSentences|textMultiLine"
        android:imeOptions="actionSend|flagNoEnterAction"
        android:maxLines="4"
        android:maxLength="2000"
        android:hint="@string/compose_hint"/&gt;</pre>

<p>A full description of all of the input types can be found in the
documentation. It is important to make use of the correct input types that are
available, so that the soft keyboard can use the optimal keyboard layout for the
text the user will be entering.</p>

<h4>Enabling resize mode and other window features</h4>

<p>The second most important thing for your app to do is to specify the overall
behavior of your window in relation to the input method. The most visible aspect
of this is controlling resize vs. pan and scan mode, but there are other things
you can do as well to improve your user experience.</p>

<p>You will usually control this behavior through the
<code>android:windowSoftInputMode</code> attribute on each
<code>&lt;activity&gt;</code> definition in your
<code>AndroidManifest.xml</code>.  Like the input type, there are a couple
different pieces of data that can be specified here by combining them
together:</p>

<ul>
<li>The window adjustment mode is specified with either
<code>adjustResize</code> or <code>adjustPan</code>.  It is highly recommended
that you always specify one or the other.</li>
<li>You can further control whether the IME will be shown automatically when
your activity is displayed and other situations where the user moves to it. The
system won't automatically show an IME by default, but in some cases it can be
convenient for the user if an application enables this behavior. You can request
this with <code>stateVisible</code>.  There are also a number of other state
options for finer-grained control that you can find in the documentation.</li>
</ul>

<p>A typical example of this field can be see in the edit contact activity,
which ensures it is resized and automatically displays the IME for the user:</p>

<pre>    &lt;activity name="EditContactActivity"
        android:windowSoftInputMode="stateVisible|adjustResize"&gt;
        ...
    &lt;/activity&gt;</pre>

<p class="note"><strong>Note:</strong>Starting from Android 1.5 (API Level 3), 
the platform offers a new method, 
{@link android.view.Window#setSoftInputMode(int mode)},
that non-Activity windows can use to control their behavior. Calling this method
in your will make your application incompatible with previous versions of the
Android platform.</p>

<h4>Controlling the action buttons</h4>

<p>The final customization we will look at is the "action" buttons in the IME.  
There are currently two types of actions:</p>

<ul>
<li>The enter key on a soft keyboard is typically bound to an action when not
operating on a mult-line edit text. For example, on the G1 pressing the hard
enter key will typically move to the next field or the application will
intercept it to execute an action; with a soft keyboard, this overloading of the
enter key remains, since the enter button just sends an enter key event.</li>
<li>When in fullscreen mode, an IME may also put an additional action button to
the right of the text being edited, giving the user quick access to a common
application operation.</li>
</ul>

<p>These options are controlled with the <code>android:imeOptions</code> 
attribute on <code>TextView</code>. The value you supply here can be any 
combination of:</p>

<ul>
<li>One of the pre-defined action constants (<code>actionGo</code>,
<code>actionSearch</code>, <code>actionSend</code>, <code>actionNext</code>,
<code>actionDone</code>).  If none of these are specified, the system will infer
either <code>actionNext</code> or <code>actionDone</code> depending on whether
there is a focusable field after this one; you can explicitly force no action
with <code>actionNone</code>.</li>
<li>The <code>flagNoEnterAction</code> option tells the IME that the action
should <em>not</em> be available on the enter key, even if the text itself is
not multi-line. This avoids having unrecoverable actions like (send) that can be
accidentally touched by the user while typing.</li>
<li>The <code>flagNoAccessoryAction</code> removes the action button from the
text area, leaving more room for text.</li><li>The <code>flagNoExtractUi</code>
completely removes the text area, allowing the application to be seen behind
it.</li>
</ul>

<p>The previous IM application message view also provides an example of an
interesting use of <code>imeOptions</code>, to specify the send action but not
let it be shown on the enter key:</p>

<pre>android:imeOptions="actionSend|flagNoEnterAction"</pre>

<h3>APIs for controlling IMEs</h3>

<p>For more advanced control over the IME, there are a variety of new APIs you
can use. Unless special care is taken (such as by using reflection), using these
APIs will cause your application to be incompatible with previous versions of
Android, and you should make sure you specify
<code>android:minSdkVersion="3"</code> in your manifest. For more information,
see the documentation for the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">&lt;uses-sdk&gt;</a
> manifest element.</p>

<p>The primary API is the new <code>android.view.inputmethod.InputMethodManager</code> class, which you can retrieve with <code>Context.getSystemService()</code>.
It allows you to interact with the global input method state, such as
explicitly hiding or showing the current IME's input area.</p>

<p>There are also new window flags controlling input method interaction, which you can control through the existing <code>Window.addFlags()</code> method and new <code>Window.setSoftInputMode()</code> method.  The <code>PopupWindow</code>
class has grown corresponding methods to control these options on its
window. One thing in particular to be aware of is the new <code>WindowManager.LayoutParams.FLAG_ALT_FOCUSABLE_IM</code> constant, which is used to control whether a window is on top of or behind the current IME.</p>

<p>Most of the interaction between an active IME and application is done through the <code>android.view.inputmethod.InputConnection</code>
class. This is the API an application implement, which an IME calls to
perform the appropriate edit operations on the application. You won't
normally need to worry about this, since <code>TextView</code> provides its own implementation for itself.</p>

<p>There are also a handful of new <code>View</code> APIs, the most important of these being<code> onCreateInputConnection()</code> which creates a new <code>InputConnection</code> for an IME (and fills in an <code>android.view.inputmethod.EditorInfo</code>
structure with your input type, IME options, and other data); again,
most developers won't need to worry about this, since TextView takes
care of it for you.</p>