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

6 files changed, 153 insertions, 26 deletions

diff --git a/docs/html/design/style/iconography.jd b/docs/html/design/style/iconography.jd
index d212b06..1a92753 100644
--- a/docs/html/design/style/iconography.jd
+++ b/docs/html/design/style/iconography.jd
@@ -516,23 +516,41 @@ application: </p>
         <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 
+<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>
diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd
index 7ebda53..7c963dd 100644
--- a/docs/html/guide/practices/screens_support.jd
+++ b/docs/html/guide/practices/screens_support.jd
@@ -1,5 +1,5 @@
 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
@@ -348,13 +348,13 @@ can use for density-specific resources are <code>ldpi</code> (low), <code>mdpi</
 <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
@@ -362,6 +362,16 @@ 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>
 
@@ -538,9 +548,9 @@ screen sizes (instead of using the size qualifiers in table 1).</p></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")
@@ -548,10 +558,16 @@ res/layout-large/my_layout.xml        // layout for large screen size
 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
@@ -560,7 +576,7 @@ configuration qualifiers (not just for screen configurations), see
 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
@@ -703,10 +719,10 @@ such, you can now specify that these layout resources should be used only when t
 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>
 
 
@@ -728,7 +744,7 @@ Also beware that the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action B
 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>
@@ -745,7 +761,7 @@ height and width (you may also think of it as the "smallest possible width" for
 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
@@ -851,7 +867,7 @@ res/layout-sw600dp/main_activity.xml   # For 7” tablets (600dp wide and bigger
 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&lt;N&gt;dp}, which specifies the smallest of the screen's two sides, regardless of the
 device's current orientation. Thus, using {@code sw&lt;N&gt;dp} is a simple way to specify the
 overall screen size available for your layout by ignoring the screen's orientation.</p>
@@ -1392,4 +1408,4 @@ between 0.1 and 3 that represents the desired scaling factor.</p>
 
 <p>For more information about creating AVDs from the command line, see <a
 href="{@docRoot}tools/devices/managing-avds-cmdline.html">Managing AVDs from the
-Command Line</a>.</p>
\ No newline at end of file
+Command Line</a>.</p>
diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd
index 19babee..db1bf8d 100644
--- a/docs/html/guide/topics/resources/available-resources.jd
+++ b/docs/html/guide/topics/resources/available-resources.jd
@@ -29,6 +29,7 @@ Saved in {@code res/color/} and accessed from the {@code R.color} class.</dd>
   <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>
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd
index 6d9527f..98e7c96 100644
--- a/docs/html/guide/topics/resources/providing-resources.jd
+++ b/docs/html/guide/topics/resources/providing-resources.jd
@@ -60,18 +60,24 @@ MyProject/
         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>
 
@@ -104,6 +110,7 @@ State List Resource</a></td>
 
   <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>
@@ -119,6 +126,13 @@ are compiled into the following drawable resource subtypes:</p>
   </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.
         See <a href="layout-resource.html">Layout Resource</a>.</td>
diff --git a/docs/html/tools/projects/index.jd b/docs/html/tools/projects/index.jd
index 5f4f2cc..8665479 100644
--- a/docs/html/tools/projects/index.jd
+++ b/docs/html/tools/projects/index.jd
@@ -1,4 +1,6 @@
 page.title=Managing Projects Overview
+meta.tags="project, mipmap"
+page.tags="project", "mipmap"
 @jd:body
 
  <div id="qv-wrapper">
@@ -8,7 +10,9 @@ page.title=Managing Projects Overview
       <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>
@@ -230,7 +234,18 @@ project and override similar module file settings.</p>
            focused). See the <a href=
            "{@docRoot}guide/topics/resources/drawable-resource.html">Drawable</a> resource type.</dd>
 
-           <dt><code>layout/</code></dt>
+
+           <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=
            "{@docRoot}guide/topics/resources/layout-resource.html">Layout</a> resource type.</dd>
@@ -304,6 +319,46 @@ project and override similar module file settings.</p>
 
 
 
+<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>
+...
+&lt;application android:name="ApplicationTitle"
+         android:label="@string/app_label"
+         android:icon="@mipmap/ic_launcher" &gt;
+         ...
+</pre>
+
+
+
+
+
   <h2 id="LibraryModules">Library Module</h2>
 
   <div class="sidebox-wrapper">
diff --git a/docs/html/training/multiscreen/screendensities.jd b/docs/html/training/multiscreen/screendensities.jd
index fcb65cc..1fc5904 100644
--- a/docs/html/training/multiscreen/screendensities.jd
+++ b/docs/html/training/multiscreen/screendensities.jd
@@ -28,6 +28,7 @@ next.link=adaptui.html
 
 <ul>
   <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+  <li><a href="{@docRoot}design/style/iconography.html">Iconography</a></li>
   <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
 Guidelines</a></li>
 </ul>
@@ -133,6 +134,28 @@ MyProject/
 <p>Then, any time you reference <code>&#64;drawable/awesomeimage</code>, the system selects the
 appropriate bitmap based on the screen's dpi.</p>
 
+<p>Place your launcher icons in the <code>mipmap/</code> folders. </p>
+
+<pre>res/...
+    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 class="note"><strong>Note:</strong> You should place all launcher icons in the
+<code>res/mipmap-[density]/</code> folders, rather than <code>drawable/</code> folders to ensure
+launcher apps use the best resolution icon. For more information about using the mipmap folders, see
+<a href="{@docRoot}tools/project/index.html#mipmap">Managing Projects Overview</a>.</p>
+
 <p>For more tips and guidelines for creating icon assets for your application, see the <a
 href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
 Guidelines</a>.</p>