diff options
Diffstat (limited to 'docs/html/resources/articles/on-screen-inputs.jd')
| -rw-r--r-- | docs/html/resources/articles/on-screen-inputs.jd | 265 |
1 files changed, 0 insertions, 265 deletions
diff --git a/docs/html/resources/articles/on-screen-inputs.jd b/docs/html/resources/articles/on-screen-inputs.jd deleted file mode 100644 index 6a028c8..0000000 --- a/docs/html/resources/articles/on-screen-inputs.jd +++ /dev/null @@ -1,265 +0,0 @@ -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> <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 |