Merge "docs: site mipmap folder updates" into lmp-docs

        <em>finished_asset</em>.png

    drawable-xxhdpi/...

        <em>finished_asset</em>.png

    mipmap-ldpi/...

        <em>finished_launcher_asset</em>.png

    mipmap-mdpi/...

        <em>finished_launcher_asset</em>.png

    mipmap-hdpi/...

        <em>finished_launcher_asset</em>.png

    mipmap-xhdpi/...

        <em>finished_launcher_asset</em>.png

    mipmap-xxhdpi/...

        <em>finished_launcher_asset</em>.png

    mipmap-xxxhdpi/...

        <em>finished_launcher_asset</em>.png

</pre>

<p>For more information about how to save resources in the application project,

see <a href="{@docRoot}guide/topics/resources/providing-resources.html">Providing Resources</a>.

</p>

<p> For more information about using the mipmap folders, see

<a href="{@docRoot}tools/project/index.html#mipmap">Managing Projects Overview</a>.</p>

<h3 id="xxxhdpi-launcher">Provide an xxx-high-density launcher icon</h3>

<p>Some devices scale-up the launcher icon by as much as 25%. For example, if your highest density

launcher icon image is already extra-extra-high density, the scaling process will make it appear

less crisp. So you should provide a higher density launcher icon in the <code>drawable-xxxhdpi

less crisp. So you should provide a higher density launcher icon in the <code>mipmap-xxxhdpi

</code> directory, which the system uses instead of scaling up a smaller version of the icon.</p>

<p class="note"><strong>Note:</strong> the <code>drawable-xxxhdpi</code> qualifier is necessary only

to provide a launcher icon that can appear larger than usual on an xxhdpi device. You do not need to

provide xxxhdpi assets for all your app's images.</p>

<p class="note"><strong>Note:</strong> The <code>mipmap-xxxhdpi</code> qualifier is necessary

only to provide a launcher icon that can appear larger than usual on an xxhdpi device. It is best

practice to place all your launcher icons in the <code>res/mipmap-[density]/</code> folders. This

enables your app to display launcher icons that have a higher density than the device, without

scaling up a lower density version of the icon. You do not need to provide xxxhdpi assets for all

your app's images.</p>

<p>See <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> for

more information.</p>

page.title=Supporting Multiple Screens

page.metaDescription=Nanaging UIs for the best display on multiple screen sizes.

page.metaDescription=Managing UIs for the best display on multiple screen sizes.

meta.tags="multiple screens"

@jd:body

<code>hdpi</code> (high), <code>xhdpi</code> extra-high), <code>xxhdpi</code>

(extra-extra-high), and <code>xxxhdpi</code> (extra-extra-extra-high). For example, bitmaps

for high-density screens should go in {@code drawable-hdpi/}.</p>

    <p class="note" id="xxxhdpi-note"><strong>Note:</strong>  the <code>drawable-xxxhdpi</code>

    <p class="note" id="xxxhdpi-note"><strong>Note:</strong>  The <code>mipmap-xxxhdpi</code>

qualifier is necessary only to provide a launcher icon that can appear larger than usual on an

xxhdpi device. You do not need to provide xxxhdpi assets for all your app's images.</p>

    <p>Some devices scale-up the launcher icon by as much as 25%. For example, if your highest

density launcher icon image is already extra-extra-high-density, the scaling process will make it

appear less crisp. So you should provide a higher density launcher icon in the

<code>drawable-xxxhdpi</code> directory, which the system uses instead of scaling up a smaller

<code>mipmap-xxxhdpi</code> directory, which the system uses instead of scaling up a smaller

version of the icon.</p>

    <p>See <a href="{@docRoot}design/style/iconography.html#xxxhdpi-launcher">Provide an

xxx-high-density launcher icon</a> for more information. You should not use the

  </li>

</ul>

<p class="note"><strong>Note:</strong> Place all your launcher icons in the

<code>res/mipmap-[density]/</code> folders, rather than the <code>res/drawable-[density]/</code>

folders. The Android system retains the resources in these density-specific folders, such as

mipmap-xxxhdpi, regardless of the screen resolution of the device where your app is installed. This

behavior allows launcher apps to pick the best resolution icon for your app to display on the home

screen. For more information about using the mipmap folders, see

<a href="{@docRoot}tools/project/index.html#mipmap">Managing Projects Overview</a>.

</p>

<p>The size and density configuration qualifiers correspond to the generalized sizes and densities

described in <a href="#range">Range of screens supported</a>, above.</p>

sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this

document.</p>

<p>For example, the following is a list of resource directories in an application that

provides different layout designs for different screen sizes and different bitmap drawables

for medium, high, and extra-high-density screens.</p>

