diff options
Diffstat (limited to 'docs/html/resources/articles/on-screen-inputs.jd')
| -rw-r--r-- | docs/html/resources/articles/on-screen-inputs.jd | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/docs/html/resources/articles/on-screen-inputs.jd b/docs/html/resources/articles/on-screen-inputs.jd new file mode 100644 index 0000000..057325a --- /dev/null +++ b/docs/html/resources/articles/on-screen-inputs.jd @@ -0,0 +1,249 @@ +page.title=Onscreen Input Methods +@jd:body + + +<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>
\ No newline at end of file |