docs: add guide for optimizing tablet apps for handsets

deprecate "optimizing for 3.0" doc

Change-Id: I290ff5cd22c714e639fb820251c9e1d763f750df

Author: scottamain

docs/html/guide/guide_toc.cs

@@ -715,9 +715,9 @@ localized titles are added in the language order specified below.
           </a></li>
         </ul>
       </li>
-      <li><a href="<?cs var:toroot ?>guide/practices/optimizing-for-3.0.html">
-            <span class="en">Optimizing Apps for Android 3.0</span>
-          </a></li>
+      <li><a href="<?cs var:toroot ?>guide/practices/tablets-and-handsets.html">
+            <span class="en">Supporting Tablets and Handsets</span>
+          </a> <span class="new">new!</span></li>
       <li class="toggle-list">
         <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html">
                <span class="en">UI Guidelines</span>

docs/html/guide/practices/optimizing-for-3.0.jd

@@ -1,6 +1,31 @@
 page.title=Optimizing Apps for Android 3.0
 @jd:body
 
+
+<div id="deprecatedSticker">
+  <a href="#" 
+     onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false">
+    <strong>This doc is deprecated</strong></a>
+</div>
+
+
+<div id="naMessage" style="display:block">
+<div><p><strong>This document has been deprecated.</strong></p>
+ <p>To learn about how you can  optimize your app for both tablets and handsets, please
+read the guide to <a href="tablets-and-handsets.html">Supporting Tablets and
+Handsets</a>.</p>
+
+ <input style="margin-top:1em;padding:5px" type="button"
+        value="That's nice, but I still want to read this document"
+onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" />
+</div>
+</div>
+
+
+
+
+
+
 <div id="qv-wrapper">
 <div id="qv">
 <h2>In this document</h2>
@@ -25,6 +50,8 @@ page.title=Optimizing Apps for Android 3.0
 <h2>See also</h2>
 
 <ol>
+  <li><a href="tablets-and-handsets.html">Supporting Tablets
+and Handsets</a></li>
   <li><a
 href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a></li>
   <li><a href="http://code.google.com/p/iosched/">Google I/O App source code</a></li>

docs/html/guide/practices/screens-distribution.jd

@@ -15,8 +15,8 @@ screen configuration</li>
 
   <h2>In this document</h2>
   <ol>
-    <li><a href="#FilteringHansetApps">Filtering a Handset Application from Tablets</a></li>
-    <li><a href="#FilteringTabletApps">Filtering a Tablet Application from Handsets</a></li>
+    <li><a href="#FilteringHansetApps">Declaring an App is Only for Handsets</a></li>
+    <li><a href="#FilteringTabletApps">Declaring an App is Only for Tablets</a></li>
     <li><a href="#MultiApks">Publishing Multiple APKs for Different Screens</a></li>
   </ol>
 
@@ -48,7 +48,7 @@ available to the greatest number of users with different devices, using a single
 
 
 
-<h2 id="FilteringHandsetApps">Filtering a Handset Application from Tablets</h2>
+<h2 id="FilteringHandsetApps">Declaring an App is Only for Handsets</h2>
 
 <p>Because the system generally scales applications to fit larger screens well, you shouldn't
 need to filter your application from larger screens. As long as you follow the <a
@@ -79,7 +79,6 @@ entry looks like if your application is compatible with only small and normal sc
 
 <pre>
 &lt;manifest ... >
-    ...
     &lt;compatible-screens>
         &lt;!-- all small size screens -->
         &lt;screen android:screenSize="small" android:screenDensity="ldpi" />
@@ -92,6 +91,7 @@ entry looks like if your application is compatible with only small and normal sc
         &lt;screen android:screenSize="normal" android:screenDensity="hdpi" />
         &lt;screen android:screenSize="normal" android:screenDensity="xhdpi" />
     &lt;/compatible-screens>
+    ...
     &lt;application ... >
         ...
     &lt;application>
@@ -108,36 +108,66 @@ to specify each screen density your application supports.</p>
 
 
 
-<h2 id="FilteringTabletApps">Filtering a Tablet Application from Handsets</h2>
 
