cherrypick from hc-mr2 Change-Id: Ia38b7c364a3a655faa5cc5d13e19c2dbbb12eee5

<dt><a name="screen"></a>{@code android:screenOrientation}</dt>

<dd>The orientation of the activity's display on the device. 

The value can be any one of the following strings:

<p>The value can be any one of the following strings:</p>

<table>

<tr>

distinction, the system chooses the orientation using the same policy as for the "{@code

unspecified}" setting.</td>

</tr>

</table></dd>

</table>

<p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values,

it is considered a hard requirement for the orientation in which the activity runs. As such,

the value you declare enables filtering by services such as Android Market so your application is

available only to devices that support the orientation required by your activities. For

example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or

{@code "sensorLandscape"}, then your application will be available only to devices that support

landscape orientation. However, you should also explicitly declare that

your application requires either portrait or landscape orientation with the <a

href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code &lt;uses-feature&gt;}</a>

element. For example, <code>&lt;uses-feature

android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior

provided by Android Market (and other services that support it) and the platform itself does not

control whether your app can be installed when a device supports only certain orientations.</p>

</dd>

<dt><a name="state"></a>{@code android:stateNotNeeded}</dt>

<dd>Whether or not the activity can be killed and successfully restarted 

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>

<p>For some features, there may exist a specfic attribute that allows you to define

<p>For some features, there may exist a specific attribute that allows you to define

a version of the feature, such as the version of Open GL used (declared with

<a href="#glEsVersion"><code>glEsVersion</code></a>). Other features that either do or do not

exist for a device, such as a camera, are declared using the

it (<code>"true"</code>), or whether the application prefers to use the feature

if available, but is designed to run without it (<code>"false"</code>).</p>

<p>Android Market handles explictly declared features in this way: </p>

<p>Android Market handles explicitly declared features in this way: </p>

<ul>

<li>If a feature is explicitly declared as being required, Android Market adds

<pre>&lt;uses-feature android:name="android.hardware.camera" android:required="true" /&gt;</pre></li>

<li>If a feature is explicitly declared as <em>not</em> being required, Android

Market <em>does not</em> add the feature to the list of required features. For

that reason, an explicity declared non-required feature is never considered when

that reason, an explicitly declared non-required feature is never considered when

filtering the application. Even if the device does not provide the declared

feature, Android Market will still consider the application compatible with the

device and will show it to the user, unless other filtering rules apply. For

  <td>The application uses the device's proximity sensor.</td>

  <td></td>

</tr>

<tr>

  <td rowspan="2">Screen</td>

  <td><code>android.hardware.screen.landscape</code></td>

  <td>The application requires landscape orientation.</td>

  <td rowspan="2">

     <p>For example, if your app requires portrait orientation, you should declare

<code>&lt;uses-feature android:name="android.hardware.screen.portrait"/></code> so that only devices

that support portrait orientation (whether always or by user choice) can install your app. If your

application <em>supports</em> both orientations, then you don't need to declare either.</p>

    <p>Both orientations are assumed <em>not required</em>, by default, so your app may be installed

on devices that support one or both orientations. However, if any of your activities request that

they run in a specific orientation, using the <a

href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code

android:screenOrientation}</a> attribute, then this also declares that the application requires that

orientation. For example, if you declare <a

href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code

android:screenOrientation}</a> with either {@code "landscape"}, {@code "reverseLandscape"}, or

{@code "sensorLandscape"}, then your application will be available only to devices that support

landscape orientation. As a best practice, you should still declare your requirement for this

orientation using a {@code <uses-feature>} element. If you declare an orientation for your

activity using <a href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code

android:screenOrientation}</a>, but don't actually <em>require</em> it, you can disable the

requirement by declaring the orientation with a {@code <uses-feature>} element and include

{@code android:required="false"}.</p>

    <p>For backwards compatibility, any device running a platform version that supports only API

level 12 or lower is assumed to support both landscape and portrait.</p>

  </td>

</tr>

<tr>

  <td><code>android.hardware.screen.portrait</code></td>

  <td>The application requires portrait orientation.</td>

</tr>

<tr>

  <td rowspan="3">Telephony</td>

  <td><code>android.hardware.telephony</code></td>

</tr>

<tr>

  <td rowspan="5">Touchscreen</td>

  <td rowspan="7">Touchscreen</td>

  <td><code>android.hardware.faketouch</code></td>

  <td>The application uses basic touch interaction events, such as "click down", "click

up", and drag.</td>

  <td>When declared, this indicates that the application is compatible with a device that offers an

emulated touchscreen ("fake touch" interface), or better. A device that offers a fake touch 

interface provides a user input system that emulates a subset of touchscreen capabilities. For

example, a mouse or remote control that drives an on-screen cursor provides a fake touch interface.

If your application requires only basic point and click interaction, you should declare this

feature. Because this is the minimum level of touch interaction, your app will also be compatible

with devices that offer more complex touch interfaces.

  <td><p>When declared as required, this indicates that the application is compatible with a device

only if it offers an emulated touchscreen ("fake touch" interface), or better. A device that offers

a fake touch interface provides a user input system that emulates a subset of touchscreen

capabilities. For example, a mouse or remote control that drives an on-screen cursor provides a fake

touch interface. If your application requires basic point and click interaction (in other

words, it won't work with <em>only</em> a d-pad controller), you should declare this feature.

Because this is the minimum level of touch interaction, your app will also be compatible with

devices that offer more complex touch interfaces.</p>

  <p class="note"><strong>Note:</strong> Because applications require the {@code

android.hardware.touchscreen} feature by default, if you want your application to be available to

devices that provide a fake touch interface, you must also explicitly declare that a touch screen is

android:name="android.hardware.touchscreen" <strong>android:required="false"</strong>

/&gt;}</p></td>