<p>For example, the following application resource directories provide different layout designs

for different screen sizes and different drawables. Use the <code>mipmap/</code> folders for

launcher icons.</p>

<pre class="classic">

res/layout/my_layout.xml              // layout for normal screen size ("default")

res/layout-xlarge/my_layout.xml       // layout for extra-large screen size

res/layout-xlarge-land/my_layout.xml  // layout for extra-large in landscape orientation

res/drawable-mdpi/my_icon.png         // bitmap for medium-density

res/drawable-hdpi/my_icon.png         // bitmap for high-density

res/drawable-xhdpi/my_icon.png        // bitmap for extra-high-density

res/drawable-xxhdpi/my_icon.png       // bitmap for extra-extra-high-density

res/drawable-mdpi/graphic.png         // bitmap for medium-density

res/drawable-hdpi/graphic.png         // bitmap for high-density

res/drawable-xhdpi/graphic.png        // bitmap for extra-high-density

res/drawable-xxhdpi/graphic.png       // bitmap for extra-extra-high-density

res/mipmap-mdpi/my_icon.png         // launcher icon for medium-density

res/mipmap-hdpi/my_icon.png         // launcher icon for high-density

res/mipmap-xhdpi/my_icon.png        // launcher icon for extra-high-density

res/mipmap-xxhdpi/my_icon.png       // launcher icon for extra-extra-high-density

res/mipmap-xxxhdpi/my_icon.png      // launcher icon for extra-extra-extra-high-density

</pre>

<p>For more information about how to use alternative resources and a complete list of

Providing Alternative Resources</a>.</p>

<p>Be aware that, when the Android system picks which resources to use at runtime, it uses

certain logic to determing the "best matching" resources. That is, the qualifiers you use don't

certain logic to determine the "best matching" resources. That is, the qualifiers you use don't

have to exactly match the current screen configuration in all cases in order for the system to

use them. Specifically, when selecting resources based on the size qualifiers, the system will

use resources designed for a screen smaller than the current screen if there are no resources

smallest width your layout supports once it's complete.</p>

<p class="note"><strong>Note:</strong> Remember that all the figures used with these new size APIs

are density-indpendent pixel (dp) values and your layout dimensions should also always be defined

are density-independent pixel (dp) values and your layout dimensions should also always be defined

using dp units, because what you care about is the amount of screen space available after the system

accounts for screen density (as opposed to using raw pixel resolution). For more information about

density-indpendent pixels, read <a href="#terms">Terms and concepts</a>, earlier in this

density-independent pixels, read <a href="#terms">Terms and concepts</a>, earlier in this

document.</p>

a part of your application's window space, although your layout does not declare it, so it reduces

the space available for your layout and you must account for it in your design.</p>

<p class="table-caption"><strong>Table 2.</strong> New configuration qualifers for screen size

<p class="table-caption"><strong>Table 2.</strong> New configuration qualifiers for screen size

(introduced in Android 3.2).</p>

<table>

  <tr><th>Screen configuration</th><th>Qualifier values</th><th>Description</th></tr>

use this qualifier to ensure that, regardless of the screen's current orientation, your

application's has at least {@code &lt;N&gt;} dps of width available for its UI.</p>

        <p>For example, if your layout requires that its smallest dimension of screen area be at

