am 40132ee1: Merge "docs: site mipmap folder updates" into lmp-docs
* commit '40132ee15afbc45858b637410aecb861da60878a':
docs: site mipmap folder updates
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 @@
<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 @@
<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 @@
</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 @@
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-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 @@
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 @@
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 @@
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 @@
use this qualifier to ensure that, regardless of the screen's current orientation, your
application's has at least {@code <N>} 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-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>
@@ -1392,4 +1408,4 @@
<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 @@
<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 @@
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 @@
<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 @@
</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 @@
<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 @@
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 @@
+<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">
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 @@
<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 @@
<p>Then, any time you reference <code>@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>
