263 lines
13 KiB
Plaintext
263 lines
13 KiB
Plaintext
page.title=Onscreen Input Methods
|
|
@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> <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"/></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><activity></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> <activity name="EditContactActivity"
|
|
android:windowSoftInputMode="stateVisible|adjustResize">
|
|
...
|
|
</activity></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"><uses-sdk></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> |