-<p>If your application's UI is adversely affected when the system scales your application down to
-smaller screens, you should add <a
-href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
-layouts</a> for smaller screens to adjust the layout for those screens. However, sometimes your
-layout still might not fit a smaller screen or you've explicitly designed your application only for
-tablets and other large devices. In this case, you can manage the availability of your application
-to smaller screens by using the <a
+<h2 id="FilteringTabletApps">Declaring an App is Only for Tablets</h2>
+
+<p>If you don't want your app to be used on handsets (perhaps your app truly makes sense only on a
+large screen) or you need time to optimize it for smaller screens, you can prevent small-screen
+devices from downloading your app by using the <a
 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
 &lt;supports-screens>}</a> manifest element.</p>
 
-<p>For example, if you want your application to be available only to large and extra large
-screens, you can declare the element in your manifest like this:</p>
+<p>For example, if you want your application to be available only to tablet devices, you can declare
+the element in your manifest like this:</p>
 
 <pre>
 &lt;manifest ... >
-    ...
     &lt;supports-screens android:smallScreens="false"
                       android:normalScreens="false"
                       android:largeScreens="true"
-                      android:xlargeScreens="true" /&gt;
+                      android:xlargeScreens="true"
+                      android:requiresSmallestWidthDp="600" />
+    ...
     &lt;application ... >
         ...
-    &lt;application>
+    &lt;/application>
 &lt;/manifest>
 </pre>
 
-<p>External services such as Android Market read this manifest element and use it to ensure that
-your application is available only to devices with either a large or an extra large screen.</p>
+<p>This describes your app's screen-size support in two different ways:</p>
+
+<ul>
+  <li>It declares that the app does <em>not</em> support the screen sizes "small" and
+"normal", which are traditionally not tablets.</li>
+  <li>It declares that the app requires a screen size with a minimum usable area that is at least
+600dp wide.</li>
+</ul>
+
+<p>The first technique is for devices that are running Android 3.1 or older, because those devices
+declare their size based on generalized screen sizes. The <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html#requiresSmallest">{@code
+requiresSmallestWidthDp}</a> attribute is for devices running Android 3.2 and newer, which includes
+the capability for apps to specify size requirements based on a minimum number of
+density-independent pixels available.  In this example, the app declares a minimum width requirement
+of 600dp, which generally implies a 7"-or-greater screen. </p>
+
+<p>Your size choice might be different, of course, based on how well your design works on different
+screen sizes; for example, if your design works well only on screens that are 9" or larger, you
+might require a minimum width of 720dp.</p>
+
+<p>The catch is that you must compile your application against Android 3.2 or higher in order to use
+the <code>requiresSmallestWidthDp</code> attribute. Older versions don't understand this attribute
+and will raise a compile-time error. The safest thing to do is develop your app against the platform
+that matches the API level you've set for <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">minSdkVersion</a
+>. When you're making final preparations to build your release candidate, change the build target to
+Android 3.2 and add the <code>requiresSmallestWidthDp</code> attribute. Android versions older than
+3.2 simply ignore that XML attribute, so there's no risk of a runtime failure.</p>
+
+<p>For more information about why the "smallest width" screen size is
+important for supporting different screen sizes, read <a
+href="http://android-developers.blogspot.com/2011/07/new-tools-for-managing-screen-sizes.html">New
+Tools for Managing Screen Sizes</a>.</p>
 
 <p class="caution"><strong>Caution:</strong> If you use the <a
 href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
@@ -151,7 +181,7 @@ information). If you want
 to prevent your application from being downloaded on larger screens, use <a
 href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
 &lt;compatible-screens>}</a>, as discussed in the previous section about <a
-href="#FilteringHandsetApps">Filtering a Handset Application from Tablets</a>.</p>
+href="#FilteringHandsetApps">Declaring an App is Only for Handsets</a>.</p>
 
 <p>Remember, you should strive to make your application available to as many devices as possible by
 applying all necessary techniques for <a

docs/html/guide/practices/screens_support.jd

@@ -50,6 +50,9 @@ Resolutions</a></li>
   <h2>See also</h2>
   <ol>
     <li><a
+href="http://android-developers.blogspot.com/2011/09/thinking-like-web-designer.html">Thinking
+Like a Web Designer</a></li>
+    <li><a
 href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
 Providing Alternative Resources</a></li>
     <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design