diff options
Diffstat (limited to 'docs/html/guide/topics')
| -rw-r--r-- | docs/html/guide/topics/graphics/hardware-accel.jd | 44 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/activity-element.jd | 28 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/application-element.jd | 174 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/uses-feature-element.jd | 44 | ||||
| -rw-r--r-- | docs/html/guide/topics/search/searchable-config.jd | 96 | ||||
| -rw-r--r-- | docs/html/guide/topics/text/creating-input-method.jd | 345 | ||||
| -rw-r--r-- | docs/html/guide/topics/ui/actionbar.jd | 2 |
7 files changed, 376 insertions, 357 deletions
diff --git a/docs/html/guide/topics/graphics/hardware-accel.jd b/docs/html/guide/topics/graphics/hardware-accel.jd index 7c957b8..3d1935a 100644 --- a/docs/html/guide/topics/graphics/hardware-accel.jd +++ b/docs/html/guide/topics/graphics/hardware-accel.jd @@ -327,6 +327,30 @@ changed.</li> <td class="value_pos">18</td> </tr> <tr> + <td class="label_pos">drawArc()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">drawRoundRect()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">saveLayer() with RectF dimensions</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">saveLayer() with float dimensions</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">saveLayerAlpha() with RectF dimensions</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">saveLayerAlpha() with float dimensions</td> + <td class="value_pos">21</td> + </tr> + <tr> <td colspan="5" class="s5">Paint</td> </tr> <tr> @@ -374,6 +398,26 @@ changed.</li> <td class="value_neg">✗</td> </tr> <tr> + <td class="label_pos">getFontFeatureSettings()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">isElegantTextHeight()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">isElegantTextHeight()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">setFontFeatureSettings()</td> + <td class="value_pos">21</td> + </tr> + <tr> + <td class="label_pos">setLetterSpacing()</td> + <td class="value_pos">21</td> + </tr> + <tr> <td colspan="5" class="s5">Xfermode</td> </tr> <tr> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index ade05c9..c1256f9 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -9,6 +9,7 @@ parent.link=manifest-intro.html android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] android:<a href="#autoremrecents">autoRemoveFromRecents</a>=["true" | "false"] + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"] android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale", "touchscreen", "keyboard", "keyboardHidden", @@ -153,6 +154,29 @@ automatically removed from the overview screen. This overrides the caller's use "{@code true}" or "{@code false}".</dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <activity>} tag to supply a default banner for a specific activity, or with the +<a href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> +tag to supply a banner for all application activities. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + + <dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> <dd>Whether or not all activities will be removed from the task, except for the root activity, whenever it is re-launched from the home screen — @@ -662,7 +686,9 @@ visible on screen — "{@code true}" if it should be finished, and <p> A value of "{@code true}" means that the activity will not leave a historical trace. It will not remain in the activity stack for the task, -so the user will not be able to return to it. +so the user will not be able to return to it. In this case, +{@link android.app.Activity#onActivityResult onActivityResult()} is never called if you +start another activity for a result from this activity. </p> <p> diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 33f6bce..8a0e837 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -7,12 +7,14 @@ page.title=<application> <dd><pre class="stx"><application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#allowbackup">allowBackup</a>=["true" | "false"] android:<a href="#agent">backupAgent</a>="<i>string</i>" + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#debug">debuggable</a>=["true" | "false"] android:<a href="#desc">description</a>="<i>string resource</i>" android:<a href="#enabled">enabled</a>=["true" | "false"] android:<a href="#code">hasCode</a>=["true" | "false"] android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"] android:<a href="#icon">icon</a>="<i>drawable resource</i>" + android:<a href="#isGame">isGame</a>=["true" | "false"] android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] android:<a href="#largeHeap">largeHeap</a>=["true" | "false"] android:<a href="#label">label</a>="<i>string resource</i>" @@ -48,13 +50,13 @@ page.title=<application> <dt>description:</dt> <dd itemprop="description">The declaration of the application. This element contains subelements -that declare each of the application's components and has attributes -that can affect all the components. Many of these attributes (such as -{@code icon}, {@code label}, {@code permission}, {@code process}, -{@code taskAffinity}, and {@code allowTaskReparenting}) set default values +that declare each of the application's components and has attributes +that can affect all the components. Many of these attributes (such as +{@code icon}, {@code label}, {@code permission}, {@code process}, +{@code taskAffinity}, and {@code allowTaskReparenting}) set default values for corresponding attributes of the component elements. Others (such as -{@code debuggable}, {@code enabled}, {@code description}, and -{@code allowClearUserData}) set values for the application as a whole and +{@code debuggable}, {@code enabled}, {@code description}, and +{@code allowClearUserData}) set values for the application as a whole and cannot be overridden by the components.</dd> @@ -65,18 +67,18 @@ cannot be overridden by the components.</dd> <dd><dl class="attr"> <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not activities that the application defines can move from -the task that started them to the task they have an affinity for when that task -is next brought to the front — {@code "true"} if they can move, and -{@code "false"} if they must remain with the task where they started. +<dd>Whether or not activities that the application defines can move from +the task that started them to the task they have an affinity for when that task +is next brought to the front — {@code "true"} if they can move, and +{@code "false"} if they must remain with the task where they started. The default value is {@code "false"}. <p> -The -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element has its own +The +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +element has its own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute that can override the value set here. See that attribute for more +attribute that can override the value set here. See that attribute for more information. </p></dd> @@ -92,46 +94,68 @@ The default value of this attribute is true.</dd> <dt><a name="agent"></a>{@code android:backupAgent}</dt> <dd>The name of the class that implement's the application's backup agent, a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be -a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). -However, as a shorthand, if the first character of the name is a period -(for example, {@code ".MyBackupAgent"}), it is appended to the -package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). +However, as a shorthand, if the first character of the name is a period +(for example, {@code ".MyBackupAgent"}), it is appended to the +package name specified in the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p> There is no default. The name must be specified. </p></dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <application>} tag to supply a default banner for all application activities, or with the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> +tag to supply a banner for a specific activity. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + <dt><a name="debug"></a>{@code android:debuggable}</dt> -<dd>Whether or not the application can be debugged, even when running +<dd>Whether or not the application can be debugged, even when running on a device in user mode — {@code "true"} if it can be, and {@code "false"} -if not. The default value is {@code "false"}.</dd> +if not. The default value is {@code "false"}.</dd> <dt><a name="desc"></a>{@code android:description}</dt> <dd>User-readable text about the application, longer and more descriptive than the application label. The value must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default value.</dd> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the Android system can instantiate components of -the application — {@code "true"} if it can, and {@code "false"} -if not. If the value is {@code "true"}, each component's -{@code enabled} attribute determines whether that component is enabled -or not. If the value is {@code "false"}, it overrides the +<dd>Whether or not the Android system can instantiate components of +the application — {@code "true"} if it can, and {@code "false"} +if not. If the value is {@code "true"}, each component's +{@code enabled} attribute determines whether that component is enabled +or not. If the value is {@code "false"}, it overrides the component-specific values; all components are disabled. <p> The default value is {@code "true"}. -</p></dd> +</p></dd> <dt><a name="code"></a>{@code android:hasCode}</dt> -<dd>Whether or not the application contains any code — {@code "true"} -if it does, and {@code "false"} if not. When the value is {@code "false"}, -the system does not try to load any application code when launching components. +<dd>Whether or not the application contains any code — {@code "true"} +if it does, and {@code "false"} if not. When the value is {@code "false"}, +the system does not try to load any application code when launching components. The default value is {@code "true"}. <p> An application would not have any code of its own only if it's using nothing -but built-in component classes, such as an activity that uses the {@link +but built-in component classes, such as an activity that uses the {@link android.app.AliasActivity} class, a rare occurrence.</p> </dd> @@ -140,7 +164,7 @@ android.app.AliasActivity} class, a rare occurrence.</p> activities and views in this application — {@code "true"} if it should be enabled, and {@code "false"} if not. The default value is {@code "true"} if you've set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> -or <a +or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to {@code "14"} or higher; otherwise, it's {@code "false"}. @@ -161,20 +185,26 @@ make use of the renderer without errors.</p> </dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the application as whole, and the default icon for -each of the application's components. See the individual -{@code icon} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>An icon for the application as whole, and the default icon for +each of the application's components. See the individual +{@code icon} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/icon"}). There is no default icon. +the image (for example {@code "@drawable/icon"}). There is no default icon. </p></dd> +<dt><a name="isGame"></a>{@code android:isGame}</dt> +<dd>Whether or not the application is a game. The system may group together applications classifed +as games or display them separately from other applications. + +<p>The default is {@code false}.</p></dd> + <dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> <dd>Whether the application in question should be terminated after its settings have been restored during a full-system restore operation. @@ -202,65 +232,65 @@ because some devices are constrained by their total available memory.</p> </dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the application as a whole, and a default -label for each of the application's components. See the individual -{@code label} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>A user-readable label for the application as a whole, and a default +label for each of the application's components. See the individual +{@code label} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="logo"></a>{@code android:logo}</dt> <dd>A logo for the application as whole, and the default logo for activities. <p>This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> +the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> <dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> -<dd>The fully qualified name of an Activity subclass that the system -can launch to let users manage the memory occupied by the application -on the device. The activity should also be declared with an +<dd>The fully qualified name of an Activity subclass that the system +can launch to let users manage the memory occupied by the application +on the device. The activity should also be declared with an <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. </dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The fully qualified name of an {@link android.app.Application} -subclass implemented for the application. When the application process -is started, this class is instantiated before any of the application's -components. +<dd>The fully qualified name of an {@link android.app.Application} +subclass implemented for the application. When the application process +is started, this class is instantiated before any of the application's +components. <p> The subclass is optional; most applications won't need one. -In the absence of a subclass, Android uses an instance of the base +In the absence of a subclass, Android uses an instance of the base Application class. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have in order to interact -with the application. This attribute is a convenient way to set a -permission that applies to all of the application's components. It can -be overwritten by setting the {@code permission} attributes of individual +<dd>The name of a permission that clients must have in order to interact +with the application. This attribute is a convenient way to set a +permission that applies to all of the application's components. It can +be overwritten by setting the {@code permission} attributes of individual components. <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and another document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="persistent"></a>{@code android:persistent}</dt> -<dd>Whether or not the application should remain running at all times — -{@code "true"} if it should, and {@code "false"} if not. The default value -is {@code "false"}. Applications should not normally set this flag; +<dd>Whether or not the application should remain running at all times — +{@code "true"} if it should, and {@code "false"} if not. The default value +is {@code "false"}. Applications should not normally set this flag; persistence mode is intended only for certain system applications.</dd> <dt><a name="proc"></a>{@code android:process}</dt> @@ -282,9 +312,9 @@ user ID and be signed with the same certificate. </p> <p> -If the name assigned to this attribute begins with a colon (':'), a new +If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is created when it's needed. -If the process name begins with a lowercase character, a global process +If the process name begins with a lowercase character, a global process of that name is created. A global process can be shared with other applications, reducing resource usage. </p></dd> @@ -307,7 +337,7 @@ incompatible. <em>Use with caution!</em> If your app requires an {@link android.accounts.Account}, the value for this attribute must correspond to the account authenticator type used by your app (as defined by {@link android.accounts.AuthenticatorDescription}), -such as "com.google". +such as "com.google". <p>The default value is null and indicates that the application can work <em>without</em> any accounts. @@ -369,13 +399,13 @@ direction associated to the user's Locale choice (your layouts will always be le <dt><a name="aff"></a>{@code android:taskAffinity}</dt> <dd>An affinity name that applies to all activities within the application, except for those that set a different affinity with their own -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attributes. See that attribute for more information. <p> -By default, all activities within an application share the same -affinity. The name of that affinity is the same as the package name -set by the +By default, all activities within an application share the same +affinity. The name of that affinity is the same as the package name +set by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p></dd> @@ -389,7 +419,7 @@ only through adb.</dd> <dt><a name="theme"></a>{@code android:theme}</dt> <dd>A reference to a style resource defining a default theme for all activities in the application. Individual activities can override -the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> +the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> attributes. For more information, see the <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. </dd> diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index a716bf8..2385592 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -27,12 +27,12 @@ page.tags=filtering,features,google play filters,permissions </div> </div> - <div class="sidebox-wrapper"> + <div class="sidebox-wrapper"> <div class="sidebox"> - <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play Filtering</p> <p style="padding-top:1em;">Google Play uses the <code><uses-feature></code> - elements declared in your app manifest to filter your app from devices + elements declared in your app manifest to filter your app from devices that do not meet it's hardware and software feature requirements. </p> <p style="margin-top:1em;">By specifying the features that your application requires, @@ -98,7 +98,7 @@ application requires.</p> <p>Declared <code><uses-feature></code> elements are informational only, meaning that the Android system itself does not check for matching feature support on the device before installing an application. However, other services -(such as Google Play) or applications may check your application's +(such as Google Play) or applications may check your application's <code><uses-feature></code> declarations as part of handling or interacting with your application. For this reason, it's very important that you declare all of the features (from the list below) that your application uses. </p> @@ -124,7 +124,7 @@ permission grants your application access to the appropriate hardware and software, while declaring the features used by your application ensures proper device compatibility.</p> -</dd> +</dd> <dt>attributes:</dt> @@ -352,7 +352,7 @@ not offer a camera.</p> <p>If you don't want Google Play to filter based on a specific implied feature, you can disable that behavior. To do so, declare the feature explicitly -in a <code><uses-feature></code> element and include an +in a <code><uses-feature></code> element and include an <code>android:required="false"</code> attribute. For example, to disable filtering derived from the <code>CAMERA</code> permission, you would declare the feature as shown below.</p> @@ -560,7 +560,7 @@ is sensitive to delays or lag in sound input or output.</td> <td></td> </tr> <tr> - <td rowspan="5">Camera</td> + <td rowspan="6">Camera</td> <td><code>android.hardware.camera</code></td> <td>The application uses the device's camera. If the device supports multiple cameras, the application uses the camera that facing @@ -593,6 +593,22 @@ external camera device if one is connected. Use this in preference to <td><code>android.hardware.camera.external</code></td> <td>The application uses an external camera device if one is connected.</td> </tr> +<tr> + <td><code>android.hardware.camera.level.full</code></td> + <td>The application uses a camera device with <code>FULL</code>-level support.</td> +</tr> +<tr> + <td><code>android.hardware.camera.capability.manual_sensor</code></td> + <td>The application uses a a camera device with the <code>MANUAL_SENSOR</code> capability.</td> +</tr> +<tr> + <td><code>android.hardware.camera.capability.manual_post_processing</code></td> + <td>The application uses a a camera device with the <code>MANUAL_POST_PROCESSING</code> capability.</td> +</tr> +<tr> + <td><code>android.hardware.camera.capability.raw</code></td> + <td>The application uses a a camera device with the <code>RAW</code> capability.</td> +</tr> <tr> <td>Infrared</td> @@ -741,9 +757,9 @@ device.</td> <td>Television</td> <td><code>android.hardware.type.television</code></td> <td>The application is designed for a television user experience.</td> - <td>This feature defines "television" to be a typical living room television experience: - displayed on a big screen, where the user is sitting far away and the dominant form of - input is something like a d-pad, and generally not through touch or a + <td>This feature defines "television" to be a typical living room television experience: + displayed on a big screen, where the user is sitting far away and the dominant form of + input is something like a d-pad, and generally not through touch or a mouse/pointer-device.</td> </tr> @@ -880,9 +896,9 @@ in a separate <code><uses-feature></code> element. </p> <table> -<tr> +<tr> <th>Feature</th> - <th>Attribute Value</th> + <th>Attribute Value</th> <th>Description</th> </tr> <tr> @@ -965,7 +981,7 @@ filtering based on the <code>CAMERA</code> permission, you would add this <pre><uses-feature android:name="android.hardware.camera" android:required="false" /></pre> <table id="permissions-features" > - <tr> + <tr> <th>Category</th> <th>This Permission...</th> <th>Implies This Feature Requirement</th> diff --git a/docs/html/guide/topics/search/searchable-config.jd b/docs/html/guide/topics/search/searchable-config.jd index e38024c..4874bb4 100644 --- a/docs/html/guide/topics/search/searchable-config.jd +++ b/docs/html/guide/topics/search/searchable-config.jd @@ -32,26 +32,26 @@ Android uses the filename as the resource ID.</dd> <pre class="stx"> <?xml version="1.0" encoding="utf-8"?> <<a href="#searchable-element">searchable</a> xmlns:android="http://schemas.android.com/apk/res/android" - android:label="<em>string resource</em>" - android:hint="<em>string resource</em>" - android:searchMode=["queryRewriteFromData" | "queryRewriteFromText"] - android:searchButtonText="<em>string resource</em>" - android:inputType="<em>{@link android.R.attr#inputType}</em>" - android:imeOptions="<em>{@link android.R.attr#imeOptions}</em>" - android:searchSuggestAuthority="<em>string</em>" - android:searchSuggestPath="<em>string</em>" - android:searchSuggestSelection="<em>string</em>" - android:searchSuggestIntentAction="<em>string</em>" - android:searchSuggestIntentData="<em>string</em>" - android:searchSuggestThreshold="<em>int</em>" - android:includeInGlobalSearch=["true" | "false"] - android:searchSettingsDescription="<em>string resource</em>" - android:queryAfterZeroResults=["true" | "false"] - android:voiceSearchMode=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"] - android:voiceLanguageModel=["free-form" | "web_search"] - android:voicePromptText="<em>string resource</em>" - android:voiceLanguage="<em>string</em>" - android:voiceMaxResults="<em>int</em>" + android:<a href="#label">label</a>="<em>string resource</em>" + android:<a href="#hint">hint</a>="<em>string resource</em>" + android:<a href="#searchMode">searchMode</a>=["queryRewriteFromData" | "queryRewriteFromText"] + android:<a href="#searchButtonText">searchButtonText</a>="<em>string resource</em>" + android:<a href="#inputType">inputType</a>="<em>{@link android.R.attr#inputType}</em>" + android:<a href="#imeOptions">imeOptions</a>="<em>{@link android.R.attr#imeOptions}</em>" + android:<a href="#searchSuggestAuthority">searchSuggestAuthority</a>="<em>string</em>" + android:<a href="#searchSuggestPath">searchSuggestPath</a>="<em>string</em>" + android:<a href="#searchSuggestSelection">searchSuggestSelection</a>="<em>string</em>" + android:<a href="#searchSuggestIntentAction">searchSuggestIntentAction</a>="<em>string</em>" + android:<a href="#searchSuggestIntentData">searchSuggestIntentData</a>="<em>string</em>" + android:<a href="#searchSuggestThreshold">searchSuggestThreshold</a>="<em>int</em>" + android:<a href="#includeInGlobalSearch">includeInGlobalSearch</a>=["true" | "false"] + android:<a href="#searchSettingsDescription">searchSettingsDescription</a>="<em>string resource</em>" + android:<a href="#queryAfterZeroResults">queryAfterZeroResults</a>=["true" | "false"] + android:<a href="#voiceSearchMode">voiceSearchMode</a>=["showVoiceSearchButton" | "launchWebSearch" | "launchRecognizer"] + android:<a href="#voiceLanguageModel">voiceLanguageModel</a>=["free-form" | "web_search"] + android:<a href="#voicePromptText">voicePromptText</a>="<em>string resource</em>" + android:<a href="#voiceLanguage">voiceLanguage</a>="<em>string</em>" + android:<a href="#voiceMaxResults">voiceMaxResults</a>="<em>int</em>" > <<a href="#actionkey-element">actionkey</a> android:keycode="<em>{@link android.view.KeyEvent KEYCODE}</em>" @@ -69,7 +69,7 @@ Android uses the filename as the resource ID.</dd> <dd>Defines all search configurations used by the Android system to provide assisted search. <p class="caps">attributes:</p> <dl class="atn-list"> - <dt><code>android:label</code></dt> + <dt><a name="label"></a><code>android:label</code></dt> <dd><em>String resource</em>. (Required.) The name of your application. It should be the same as the name applied to the {@code android:label} attribute of your <a href="{@docRoot}guide/topics/manifest/activity-element.html#label">{@code <activity>}</a> or @@ -78,14 +78,14 @@ href="{@docRoot}guide/topics/manifest/activity-element.html#label">{@code <ac <code>android:includeInGlobalSearch</code> to "true", in which case, this label is used to identify your application as a searchable item in the system's search settings.</dd> - <dt><code>android:hint</code></dt> + <dt><a name="hint"></a><code>android:hint</code></dt> <dd><em>String resource</em>. (Recommended.) The text to display in the search text field when no text has been entered. It provides a hint to the user about what content is searchable. For consistency with other Android applications, you should format the string for {@code android:hint} as "Search <em><content-or-product></em>". For example, "Search songs and artists" or "Search YouTube".</dd> - <dt><code>android:searchMode</code></dt> + <dt><a name="searchMode"></a><code>android:searchMode</code></dt> <dd><em>Keyword</em>. Sets additional modes that control the search presentation. Currently available modes define how the query text should be rewritten when a custom suggestion receives focus. The following mode values are accepted: @@ -109,19 +109,19 @@ inspection and editing, typically HTTP URI's.</td> href="adding-custom-suggestions.html#RewritingQueryText">Adding Custom Suggestions</a>.</p> </dd> - <dt><code>android:searchButtonText</code></dt> + <dt><a name="searchButtonText"></a><code>android:searchButtonText</code></dt> <dd><em>String resource</em>. The text to display in the button that executes search. By default, the button shows a search icon (a magnifying glass), which is ideal for internationalization, so you should not use this attribute to change the button unless the behavior is something other than a search (such as a URL request in a web browser).</dd> - <dt><code>android:inputType</code></dt> + <dt><a name="inputType"></a><code>android:inputType</code></dt> <dd><em>Keyword</em>. Defines the type of input method (such as the type of soft keyboard) -to use. For most searches, in which free-form text is expected, you don't +to use. For most searches, in which free-form text is expected, you don't need this attribute. See {@link android.R.attr#inputType} for a list of suitable values for this attribute.</dd> - <dt><code>android:imeOptions</code></dt> + <dt><a name="imeOptions"></a><code>android:imeOptions</code></dt> <dd><em>Keyword</em>. Supplies additional options for the input method. For most searches, in which free-form text is expected, you don't need this attribute. The default IME is "actionSearch" (provides the "search" button instead of a carriage @@ -139,12 +139,12 @@ for this attribute. {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> - <dt><code>android:searchSuggestAuthority</code></dt> + <dt><a name="searchSuggestAuthority"></a><code>android:searchSuggestAuthority</code></dt> <dd><em>String</em>. (Required to provide search suggestions.) This value must match the authority string provided in the {@code android:authorities} attribute of the Android manifest {@code <provider>} element.</dd> - <dt><code>android:searchSuggestPath</code></dt> + <dt><a name="searchSuggestPath"></a><code>android:searchSuggestPath</code></dt> <dd><em>String</em>. This path is used as a portion of the suggestions query {@link android.net.Uri}, after the prefix and authority, but before the standard suggestions path. @@ -152,7 +152,7 @@ the standard suggestions path. of suggestions (such as for different data types) and you need a way to disambiguate the suggestions queries when you receive them.</dd> - <dt><code>android:searchSuggestSelection</code></dt> + <dt><a name="searchSuggestSelection"></a><code>android:searchSuggestSelection</code></dt> <dd><em>String</em>. This value is passed into your query function as the {@code selection} parameter. Typically this is a WHERE clause for your database, and should contain a single question mark, which is a placeholder for the @@ -160,22 +160,22 @@ actual query string that has been typed by the user (for example, {@code "query= can also use any non-null value to trigger the delivery of the query text via the {@code selectionArgs} parameter (and then ignore the {@code selection} parameter).</dd> - <dt><code>android:searchSuggestIntentAction</code></dt> + <dt><a name="searchSuggestIntentAction"></a><code>android:searchSuggestIntentAction</code></dt> <dd><em>String</em>. The default intent action to be used when a user clicks on a custom search suggestion (such as {@code "android.intent.action.VIEW"}). If this is not overridden by the selected suggestion (via the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_ACTION} column), this value is placed in the action field of the {@link android.content.Intent} when the user clicks a suggestion.</dd> - <dt><code>android:searchSuggestIntentData</code></dt> + <dt><a name="searchSuggestIntentData"></a><code>android:searchSuggestIntentData</code></dt> <dd><em>String</em>. The default intent data to be used when a user clicks on a custom search suggestion. If not overridden by the selected suggestion (via the {@link android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is - placed in the data field of the {@link android.content.Intent} when the user clicks + placed in the data field of the {@link android.content.Intent} when the user clicks a suggestion.</dd> - <dt><code>android:searchSuggestThreshold</code></dt> + <dt><a name="searchSuggestThreshold"></a><code>android:searchSuggestThreshold</code></dt> <dd><em>Integer</em>. The minimum number of characters needed to trigger a suggestion look-up. Only guarantees that the system will not query your content provider for anything shorter than the threshold. The default value is 0.</dd> @@ -192,20 +192,20 @@ android.app.SearchManager#SUGGEST_COLUMN_INTENT_DATA} column), this value is following {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> - <dt><code>android:includeInGlobalSearch</code></dt> + <dt><a name="includeInGlobalSearch"></a><code>android:includeInGlobalSearch</code></dt> <dd><em>Boolean</em>. (Required to provide search suggestions in Quick Search Box.) Set to "true" if you want your suggestions to be included in the globally accessible Quick Search Box. The user must still enable your application as a searchable item in the system search settings before your suggestions will appear in Quick Search Box.</dd> - <dt><code>android:searchSettingsDescription</code></dt> + <dt><a name="searchSettingsDescription"></a><code>android:searchSettingsDescription</code></dt> <dd><em>String</em>. Provides a brief description of the search suggestions that you provide to Quick Search Box, which is displayed in the searchable items entry for your application. Your description should concisely describe the content that is searchable. For example, "Artists, albums, and tracks" for a music application, or "Saved notes" for a notepad application.</dd> - <dt><code>android:queryAfterZeroResults</code></dt> + <dt><a name="queryAfterZeroResults"></a><code>android:queryAfterZeroResults</code></dt> <dd><em>Boolean</em>. Set to "true" if you want your content provider to be invoked for supersets of queries that have returned zero results in the past. For example, if your content provider returned zero results for "bo", it should be requiried for "bob". If set to @@ -222,7 +222,7 @@ content provider again). The default value is false.</dd> following {@code <searchable>} attributes:</p><br/> <dl class="atn-list"> - <dt><code>android:voiceSearchMode</code></dt> + <dt><a name="voiceSearchMode"></a><code>android:voiceSearchMode</code></dt> <dd><em>Keyword</em>. (Required to provide voice search capabilities.) Enables voice search, with a specific mode for voice search. (Voice search may not be provided by the device, in which case these flags @@ -252,7 +252,7 @@ then either {@code "launchWebSearch"} or {@code "launchRecognizer"} must also be </table> </dd> - <dt><code>android:voiceLanguageModel</code></dt> + <dt><a name="voiceLanguageModel"></a><code>android:voiceLanguageModel</code></dt> <dd><em>Keyword</em>. The language model that should be used by the voice recognition system. The following values are accepted: <table> @@ -268,20 +268,20 @@ optimized for English. This is the default.</td> available in more languages than "free_form".</td> </tr> </table> - <p>Also see + <p>Also see {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL} for more information.</p></dd> - <dt><code>android:voicePromptText</code></dt> + <dt><a name="voicePromptText"></a><code>android:voicePromptText</code></dt> <dd><em>String</em>. An additional message to display in the voice input dialog.</dd> - <dt><code>android:voiceLanguage</code></dt> + <dt><a name="voiceLanguage"></a><code>android:voiceLanguage</code></dt> <dd><em>String</em>. The spoken language to be expected, expressed as the string value of a constants in {@link java.util.Locale} (such as {@code "de"} for German or {@code "fr"} for French). This is needed only if it is different from the current value of {@link java.util.Locale#getDefault() Locale.getDefault()}.</dd> - <dt><code>android:voiceMaxResults</code></dt> + <dt><a name="voiceMaxResults"></a><code>android:voiceMaxResults</code></dt> <dd><em>Integer</em>. Forces the maximum number of results to return, including the "best" result which is always provided as the {@link android.content.Intent#ACTION_SEARCH} intent's primary @@ -308,7 +308,7 @@ keys are not generally discoverable, so you should not provide them as a core us other three attributes in order to define the search action.</p> <p class="caps">attributes:</p> <dl class="atn-list"> - <dt><code>android:keycode</code></dt> + <dt><a name="keycode"></a><code>android:keycode</code></dt> <dd><em>String</em>. (Required.) A key code from {@link android.view.KeyEvent} that represents the action key you wish to respond to (for example {@code "KEYCODE_CALL"}). This is added to the @@ -318,7 +318,7 @@ android.view.KeyEvent} that represents the action key keys are supported for a search action, as many of them are used for typing, navigation, or system functions.</dd> - <dt><code>android:queryActionMsg</code></dt> + <dt><a name="queryActionMsg"></a><code>android:queryActionMsg</code></dt> <dd><em>String</em>. An action message to be sent if the action key is pressed while the user is entering query text. This is added to the {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} intent that the system @@ -326,17 +326,17 @@ user is entering query text. This is added to the {@link android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}.</dd> - <dt><code>android:suggestActionMsg</code></dt> + <dt><a name="suggestActionMsg"></a><code>android:suggestActionMsg</code></dt> <dd><em>String</em>. An action message to be sent if the action key is pressed while a suggestion is in focus. This is added to the intent that the system passes to your searchable activity (using the action you've defined for the suggestion). To examine the string, - use {@link android.content.Intent#getStringExtra + use {@link android.content.Intent#getStringExtra getStringExtra(SearchManager.ACTION_MSG)}. This should only be used if all your suggestions support this action key. If not all suggestions can handle the same action key, then you must instead use the following {@code android:suggestActionMsgColumn} attribute.</dd> - <dt><code>android:suggestActionMsgColumn</code></dt> + <dt><a name="suggestActionMsgColumn"></a><code>android:suggestActionMsgColumn</code></dt> <dd><em>String</em>. The name of the column in your content provider that defines the action message for this action key, which is to be sent if the user presses the action key while a suggestion is in focus. This attribute lets you control the diff --git a/docs/html/guide/topics/text/creating-input-method.jd b/docs/html/guide/topics/text/creating-input-method.jd index 802b58a..424a21c 100644 --- a/docs/html/guide/topics/text/creating-input-method.jd +++ b/docs/html/guide/topics/text/creating-input-method.jd @@ -41,8 +41,8 @@ page.tags=ime,keyboard,inputmethodservice <p> To add an IME to the Android system, you create an Android application containing a class that extends {@link android.inputmethodservice.InputMethodService}. In - addition, you usually create a "settings" activity that passes options to the IME - service. You can also define a settings UI that's displayed as part of the system settings. + addition, you usually create a "settings" activity that passes options to the IME service. You + can also define a settings UI that's displayed as part of the system settings. </p> <p>This guide covers the following:</p> <ul> @@ -70,29 +70,22 @@ page.tags=ime,keyboard,inputmethodservice <strong>Figure 1.</strong> The life cycle of an IME. </p> <p> - The following sections describe how to implement the UI and code associated -with an IME that + The following sections describe how to implement the UI and code associated with an IME that follows this lifecycle. </p> <h2 id="DefiningIME">Declaring IME Components in the Manifest</h2> <p> - In the Android system, an IME is an Android application that contains a -special IME service. - The application's manifest file must declare the service, request the -necessary permissions, - provide an intent filter that matches the action -<code>action.view.InputMethod</code>, and - provide metadata that defines characteristics of the IME. In addition, to -provide a settings - interface that allows the user to modify the behavior of the IME, you can -define a "settings" + In the Android system, an IME is an Android application that contains a special IME service. + The application's manifest file must declare the service, request the necessary permissions, + provide an intent filter that matches the action <code>action.view.InputMethod</code>, and + provide metadata that defines characteristics of the IME. In addition, to provide a settings + interface that allows the user to modify the behavior of the IME, you can define a "settings" activity that can be launched from System Settings. </p> <p> The following snippet declares an IME service. It requests the permission -{@link android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to -connect the IME to - the system, sets up an intent filter that matches the action + {@link android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME + to the system, sets up an intent filter that matches the action <code>android.view.InputMethod</code>, and defines metadata for the IME: </p> <pre> @@ -108,10 +101,8 @@ android:resource="@xml/method" /> </service> </pre> <p> - This next snippet declares the settings activity for the IME. It has an -intent filter for - {@link android.content.Intent#ACTION_MAIN} that indicates this activity is -the main entry point + This next snippet declares the settings activity for the IME. It has an intent filter for + {@link android.content.Intent#ACTION_MAIN} that indicates this activity is the main entry point for the IME application:</p> <pre> <!-- Optional: an activity for controlling the IME settings --> @@ -127,23 +118,18 @@ the main entry point </p> <h2 id="IMEAPI">The Input Method API</h2> <p> - Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link android.view.inputmethod} - packages. The {@link android.view.KeyEvent} class is important for handling keyboard - characters. + Classes specific to IMEs are found in the {@link android.inputmethodservice} and + {@link android.view.inputmethod} packages. The {@link android.view.KeyEvent} class is + important for handling keyboard characters. </p> <p> The central part of an IME is a service component, a class that extends - {@link android.inputmethodservice.InputMethodService}. In addition to -implementing the - normal service lifecycle, this class has callbacks for providing your IME's -UI, handling user - input, and delivering text to the field that currently has focus. By -default, the - {@link android.inputmethodservice.InputMethodService} class provides most -of the implementation - for managing the state and visibility of the IME and communicating with the -current - input field. + {@link android.inputmethodservice.InputMethodService}. In addition to implementing the + normal service lifecycle, this class has callbacks for providing your IME's UI, handling user + input, and delivering text to the field that currently has focus. By default, the + {@link android.inputmethodservice.InputMethodService} class provides most of the implementation + for managing the state and visibility of the IME and communicating with the current input + field. </p> <p> The following classes are also important: @@ -152,45 +138,32 @@ current <dt>{@link android.view.inputmethod.BaseInputConnection}</dt> <dd> Defines the communication channel from an {@link android.view.inputmethod.InputMethod} - back to the application that is receiving its input. You use it to read -text around the - cursor, commit text to the text box, and send raw key events to the -application. - Applications should extend this class rather than implementing the base -interface + back to the application that is receiving its input. You use it to read text around the + cursor, commit text to the text box, and send raw key events to the application. + Applications should extend this class rather than implementing the base interface {@link android.view.inputmethod.InputConnection}. </dd> <dt>{@link android.inputmethodservice.KeyboardView}</dt> <dd> - An extension of {@link android.view.View} that renders a keyboard and -responds to user + An extension of {@link android.view.View} that renders a keyboard and responds to user input events. The keyboard layout is specified by an instance of - {@link android.inputmethodservice.Keyboard}, which you can define in an -XML file. + {@link android.inputmethodservice.Keyboard}, which you can define in an XML file. </dd> </dl> <h2 id="IMEUI">Designing the Input Method UI</h2> <p> - There are two main visual elements for an IME: the <strong>input</strong> -view and the - <strong>candidates</strong> view. You only have to implement the elements -that are relevant to + There are two main visual elements for an IME: the <strong>input</strong> view and the + <strong>candidates</strong> view. You only have to implement the elements that are relevant to the input method you're designing. </p> <h3 id="InputView">Input view</h3> <p> - The input view is the UI where the user inputs text in the form of -keyclicks, handwriting or - gestures. When the IME is displayed for the first time, the system calls -the - {@link android.inputmethodservice.InputMethodService#onCreateInputView()} -callback. In your - implementation of this method, you create the layout you want to display in -the IME - window and return the layout to the system. This snippet is an example of -implementing the - {@link android.inputmethodservice.InputMethodService#onCreateInputView()} -method: + The input view is the UI where the user inputs text in the form of keyclicks, handwriting or + gestures. When the IME is displayed for the first time, the system calls the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your + implementation of this method, you create the layout you want to display in the IME + window and return the layout to the system. This snippet is an example of implementing the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: <pre> @Override public View onCreateInputView() { @@ -215,17 +188,12 @@ traditional QWERTY keyboard, </p> <h3 id="CandidateView">Candidates view</h3> <p> - The candidates view is the UI where the IME displays potential word -corrections or + The candidates view is the UI where the IME displays potential word corrections or suggestions for the user to select. In the IME lifecycle, the system calls - {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when -it's ready - to display the candidates view. In your implementation of this method, -return a layout that shows - word suggestions, or return null if you don’t want to show anything. A -null response is the - default behavior, so you don’t have to implement this if you don’t -provide suggestions.</p> + {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready + to display the candidates view. In your implementation of this method, return a layout that + shows word suggestions, or return null if you don’t want to show anything. A null response is + the default behavior, so you don’t have to implement this if you don’t provide suggestions.</p> <p> For an example implementation that provides user suggestions, see the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/"> @@ -237,32 +205,22 @@ provide suggestions.</p> </p> <h4>Handling multiple screen sizes</h4> <p> - The UI for your IME must be able to scale for different screen sizes, and -it also - must handle both landscape and portrait orientations. In non-fullscreen IME -mode, leave - sufficient space for the application to show the text field and any -associated context, so that - no more than half the screen is occupied by the IME. In fullscreen IME mode -this is not an + The UI for your IME must be able to scale for different screen sizes, and it also + must handle both landscape and portrait orientations. In non-fullscreen IME mode, leave + sufficient space for the application to show the text field and any associated context, so that + no more than half the screen is occupied by the IME. In fullscreen IME mode this is not an issue. </p> <h4>Handling different input types</h4> <p> - Android text fields allow you to set a specific input type, such as free -form text, numbers, - URLs, email addresses, and search strings. When you implement a new IME, -you need to - detect the input type of each field and provide the appropriate interface -for it. However, you - don't have to set up your IME to check that the user entered text -valid for the - input type; that's the responsibility of the application that owns the text -field. + Android text fields allow you to set a specific input type, such as free-form text, numbers, + URLs, email addresses, and search strings. When you implement a new IME, you need to detect + the input type of each field and provide the appropriate interface for it. However, you + don't have to set up your IME to check that the user entered text valid for the input type; + that's the responsibility of the application that owns the text field. </p> <p> - For example, here are screenshots of the interfaces that the Latin IME -provided with the + For example, here are screenshots of the interfaces that the Latin IME provided with the Android platform provides for text and phone number inputs: </p> <img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt="" height="142" id="figure2" /> @@ -273,18 +231,14 @@ provided with the <p> When an input field receives focus and your IME starts, the system calls {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) onStartInputView()}, - passing in an {@link android.view.inputmethod.EditorInfo} object that - contains details about the input type and other attributes of the text -field. In this object, - the {@link android.view.inputmethod.EditorInfo#inputType} field contains -the text field's input + passing in an {@link android.view.inputmethod.EditorInfo} object that contains details about + the input type and other attributes of the text field. In this object, the + {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input type. </p> <p> - The {@link android.view.inputmethod.EditorInfo#inputType} field is an -<code>int</code> - that contains bit patterns for various input type settings. To test it for -the text field's + The {@link android.view.inputmethod.EditorInfo#inputType} field is an <code>int</code> + that contains bit patterns for various input type settings. To test it for the text field's input type, mask it with the constant {@link android.text.InputType#TYPE_MASK_CLASS}, like this: </p> @@ -297,8 +251,7 @@ The input type bit pattern can have one of several values, including: <dl> <dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt> <dd> - A text field for entering numbers. As illustrated in the previous -screen shot, the + A text field for entering numbers. As illustrated in the previous screen shot, the Latin IME displays a number pad for fields of this type. </dd> <dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt> @@ -315,103 +268,86 @@ screen shot, the </dd> </dl> <p> - These constants are described in more detail in the reference documentation -for + These constants are described in more detail in the reference documentation for {@link android.text.InputType}. </p> <p> - The {@link android.view.inputmethod.EditorInfo#inputType} field can contain -other bits that + The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that indicate a variant of the text field type, such as: </p> <dl> <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt> <dd> - A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for -entering passwords. The + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The input method will display dingbats instead of the actual text. </dd> <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt> <dd> - A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for -entering web URLs and + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and other Uniform Resource Identifiers (URIs). </dd> <dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt> <dd> - A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for -entering text that the - application "auto-completes" from a dictionary, search, or other -facility. + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering text that the + application "auto-completes" from a dictionary, search, or other facility. </dd> </dl> <p> - Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with -the appropriate - constant when you test for these variants. The available mask constants are -listed in the + Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with the appropriate + constant when you test for these variants. The available mask constants are listed in the reference documentation for {@link android.text.InputType}. </p> <p class="caution"> - <strong>Caution:</strong> In your own IME, make sure you handle text -correctly when you send it - to a password field. Hide the password in your UI both in the input view -and in the candidates - view. Also remember that you shouldn't store passwords on a device. To -learn more, see the <a href="{@docRoot}guide/practices/security.html">Designing for Security</a> - guide. + <strong>Caution:</strong> In your own IME, make sure you handle text correctly when you send it + to a password field. Hide the password in your UI both in the input view and in the candidates + view. Also remember that you shouldn't store passwords on a device. To learn more, see the + <a href="{@docRoot}guide/practices/security.html">Designing for Security</a> guide. </p> <h2 id="SendText">Sending Text to the Application</h2> <p> - As the user inputs text with your IME, you can send text to the application -by - sending individual key events or by editing the text around the cursor in -the application's text + As the user inputs text with your IME, you can send text to the application by sending + individual key events or by editing the text around the cursor in the application's text field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} to deliver the text. To get this instance, call {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection InputMethodService.getCurrentInputConnection()}. </p> <h3 id="EditingCursor">Editing the text around the cursor</h3> <p> - When you're handling the editing of existing text in a text field, some of -the more useful + When you're handling the editing of existing text in a text field, some of the more useful methods in {@link android.view.inputmethod.BaseInputConnection} are: </p> <dl> <dt> {@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) getTextBeforeCursor()}</dt> <dd> - Returns a {@link java.lang.CharSequence} containing the number of -requested characters + Returns a {@link java.lang.CharSequence} containing the number of requested characters before the current cursor position. </dd> <dt> {@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) getTextAfterCursor()} </dt> <dd> - Returns a {@link java.lang.CharSequence} containing the number of -requested characters following the current cursor position. + Returns a {@link java.lang.CharSequence} containing the number of requested characters + following the current cursor position. </dd> <dt> {@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) deleteSurroundingText()} </dt> <dd> - Deletes the specified number of characters before and following the -current cursor + Deletes the specified number of characters before and following the current cursor position. </dd> <dt> {@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) commitText()} </dt> <dd> - Commit a {@link java.lang.CharSequence} to the text field and set a new -cursor + Commit a {@link java.lang.CharSequence} to the text field and set a new cursor position. </dd> </dl> <p> - For example, the following snippet shows how to replace the four characters to -the left of the cursor with the text "Hello!": + For example, the following snippet shows how to replace the four characters to the left of the + cursor with the text "Hello!": </p> <pre> InputConnection ic = getCurrentInputConnection(); @@ -424,12 +360,9 @@ the left of the cursor with the text "Hello!": </pre> <h3 id="ComposeThenCommit">Composing text before committing</h3> <p> - If your IME does text prediction or requires multiple steps to compose a -glyph or - word, you can show the progress in the text field until the user commits -the word, and then you - can replace the partial composition with the completed text. You may give -special treatment to + If your IME does text prediction or requires multiple steps to compose a glyph or + word, you can show the progress in the text field until the user commits the word, and then you + can replace the partial composition with the completed text. You may give special treatment to the text by adding a "span" to it when you pass it to {@link android.view.inputmethod.InputConnection#setComposingText setComposingText()}. </p> @@ -465,14 +398,10 @@ alt="" height="31" </p> <h3 id="HardwareKeyEvents">Intercepting hardware key events</h3> <p> - Even though the input method window doesn't have explicit focus, it -receives hardware key - events first and can choose to consume them or forward them along to the -application. For - example, you may want to consume the directional keys to navigate within -your UI for candidate - selection during composition. You may also want to trap the back key to -dismiss any popups + Even though the input method window doesn't have explicit focus, it receives hardware key + events first and can choose to consume them or forward them along to the application. For + example, you may want to consume the directional keys to navigate within your UI for candidate + selection during composition. You may also want to trap the back key to dismiss any popups originating from the input method window.</p> <p> To intercept hardware keys, override @@ -483,45 +412,36 @@ dismiss any popups SoftKeyboard</a> sample app for an example. </p> <p> - Remember to call the <code>super()</code> method for keys you don't want to -handle yourself. + Remember to call the <code>super()</code> method for keys you don't want to handle yourself. </p> <h2 id="IMESubTypes">Creating an IME Subtype</h2> <p> - Subtypes allow the IME to expose multiple input modes and languages -supported by an IME. A subtype can represent: + Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A + subtype can represent: </p> <ul> <li>A locale such as en_US or fr_FR</li> <li>An input mode such as voice, keyboard, or handwriting</li> <li> - Other input styles, forms, or properties specific to the IME, such as -10-key or qwerty + Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty keyboard layouts. </li> </ul> <p> - Basically, the mode can be any text such as "keyboard", "voice", and so -forth. A subtype can also expose a combination of these. + Basically, the mode can be any text such as "keyboard", "voice", and so forth. A subtype can + also expose a combination of these. </p> <p> - Subtype information is used for an IME switcher dialog that's available -from the notification - bar and also for IME settings. The information also allows the framework to -bring up a - specific subtype of an IME directly. When you build an IME, use the subtype -facility, because - it helps the user identify and switch between different IME languages and -modes. -</p> -<p> - You define subtypes in one of the input method's XML resource files, using -the - <code><subtype></code> element. The following snippet defines an IME -with two - subtypes: a keyboard subtype for the US English locale, and another -keyboard subtype for the + Subtype information is used for an IME switcher dialog that's available from the notification + bar and also for IME settings. The information also allows the framework to bring up a + specific subtype of an IME directly. When you build an IME, use the subtype facility, because + it helps the user identify and switch between different IME languages and modes. +</p> +<p> + You define subtypes in one of the input method's XML resource files, using the + <code><subtype></code> element. The following snippet defines an IME with two + subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the French language locale for France: </p> <pre> @@ -546,10 +466,8 @@ keyboard subtype for the /> </pre> <p> - To ensure that your subtypes are labeled correctly in the UI, use %s to get -a subtype label - that is the same as the subtype’s locale label. This is demonstrated in -the next two snippets. + To ensure that your subtypes are labeled correctly in the UI, use %s to get a subtype label + that is the same as the subtype’s locale label. This is demonstrated in the next two snippets. The first snippet shows part of the input method's XML file: </p> <pre> @@ -560,10 +478,8 @@ the next two snippets. android:imeSubtypeMode="keyboard" /> </pre> <p> - The next snippet is part of the IME's <code>strings.xml</code> file. The -string - resource <code>label_subtype_generic</code>, which is used by the input -method UI definition to + The next snippet is part of the IME's <code>strings.xml</code> file. The string + resource <code>label_subtype_generic</code>, which is used by the input method UI definition to set the subtype's label, is defined as: </p> <pre> @@ -575,12 +491,9 @@ method UI definition to </p> <h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3> <p> - The Android system manages all subtypes exposed by all IMEs. IME subtypes -are - treated as modes of the IME they belong to. In the notification bar, a user -can select an - available subtype for the currently-set IME, as shown in the following -screenshot: + The Android system manages all subtypes exposed by all IMEs. IME subtypes are + treated as modes of the IME they belong to. In the notification bar, a user can select an + available subtype for the currently-set IME, as shown in the following screenshot: </p> <img src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png" @@ -599,9 +512,9 @@ alt="" </p> <h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3> <p> - A user can control how subtypes are used in the “Language & input” -settings panel in the - System Settings area. In the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/"> + A user can control how subtypes are used in the “Language & input” settings panel in the + System Settings area. In the + <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/"> SoftKeyboard</a> sample app, the file <code>InputMethodSettingsFragment.java</code> contains an implementation that facilitates a subtype enabler in the IME settings. Refer to the <a href="https://android.googlesource.com/platform/development/+/master/samples/SoftKeyboard/"> @@ -617,15 +530,14 @@ alt="" <h2 id="Switching">Switching among IME Subtypes</h2> -<p>You can allow users to switch easily among multiple IME subtypes by providing -a switching key, such as the globe-shaped language icon, as part of the keyboard. Doing so greatly -improves the keyboard's usability, and can help avoid user frustration. +<p>You can allow users to switch easily among multiple IME subtypes by providing a switching key, +such as the globe-shaped language icon, as part of the keyboard. Doing so greatly improves the +keyboard's usability, and can help avoid user frustration. To enable such switching, perform the following steps:</p> <p> <ol> - <li>Declare <code>supportsSwitchingToNextInputMethod = "true"</code> in the -input method's XML resource files. Your declaration - should look similar to the following snippet: + <li>Declare <code>supportsSwitchingToNextInputMethod = "true"</code> in the input method's XML + resource files. Your declaration should look similar to the following snippet: <pre> <input-method xmlns:android="http://schemas.android.com/apk/res/android" android:settingsActivity="com.example.softkeyboard.Settings" @@ -646,8 +558,7 @@ input method's XML resource files. Your declaration <strong>Caution:</strong> Prior to Android 5.0 (API level 21), {@link android.view.inputmethod.InputMethodManager#switchToNextInputMethod switchToNextInputMethod()} is not aware of the <code>supportsSwitchingToNextInputMethod</code> attribute. If the user switches -into an IME without a switching key, he or she may get stuck in that IME, unable to switch out of it -easily.</p> +into an IME without a switching key, he or she may get stuck in that IME, unable to switch out of it easily.</p> <p> @@ -662,31 +573,23 @@ easily.</p> Provide a way for users to set options directly from the IME's UI. </li> <li> - Because multiple IMEs may be installed on the device, provide a way for the -user to switch to a + Because multiple IMEs may be installed on the device, provide a way for the user to switch to a different IME directly from the input method UI. </li> <li> - Bring up the IME's UI quickly. Preload or load on demand any large -resources so that users - see the IME as soon as they tap on a text field. Cache resources and views -for subsequent + Bring up the IME's UI quickly. Preload or load on demand any large resources so that users + see the IME as soon as they tap on a text field. Cache resources and views for subsequent invocations of the input method. </li> <li> - Conversely, you should release large memory allocations soon after the -input method window is - hidden, so that applications can have sufficient memory to run. Consider -using a delayed message - to release resources if the IME is in a hidden state for a few seconds. + Conversely, you should release large memory allocations soon after the input method window is + hidden, so that applications can have sufficient memory to run. Consider using a delayed + message to release resources if the IME is in a hidden state for a few seconds. </li> <li> - Make sure that users can enter as many characters as possible for the -language or locale - associated with the IME. Remember that users may use punctuation in -passwords or user - names, so your IME has to provide many different characters to allow users -to enter a + Make sure that users can enter as many characters as possible for the language or locale + associated with the IME. Remember that users may use punctuation in passwords or user + names, so your IME has to provide many different characters to allow users to enter a password and get access to the device. </li> </ul>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index a61696a..d972c47 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -1427,7 +1427,7 @@ href="#ActionView">action views</a>.</dd> <p>Here's an example that defines a custom theme for an activity, {@code CustomActivityTheme}, that includes several styles to customize the action bar.</p> -<p>Notice that there are two version for each action bar style property. The first one +<p>Notice that there are two versions for each action bar style property. The first one includes the {@code android:} prefix on the property name to support API levels 11 and higher that include these properties in the framework. The second version does <em>not</em> include the {@code android:} prefix and is for older versions of the platform, on which |