least 600 dp at all times, then you can use this qualifer to create the layout resources, {@code

least 600 dp at all times, then you can use this qualifier to create the layout resources, {@code

res/layout-sw600dp/}. The system will use these resources only when the smallest dimension of

available screen is at least 600dp, regardless of whether the 600dp side is the user-perceived

height or width. The smallestWidth is a fixed screen size characteristic of the device; <strong>the

res/layout-sw720dp/main_activity.xml   # For 10” tablets (720dp wide and bigger)

</pre>

<p>Notice that the previous two sets of example resources use the "smallest width" qualifer, {@code

<p>Notice that the previous two sets of example resources use the "smallest width" qualifier, {@code

sw<N>dp}, which specifies the smallest of the screen's two sides, regardless of the

device's current orientation. Thus, using {@code sw<N>dp} is a simple way to specify the

overall screen size available for your layout by ignoring the screen's orientation.</p>

  <dt><a href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a></dt>

    <dd>Define various graphics with bitmaps or XML.<br/>

Saved in {@code res/drawable/} and accessed from the {@code R.drawable} class.</dd>

  <dt><a href="{@docRoot}guide/topics/resources/layout-resource.html">Layout Resource</a></dt>

    <dd>Define the layout for your application UI.<br/>

Saved in {@code res/layout/} and accessed from the {@code R.layout} class.</dd>

        MyActivity.java  </span>

    res/

        drawable/  <span style="color:black">

            icon.png  </span>

            graphic.png  </span>

        layout/  <span style="color:black">

            main.xml

            info.xml</span>

        mipmap/  <span style="color:black">

            icon.png </span>

        values/  <span style="color:black">

            strings.xml  </span>

</pre>

<p>As you can see in this example, the {@code res/} directory contains all the resources (in

subdirectories): an image resource, two layout resources, and a string resource file. The resource

subdirectories): an image resource, two layout resources, {@code mipmap/} directories for launcher

icons, and a string resource file. The resource

directory names are important and are described in table 1.</p>

<p class="note"><strong>Note:</strong> For more information about using the mipmap folders, see

<a href="{@docRoot}tools/project/index.html#mipmap">Managing Projects Overview</a>.</p>

<p class="table-caption" id="table1"><strong>Table 1.</strong> Resource directories

supported inside project {@code res/} directory.</p>

  <tr>

    <td><code>drawable/</code></td>

    <td><p>Bitmap files ({@code .png}, {@code .9.png}, {@code .jpg}, {@code .gif}) or XML files that

are compiled into the following drawable resource subtypes:</p>

      <ul>

    </td>

  </tr>

  <tr>

    <td><code>mipmap/</code></td>

    <td>Drawable files for different launcher icon densities. For more information on managing

    launcher icons with {@code mipmap/} folders, see

    <a href="{@docRoot}tools/project/index.html#mipmap">Managing Projects Overview</a>.</td>

  </tr>

  <tr>

    <td><code>layout/</code></td>

    <td>XML files that define a user interface layout.

page.title=Managing Projects Overview

meta.tags="project, mipmap"

page.tags="project", "mipmap"

@jd:body

 <div id="qv-wrapper">

      <ol>

        <li><a href="#ProjectFiles">Android Project Files</a></li>

        <li><a href="#ApplicationModules">Android Application Modules</a></li>

          <ol>

            <li><a href="#mipmap">Managing Launcher Icons as mipmap Resources</a></li>

          </ol>

        <li><a href="#LibraryModules">Library Modules</a>

          <ol>

            <li><a href="#considerations">Development considerations</a></li>

           focused). See the <a href=

           "{@docRoot}guide/topics/resources/drawable-resource.html">Drawable</a> resource type.</dd>

           <dt><code>mipmap/</code></dt>

           <dd>For app launcher icons. The Android system retains the resources in this folder

           (and density-specific folders such as mipmap-xxxhdpi) regardless of the screen resolution

           of the device where your app is installed. This behavior allows launcher apps to pick

           the best resolution icon for your app to display on the home screen. For more information

           about using the <code>mipmap</code> folders, see

           <a href="#mipmap">Managing Launcher Icons as mipmap Resources</a>. </p>

          <dt><code>layout/</code></dt>

           <dd>XML files that are compiled into screen layouts (or part of a screen). See the <a href=

<h2 id="mipmap">Managing Launcher Icons as mipmap Resources</h2>

<p>Different home screen launcher apps on different devices show app launcher icons at various

resolutions. When app resource optimization techniques remove resources for unused

screen densities, launcher icons can wind up looking fuzzy because the launcher app has to upscale

a lower-resolution icon for display. To avoid these display issues, apps should use the

<code>mipmap/</code> resource folders for launcher icons. The Android system

preserves these resources regardless of density stripping, and ensures that launcher apps can

pick icons with the best resolution for display. </p>

<p>Make sure launcher apps show a high-resolution icon for your app by moving all densities of your

launcher icons to density-specific <code>res/mipmap/</code> folders

(for example <code>res/mipmap-mdpi/</code> and <code>res/mipmap-xxxhdpi/</code>). The

<code>mipmap/</code> folders replace the <code>drawable/</code> folders for launcher icons. For

xxhpdi launcher icons, be sure to add the higher resolution xxxhdpi versions of the

icons to enhance the visual experience of the icons on higher resolution devices.</p>

<p class="note"><strong>Note:</strong> Even if you build a single APK for all devices, it is still

best practice to move your launcher icons to the <code>mipmap/</code> folders.</p>

<h3>Manifest update</h3>

<p>When you move your launcher icons to the <code>mipmap-[density]</code> folders, change the

launcher icon references in the <code>AndroidManifest.xml</code> file so your manifest references

the <code>mipmap/</code> location. This example changes the manifest file to reference the

<code>ic_launcher</code> icon in the <code>mipmap/</code> folder. </p>

<pre>

...

<application android:name="ApplicationTitle"

         android:label="@string/app_label"

         android:icon="@mipmap/ic_launcher" >

         ...

</pre>

  <h2 id="LibraryModules">Library Module</h2>

  <div class="sidebox-wrapper">