xref: /frameworks/base/docs/html/guide/topics/manifest/compatible-screens-element.jd

page.title=<compatible-screens>
parent.title=The AndroidManifest.xml File
parent.link=manifest-intro.html
@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 itemprop="description">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 Google Play) 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 Google Play) 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 specific 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> to
provide scalable support for multiple screens using alternative layouts and bitmaps
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 Google
Play) 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}google/play/filters.html">Filters on Google Play</a>
document for more information about how Google Play 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 class="note"><strong>Note:</strong> This attribute currently does not accept
          {@code xxhdpi} as a valid value, but you can instead specify {@code 480}
          as the value, which is the approximate threshold for xhdpi screens.</p>

          <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>example</dt>
<dd>
<p>If your application is compatible with only small and normal screens, regardless
of screen density, then you must specify eight different {@code &lt;screen&gt;} elements,
because each screen size has four different density configurations. You must declare each one of
these; any combination of size and density that you do <em>not</em> specify is considered a screen
configuration with which your application is <em>not</em> compatible. Here's what the manifest
entry looks like if your application is compatible with only small and normal screens:</p>

<pre>
&lt;manifest ... >
    ...
    &lt;compatible-screens>
        &lt;!-- all small size screens -->
        &lt;screen android:screenSize="small" android:screenDensity="ldpi" />
        &lt;screen android:screenSize="small" android:screenDensity="mdpi" />
        &lt;screen android:screenSize="small" android:screenDensity="hdpi" />
        &lt;screen android:screenSize="small" android:screenDensity="xhdpi" />
        &lt;!-- all normal size screens -->
        &lt;screen android:screenSize="normal" android:screenDensity="ldpi" />
        &lt;screen android:screenSize="normal" android:screenDensity="mdpi" />
        &lt;screen android:screenSize="normal" android:screenDensity="hdpi" />
        &lt;screen android:screenSize="normal" android:screenDensity="xhdpi" />
    &lt;/compatible-screens>
    &lt;application ... >
        ...
    &lt;application>
&lt;/manifest>
</pre>
</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}google/play/filters.html">Filters on Google Play</a></dd>
</dl>