</tr>

<tr>

  <td><code>android.hardware.faketouch.multitouch.distinct</code></td>

  <td>The application performs distinct tracking of two or more "fingers" on a fake touch

interface. This is a superset of the faketouch feature.</td>

  <td><p>When declared as required, this indicates that the application is compatible with a device

only if it supports touch emulation for events that supports distinct tracking of two or more

fingers, or better.</p>

  <p>Unlike the distinct multitouch defined by {@code

android.hardware.touchscreen.multitouch.distinct}, input devices that support distinct multi-touch

with a fake touch interface will not support all two-finger gestures, because the input is

being transformed to cursor movement on the screen. That is, single finger gestures on such a device

move a cursor; two-finger swipes will result in single-finger touch events; other two-finger

gestures will result in the corresponding two-finger touch event. An example device that supports

distinct multi-touch with a fake touch interface is one that provides a trackpad for cursor movement

which also supports two or more fingers.</p></td>

</tr>

<tr>

  <td><code>android.hardware.faketouch.multitouch.jazzhand</code></td>

  <td>The application performs distinct tracking of five or more "fingers" on a fake touch

interface. This is a superset of the faketouch feature.</td>

  <td><p>When declared as required, this indicates that the application is compatible with a device

only if it supports touch emulation for events that supports distinct tracking of five or more

fingers.</p>

  <p>Unlike the distinct multitouch defined by {@code

android.hardware.touchscreen.multitouch.jazzhand}, input devices that support jazzhand multi-touch

with a fake touch interface will not support all five-finger gestures, because the input is being

transformed to cursor movement on the screen. That is, single finger gestures on such a device move

a cursor; multi-finger gestures will result in single-finger touch events; other multi-finger

gestures will result in the corresponding multi-finger touch event. An example device that supports

distinct multi-touch with a fake touch interface is one that provides a trackpad for cursor movement

which also supports five or more fingers.</p></td>

</tr>

<tr>

  <td><code>android.hardware.touchscreen</code></td>

  <td>The application uses touchscreen capabilities for gestures that are more interactive

than basic touch events, such as a fling. This is a superset of the faketouch features.</td>

  <td>By default, your application requires this. As such, your application is

<em>not</em> available to devices that provide only an emulated touch interface ("fake touch"), by

default. If you want your application available to devices that provide a fake touch interface,

you must explicitly declare that a touch screen is not required, by

declaring {@code android.hardware.touchscreen} with {@code android:required="false"}. You should

do so even if your application uses&mdash;but does not <em>require</em>&mdash;a real touch screen

interface.

<p>If your application <em>does require</em> a basic touch interface (in order to perform touch

than basic touch events, such as a fling. This is a superset of the basic faketouch feature.</td>

  <td><p>By default, your application requires this. As such, your application is <em>not</em>

available to devices that provide only an emulated touch interface ("fake touch"), by default. If

you want your application available to devices that provide a fake touch interface (or even devices

that provide only a d-pad controller), you must explicitly declare that a touch screen is not

required, by declaring {@code android.hardware.touchscreen} with {@code android:required="false"}.

You should do so even if your application uses&mdash;but does not <em>require</em>&mdash;a real

touch screen interface.</p>

<p>If your application <em>does require</em> a touch interface (in order to perform touch

gestures such as a fling), then you don't need to do anything, because this is required by default.

However, it's best if you explicitly declare all features used by your application, so you should

still declare this if your app uses it.</p>

  <td><code>android.hardware.touchscreen.multitouch</code></td>

  <td>The application uses basic two-point multitouch capabilities on the device

screen, such as for pinch gestures, but does not need to track touches independently. This

is a superset of touchscreen features.</td>

is a superset of touchscreen feature.</td>

  <td>This implicitly declares the <code>android.hardware.touchscreen</code> parent feature, unless

declared with <code>android:required="false"</code>. </td>

</tr>

  <td><code>android.hardware.touchscreen.multitouch.distinct</code></td>

  <td>Subfeature. The application uses advanced multipoint multitouch

capabilities on the device screen, such as for tracking two or more points fully

independently. This is a superset of multitouch features.</td>

independently. This is a superset of multitouch feature.</td>

  <td rowspan="2">This implicitly declares the <code>android.hardware.touchscreen.multitouch</code>

parent feature, unless declared with <code>android:required="false"</code>. </td>

</tr>

  <td><code>android.hardware.touchscreen.multitouch.jazzhand</code></td>

  <td>The application uses advanced multipoint multitouch

capabilities on the device screen, for tracking up to five points fully

independently. This is a superset of distinct multitouch features.</td>

independently. This is a superset of distinct multitouch feature.</td>

</tr>

<tr>

<p>A typical application that functions properly in both landscape and portrait orientations would not normally need to declare an orientation requirement. Rather, an application designed primarily for one orientation, such as an app designed for a television, could declare one of the constants to ensure that it isn't available to devices that don't provide that orientation.</p>

<p>If the application is targeting API level 12 or lower, the platform assumes that if app has not specified whether it requires portrait or landscape, both orientations are required.</p>

<p>If any of activities declared in the manifest request that they run in a specific orientation,

using the <a href="{@docRoot}guide/topics/manifest/activity-element.html#screen">{@code

android:screenOrientation}</a> attribute, then this also declares that the application

requires that orientation.</p>

</li>

<li>Other feature constants