drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "add compatible-screens manifest element and update supports-screens element with resizeable attribute" into honeycomb

Browse Source
This commit is contained in:
Scott Main
2011-02-14 11:44:10 -08:00
committed by Android (Google) Code Review
parent 55ee1d6698 1b6dd05927
commit 2e80568263
4 changed files with 263 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/html/guide/appendix/market-filters.jd
View File

@ -5,23 +5,25 @@ page.title=Market Filters
<div id="qv">
<h2>Quickview</h2>
<ul> <li>Android Market applies filters to that let you control whether your app is shown to a
user who is browing or searching for apps.</li>
<li>Filtering is determined by elements in an app's manifest file,
aspects of the device being used, and other factors.</li> </ul>
<ul>
<li>Android Market applies filters that control which Android-powered devices can access your
application on Market.</li>
<li>Filtering is determined by comparing device configurations that you declare in you app's
manifest file to the configurations defined by the device, as well as other factors.</li> </ul>
<h2>In this document</h2>
<ol> <li><a href="#how-filters-work">How Filters Work in Android Market</a></li>
<li><a href="#manifest-filters">Filtering based on Manifest File Elements</a></li>
<li><a href="#other-filters">Other Filters</a></li>
<li><a href="#advanced-filters">Advanced Manifest Filters</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a
href="{@docRoot}guide/practices/compatibility.html">Compatibility</a></li>
<li style="margin-top:2px;"><code><a
href="{@docRoot}guide/practices/compatibility.html">Android Compatibility</a></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">&lt;supports-screens&gt;</a></code></li>
<li><code><a
href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">&lt;uses-configuration&gt;</a></code></li>
@ -42,36 +44,40 @@ publishing your app on Android Market?</p> <a id="publish-link"
href="http://market.android.com/publish">Go to Android Market &raquo;</a> </div>
</div>
</div> </div>
</div>
</div>
<p>When a user searches or browses in Android Market, the results are filtered, and
some applications might not be visible. For example, if an application requires a
<p>When a user searches or browses in Android Market, the results are filtered based on which
applications are compatible with the user's device. For example, if an application requires a
trackball (as specified in the manifest file), then Android Market will not show
the app on any device that does not have a trackball.</p> <p>The manifest file and
the device's hardware and features are only part of how applications are filtered
&#8212; filtering also depends on the country and carrier, the presence or absence
of a SIM card, and other factors. </p>
the app on any device that does not have a trackball.</p>
<p>The manifest file and the device's hardware and features are only part of how applications are
filtered&mdash;filtering might also depend on the country and carrier, the presence or absence of a
SIM card, and other factors. </p>
<p>Changes to the Android Market filters are independent of changes
to the Android platform itself. This document will be updated periodically to reflect
any changes that occur. </p>
any changes that affect the way Android Market filters applications.</p>
<h2 id="how-filters-work">How Filters Work in Android Market</h2>
<p>Android Market uses the filter restrictions described below to determine
whether to show your application to a user who is browsing or searching for
applications on a given device. When determining whether to display your app,
applications on an Android-powered device. When determining whether to display your app,
Market checks the device's hardware and software capabilities, as well as it's
carrier, location, and other characteristics. It then compares those against the
restrictions and dependencies expressed by the application itself, in its
manifest, <code>.apk</code>, and publishing details. If the application is
manifest file and publishing details. If the application is
compatible with the device according to the filter rules, Market displays the
application to the user. Otherwise, Market hides your application from search
results and category browsing. </p>
<p>You can use the filters described below to control whether Market shows or
hides your application to users. You can request any combination of the
available filters for your app &#8212; for example, you could set a
hides your application to users. You can use any combination of the
available filters for your app&mdash;for example, you can set a
<code>minSdkVersion</code> requirement of <code>"4"</code> and set
<code>smallScreens="false"</code> in the app, then when uploading the app to
Market you could target European countries (carriers) only. Android Market's
@ -92,16 +98,18 @@ makes the app invisible to the user, the user will not see that an upgrade is
available. </li>
</ul>
<h2 id="manifest-filters">Filtering based on Manifest Elements</h2>
<p>Most Market filters are triggered by elements within an application's
manifest file, <a
href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a>,
although not everything in the manifest file can trigger filtering. The
table below lists the manifest elements that you can use to trigger Android
Market filtering, and explains how the filtering works.</p>
although not everything in the manifest file can trigger filtering.
Table 1 lists the manifest elements that you should use to trigger Android
Market filtering, and explains how the filtering for each element works.</p>
<p class="table-caption"><strong>Table 1.</strong> Manifest elements that
<p id="table1" class="table-caption"><strong>Table 1.</strong> Manifest elements that
trigger filtering on Market.</p>
<table>
<tr>
@ -313,10 +321,13 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:m
</tr>
</table>
<h2 id="other-filters">Other Filters</h2>
<p>Android Market uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p>
<p class="table-caption"><strong>Table 2.</strong> Application and publishing characteristics that affect filtering on Market.</p>
<p id="table2" class="table-caption"><strong>Table 2.</strong> Application and publishing
characteristics that affect filtering on Market.</p>
<table> <tr>
<th>Filter Name</th> <th>How It Works</th> </tr>
@ -351,3 +362,38 @@ country (as determined by SIM carrier) in which paid apps are available.</p></td
developer devices or unreleased devices.</p></td> </tr> </table>
<h2 id="advanced-filters">Advanced Manifest Filters</h2>
<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Android Market can also
filter applications based on the advanced manifest elements in table 3.</p>
<p>These manifest elements and the filtering they trigger are for exceptional use-cases
only. They are designed for some types of high-performance games and similar applications that
require strict controls on application distribution. <strong>Most applications should never use
these filters</strong>.</p>
<p id="table3" class="table-caption"><strong>Table 3.</strong> Advanced manifest elements for
Android Market filtering.</p>
<table>
<tr><th>Manifest Element</th><th>Summary</th></tr>
<tr>
<td><nobr><a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
&lt;compatible-screens&gt;}</a></nobr></td>
<td>
<p>Android Market filters the application if the device screen size and density does not match
any of the screen configurations (declared by a {@code &lt;screen&gt;} element) in the {@code
&lt;compatible-screens&gt;} element.</p>
<p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use
this manifest element</strong>. Using this element can dramatically
reduce the potential user base for your application, by excluding all combinations of screen size
and density that you have not listed. You should instead use the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> manifest element (described above in <a href="#table1">table
1</a>) to enable screen compatibility mode for screen configurations you have not accounted for
with alternative resources.</p>
</td>
</tr>
</table>

1
docs/html/guide/guide_toc.cs
View File

@ -207,6 +207,7 @@
<li><a href="<?cs var:toroot ?>guide/topics/manifest/activity-alias-element.html">&lt;activity-alias&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/application-element.html">&lt;application&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/category-element.html">&lt;category&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/compatible-screens-element.html">&lt;compatible-screens&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/data-element.html">&lt;data&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/grant-uri-permission-element.html">&lt;grant-uri-permission&gt;</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/manifest/instrumentation-element.html">&lt;instrumentation&gt;</a></li>

108
docs/html/guide/topics/manifest/compatible-screens-element.jd Normal file
View File

@ -0,0 +1,108 @@
page.title=&lt;compatible-screens&gt;
@jd:body
<dl class="xml">
<dt>syntax:</dt>
<dd>
<pre>
&lt;<a href="#compatible-screens">compatible-screens</a>&gt;
&lt;<a href="#screen">screen</a> android:<a href="#screenSize">screenSize</a>=["small" | "normal" | "large" | "xlarge"]
android:<a href="#screenDensity">screenDensity</a>=["ldpi" | "mdpi" | "hdpi" | "xhdpi"] /&gt;
...
&lt;/compatible-screens&gt;
</pre>
</dd>
<dt>contained in:</dt>
<dd><code><a
href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
<dt>description:</dt>
<dd>Specifies each screen configuration with which the application is compatible. Only one instance
of the {@code &lt;compatible-screens&gt;} element is allowed in the manifest, but it can
contain multiple <code>&lt;screen&gt;</code> elements. Each <code>&lt;screen&gt;</code> element
specifies a specific screen size-density combination with which the application is compatible.
<p>The Android system <em>does not</em> read the {@code &lt;compatible-screens&gt;} manifest
element (neither at install-time nor at runtime). This element is informational only and may be used
by external services (such as Android Market) to better understand the application's compatibility
with specific screen configurations and enable filtering for users. Any screen configuration that is
<em>not</em> declared in this element is a screen with which the application is <em>not</em>
compatible. Thus, external services (such as Android Market) should not provide the application to
devices with such screens.</p>
<p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use this manifest
element</strong>. Using this element can dramatically reduce the potential user base for your
application, by not allowing users to install your application if they have a device with a screen
configuration that you have not listed. You should use it only as a last resort, when the
application absolutely does not work with all screen configurations. Instead of using this element,
you should follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting
Multiple Screens</a>, in order to provide complete support for multiple screens, by adding
alternative resources for different screen sizes and densities.</p>
<p>If you want to set only a minimum screen <em>size</em> for your your application, then you
should use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element. For example, if you want your application to be available
only for <em>large</em> and <em>xlarge</em> screen devices, the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element allows you to declare that your application does not
support <em>small</em> and <em>normal</em> screen sizes. External services (such as Android
Market) will filter your application accordingly. You can also use the <a
href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
&lt;supports-screens&gt;}</a> element to declare whether the system should resize your
application for different screen sizes.</p>
<p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>
document for more information about how Android Market filters applications using this and
other manifest elements.</p>
</dd>
<dt>child elements:</dt>
<dd>
<dl class="tag-list">
<dt id="screen">{@code &lt;screen&gt;}</dt>
<dd>Specifies a single screen configuration with which the application is compatible.
<p>At least one instance of this element must be placed inside the {@code
&lt;compatible-screens&gt;} element. This element <em>must include both</em> the {@code
android:screenSize} and {@code android:screenDensity} attributes (if you do not declare both
attributes, then the element is ignored).</p>
<p class="caps">attributes:</p>
<dl class="atn-list">
<dt id="screenSize"><code>android:screenSize</code></dt>
<dd><b>Required.</b> Specifies the screen size for this screen configuration.
<p>Accepted values:</p>
<ul>
<li>{@code small}</li>
<li>{@code normal}</li>
<li>{@code large}</li>
<li>{@code xlarge}</li>
</ul>
<p>For information about the different screen sizes, see <a
href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p>
</dd>
<dt id="screenDensity"><code>android:screenDensity</code></dt>
<dd><b>Required.</b> Specifies the screen density for this screen configuration.
<p>Accepted values:</p>
<ul>
<li>{@code ldpi}</li>
<li>{@code mdpi}</li>
<li>{@code hdpi}</li>
<li>{@code xhdpi}</li>
</ul>
<p>For information about the different screen densities, see <a
href="{@docRoot}guide/practices/screens_support.html#range">Supporting Multiple Screens</a>.</p>
</dd>
</dl>
</dd>
</dl>
</dd>
<dt>introduced in:</dt>
<dd>API Level 9</dd>
<dt>see also:</dt>
<dd><a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd>
<dd><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></dd>
</dl>

119
docs/html/guide/topics/manifest/supports-screens-element.jd
View File

@ -6,7 +6,8 @@ page.title=&lt;supports-screens&gt;
<dt>syntax:</dt>
<dd>
<pre class="stx">
&lt;supports-screens android:<a href="#small">smallScreens</a>=["true" | "false"]
&lt;supports-screens android:<a href="#resizeable">resizeable</a>=["true" | "false"]
android:<a href="#small">smallScreens</a>=["true" | "false"]
android:<a href="#normal">normalScreens</a>=["true" | "false"]
android:<a href="#large">largeScreens</a>=["true" | "false"]
android:<a href="#xlarge">xlargeScreens</a>=["true" | "false"]
@ -19,17 +20,33 @@ page.title=&lt;supports-screens&gt;
<dt>description:</dt>
<dd>Lets you specify the screen dimensions the
application supports. By default a modern application (using API Level 4 or higher) supports all
screen sizes and must explicitly disable certain screen sizes here;
older applications are assumed to support only the "normal"
screen size. Note that screen size is a separate axis from
density. Screen size is determined as the available pixels to an application
after density scaling has been applied.
application supports. By default, a modern application (using API Level 4 or higher) supports all
screen sizes; older applications are assumed to support only the "normal" screen size. Screen
size is determined as the available pixels to an application after density scaling has been
applied. (Note that screen size is a separate axis from screen density.)
<p>An application "supports" a given screen size if it fills the entire screen and works as
expected. By default, the system will resize your application to fill the screen, if you have set
either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
targetSdkVersion}</a> to {@code "4"} or higher. Resizing works well for most applications and
you don't have to do any extra work to make your application work on larger screens.</p>
<p>In addition to allowing the system to resize your application, you can add additional support
for different screen sizes by providing <a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
layout resources</a> for different sizes. For instance, you might want to modify the layout
of an activity when it is on a tablet or similar device that has an <em>xlarge</em> screen.</p>
<p>If your application does not support <em>large</em> or <em>xlarge</em> screens, then you should
declare that it is not resizeable by setting <a href="#resizeable">{@code android:resizeable}</a> to
{@code "false"}, so that the system will not resize your application on larger screens.</p>
<p>If your application does not support <em>small</em> screens, then
there isn't much the system can do to make the application work well on a smaller screen, so
external services (such as Android Market) should not allow users to install the application on such
screens.</p>
<p>Based on the target device screen density, the Android
framework will scale down assets by a factor of 0.75 (low dpi screens)
or scale them up by a factor of 1.5 (high dpi screens).
The screen density is expressed as dots-per-inch (dpi).</p>
<p>For more information, see
<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
@ -38,16 +55,40 @@ The screen density is expressed as dots-per-inch (dpi).</p>
<dt>attributes:</dt>
<dd>
<dl class="attr"><dt><a name="small"></a>{@code android:smallScreens}</dt>
<dl class="attr">
<dt><a name="resizeable"></a>{@code android:resizeable}</dt>
<dd>Indicates whether the application is resizeable for different screen sizes. This attribute is
true, by default, if you have set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher. Otherwise, it is false by default. If set false, the system will not resize
your application when run on <em>large</em> or <em>xlarge</em> screens. Instead, the
application appears in a "postage stamp" that equals the <em>normal</em> screen size that your
application does support. This is less than an ideal experience for users, because the
application appears smaller than the available screen, but it might help your application run
normally if it were designed only for the <em>normal</em> screen size and some behaviors do not work
when resized.</p>
<p>To provide the best experience on all screen sizes, you should allow resizing and, if your
application does not work well on larger screens, follow the guide to <a
href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to enable
additional screen support.</p>
</dd>
<dt><a name="small"></a>{@code android:smallScreens}</dt>
<dd>Indicates whether the application supports smaller screen form-factors.
A small screen is defined as one with a smaller aspect ratio than
the "normal" (traditional HVGA) screen. An application that does
not support small screens <em>will not be available</em> for
small screen devices, because there is little the platform can do
to make such an application work on a smaller screen. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
small screen devices from external services (such as Android Market), because there is little
the platform can do
to make such an application work on a smaller screen. If the application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
</dd>
<dt><a name="normal"></a>{@code android:normalScreens}</dt>
@ -61,38 +102,44 @@ the default value for this is "true", any value less than "4" results in this se
<dt><a name="large"></a>{@code android:largeScreens}</dt>
<dd>Indicates whether the application supports larger screen form-factors.
A large screen is defined as a screen that is significantly larger
than a "normal" phone screen, and thus may require some special care
on the application's part to make good use of it. An application that
does not support large screens (declares this "false")&mdash;but does support "normal" or
"small" screens&mdash;will be placed as a "postage stamp" on
a large screen, so that it retains the dimensions it was originally
designed for. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
than a "normal" phone screen, and thus might require some special care
on the application's part to make good use of it, though it may rely on resizing by the
system to fill the screen. If the application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
</dd>
<dt><a name="xlarge"></a>{@code android:xlargeScreens}</dt>
<dd>Indicates whether the application supports extra large screen form-factors.
An xlarge screen is defined as a screen that is significantly larger
than a "large" screen, such as a tablet (or something larger) and may require special care
on the application's part to make good use of it. An application that
does not support xlarge screens (declares this "false")&mdash;but does support "large",
"normal", or "small" screens&mdash;will be placed as a "postage stamp" on
an xlarge screen, so that it retains the dimensions it was originally
designed for. If the application has set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code &lt;uses-sdk&gt;}</a> element's
{@code android:minSdkVersion} or {@code android:targetSdkVersion} attribute to "4" or higher,
the default value for this is "true", any value less than "4" results in this set to "false".
on the application's part to make good use of it, though it may rely on resizing by the
system to fill the screen. If the application has set either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}, any value less than {@code "4"} results in this set to
{@code "false"}.
<p>This attribute was introduced in API Level 9.</p>
</dd>
<dt><a name="any"></a>{@code android:anyDensity}</dt>
<dd>Indicates whether the application includes resources to accommodate any screen
density. Older applications (before API Level 4) are assumed unable to
accomodate all densities and this is "false" by default. Applications using
API Level 4 or higher are assumed able to and this is "true" by default.
accomodate all densities and this is {@code "false"} by default. If the application has set
either <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> or <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to
{@code "4"} or higher,
the default value for this is {@code "true"}. Otherwise, it is {@code "false"}.
You can explicitly supply your abilities here.
<p>Based on the "standard" device screen density (medium dpi), the Android framework will scale
down application assets by a factor of 0.75 (low dpi screens) or scale them up by a factor of 1.5
(high dpi screens), when you don't provide alternative resources for a specifc screen density. The
screen density is expressed as dots-per-inch (dpi).</p>
</dd>